Add escapeExpression method and document SafeString usage

Author: theodorejb

README.md

@@ -103,6 +103,15 @@ echo $template(['my_var' => 1]); // Not equal
 echo $template(['my_var' => null]); // Not equal
 ```
 
+## String Escaping
+
+If a custom helper is executed in a `{{ }}` expression, the return value will be HTML escaped.
+When a helper is executed in a `{{{ }}}` expression, the original return value will be output directly.
+
+Helpers may return a `DevTheorem\Handlebars\SafeString` instance to prevent escaping the return value.
+When constructing the string that will be marked as safe, any external content should be properly escaped
+using the `Handlebars::escapeExpression()` method to avoid potential security concerns.
+
 ## Unsupported Features
 
 * `{{foo/bar}}` style variables (deprecated in official Handlebars.js). Instead use: `{{foo.bar}}`.

src/Compiler.php

@@ -15,6 +15,7 @@ final class Compiler extends Validator
      */
     public static function compileTemplate(Context $context, string $template): string
     {
+        $template = addcslashes($template, '\\');
         array_unshift($context->parsed, []);
         Validator::verify($context, $template);
         static::$lastParsed = $context->parsed;

src/Encoder.php

@@ -25,7 +25,7 @@ public static function precompile(string $template, Options $options = new Optio
         $context = new Context($options);
         static::handleError($context);
 
-        $code = Compiler::compileTemplate($context, SafeString::escapeTemplate($template));
+        $code = Compiler::compileTemplate($context, $template);
         static::$lastParsed = Compiler::$lastParsed;
         static::handleError($context);
 
@@ -41,6 +41,19 @@ public static function template(string $templateSpec): \Closure
         return eval($templateSpec);
     }
 
+    /**
+     * HTML escapes the passed string, making it safe for rendering as text within HTML content.
+     * The output of all expressions except for triple-braced expressions are passed through this method.
+     * Helpers should also use this method when returning HTML content via a SafeString instance,
+     * to prevent possible code injection.
+     */
+    public static function escapeExpression(string $string): string
+    {
+        $search = ['&', '<', '>', '"', "'", '`', '='];
+        $replace = ['&amp;', '&lt;', '&gt;', '&quot;', '&#x27;', '&#x60;', '&#x3D;'];
+        return str_replace($search, $replace, $string);
+    }
+
     /**
      * @throws \Exception
      */

src/Handlebars.php

@@ -7,6 +7,8 @@
  */
 final class Parser
 {
+    public const IS_SUBEXP_SEARCH = '/^\(.+\)$/s';
+
     // Compile time error handling flags
     public const BLOCKPARAM = 9999;
     public const PARTIALBLOCK = 9998;
@@ -179,7 +181,7 @@ public static function parse(array $token, Context $context): array
      */
     public static function getPartialName(array $vars, int $pos = 0): ?array
     {
-        if (!isset($vars[$pos]) || preg_match(SafeString::IS_SUBEXP_SEARCH, $vars[$pos])) {
+        if (!isset($vars[$pos]) || preg_match(static::IS_SUBEXP_SEARCH, $vars[$pos])) {
             return null;
         }
         assert(is_string($vars[$pos]));
@@ -229,14 +231,14 @@ protected static function advancedVariable(array $vars, Context $context, string
         $i = 0;
         foreach ($vars as $idx => $var) {
             // handle (...)
-            if (preg_match(SafeString::IS_SUBEXP_SEARCH, $var)) {
+            if (preg_match(static::IS_SUBEXP_SEARCH, $var)) {
                 $ret[$i] = static::subexpression($var, $context);
                 $i++;
                 continue;
             }
 
             // handle |...|
-            if (preg_match(SafeString::IS_BLOCKPARAM_SEARCH, $var, $matched)) {
+            if (preg_match('/^ +\|(.+)\|$/s', $var, $matched)) {
                 $ret[static::BLOCKPARAM] = preg_split('/\s+/', trim($matched[1]));
                 continue;
             }
@@ -245,7 +247,7 @@ protected static function advancedVariable(array $vars, Context $context, string
                 $idx = $m[3] ?: $m[4];
                 $var = $m[5];
                 // handle foo=(...)
-                if (preg_match(SafeString::IS_SUBEXP_SEARCH, $var)) {
+                if (preg_match(static::IS_SUBEXP_SEARCH, $var)) {
                     $ret[$idx] = static::subexpression($var, $context);
                     continue;
                 }

src/Parser.php

@@ -32,7 +32,7 @@ public static function read(Context $context, string $name): void
         $cnt = static::resolve($context, $name);
 
         if ($cnt !== null) {
-            $context->usedPartial[$name] = SafeString::escapeTemplate($cnt);
+            $context->usedPartial[$name] = $cnt;
             static::compileDynamic($context, $name);
             return;
         }

src/Partial.php

@@ -60,19 +60,17 @@ public static function isec(mixed $v): bool
     }
 
     /**
-     * For {{var}} , do html encode just like handlebars.js .
+     * HTML encode {{var}} just like handlebars.js
      *
      * @param array<array<mixed>|string|int>|string|SafeString|int|null $var value to be htmlencoded
-     *
-     * @return string The htmlencoded value of the specified variable
      */
     public static function encq($var): string
     {
         if ($var instanceof SafeString) {
             return (string) $var;
         }
 
-        return Encoder::encq($var);
+        return Handlebars::escapeExpression(static::raw($var));
     }
 
     /**

src/Runtime.php

@@ -2,34 +2,22 @@
 
 namespace DevTheorem\Handlebars;
 
+/**
+ * Can be returned from a custom helper to prevent an HTML string from being escaped
+ * when the template is rendered. When constructing, any external content should be
+ * properly escaped using Handlebars::escapeExpression() to avoid potential security concerns.
+ */
 class SafeString implements \Stringable
 {
-    public const EXTENDED_COMMENT_SEARCH = '/{{!--.*?--}}/s';
-    public const IS_SUBEXP_SEARCH = '/^\(.+\)$/s';
-    public const IS_BLOCKPARAM_SEARCH = '/^ +\|(.+)\|$/s';
-
     private string $string;
 
     public function __construct(string $string)
     {
         $this->string = $string;
     }
 
-    public function __toString()
+    public function __toString(): string
     {
         return $this->string;
     }
-
-    /**
-     * Strip extended comments {{!-- .... --}}
-     */
-    public static function stripExtendedComments(string $template): string
-    {
-        return preg_replace(static::EXTENDED_COMMENT_SEARCH, '{{! }}', $template);
-    }
-
-    public static function escapeTemplate(string $template): string
-    {
-        return addcslashes($template, '\\');
-    }
 }

src/SafeString.php

@@ -7,12 +7,22 @@
  */
 class Validator
 {
+    public const EXTENDED_COMMENT_SEARCH = '/{{!--.*?--}}/s';
+
+    /**
+     * Strip extended comments {{!-- .... --}}
+     */
+    public static function stripExtendedComments(string $template): string
+    {
+        return preg_replace(static::EXTENDED_COMMENT_SEARCH, '{{! }}', $template);
+    }
+
     /**
      * Verify template
      */
     public static function verify(Context $context, string $template): void
     {
-        $template = SafeString::stripExtendedComments($template);
+        $template = static::stripExtendedComments($template);
         $context->level = 0;
         Token::setDelimiter($context);