Add an optional unresolved variable error handler callback (closes #4)

Author: wol-soft

README.md

@@ -134,6 +134,17 @@ $render->renderTemplateString(
 );
 ```
 
+By default, a used variable which is not provided will result in an `UndefinedSymbolException`. You can register a callback function via `onResolveError` to handle unresolved variable errors. The callback function must implement the signature `function (string $unresolvedVariable): string`. The provided `$unresolvedVariable` will contain the whole expression which failed to resolve (eg. `myUnresolvedVariable`, `myUnresolvedObject.render(var1, var2)`).
+
+```php
+$render->onResolveError(function (string $var): string {
+    return 'Undefined';
+});
+
+// will result in "Person name: Undefined"
+$result = $render->renderTemplateString('Person name: {{ name }}');
+```
+
 ### Loops
 
 If you assign an array or an iterable object you can use the *foreach* loop to iterate.

src/Render.php

@@ -19,12 +19,14 @@
  */
 class Render
 {
-    private const REGEX_VARIABLE = '(?<variable>\w+)(?<nestedVariable>(\.\w+)*)(\.(?<method>\w+)\((?<parameter>[^{}%]*)\))?';
+    private const REGEX_VARIABLE = '(?<expression>(?<variable>\w+)(?<nestedVariable>(\.\w+)*?)(\.(?<method>\w+)\((?<parameter>[^{}%]*)\))?)';
 
     /** @var array */
     private $templates = [];
     /** @var string */
     private $basePath = '';
+    /** @var callable */
+    private $resolveErrorCallback;
 
     /**
      * Render constructor.
@@ -37,6 +39,21 @@ public function __construct(string $basePath = '')
         $this->basePath = $basePath;
     }
 
+    /**
+     * Add a callback to handle resolve errors (eg. call to an unknown variable). By default a resolve error will lead
+     * to an UnknownSymbolException.
+     *
+     * @param callable $resolveErrorCallback
+     *
+     * @return $this
+     */
+    public function onResolveError(callable $resolveErrorCallback): self
+    {
+        $this->resolveErrorCallback = $resolveErrorCallback;
+
+        return $this;
+    }
+
     /**
      * Render a template file
      *
@@ -224,6 +241,10 @@ protected function getValue(array $matches, array $variables)
         foreach ($variablePath as $variable) {
             // first check via isset for faster lookup
             if (!isset($resolved[$variable]) && !array_key_exists($variable, $resolved)) {
+                if ($this->resolveErrorCallback) {
+                    return ($this->resolveErrorCallback)($matches['expression']);
+                }
+
                 throw new UndefinedSymbolException(sprintf('Unknown variable %s', implode('.', $variablePath)));
             }
 

tests/RenderTest.php

@@ -257,4 +257,30 @@ public function renderName(string $firstName, string $lastName): string
             )
         );
     }
+
+    /**
+     * @dataProvider resolveErrorDataProvider
+     *
+     * @param string $var
+     */
+    public function testResolveErrorCallback(string $var): void
+    {
+        $this->render->onResolveError(function (string $resolveError) use ($var): string {
+            $this->assertSame($var, $resolveError);
+
+            return 'callback-result';
+        });
+
+        $this->assertSame('callback-result', $this->render->renderTemplateString("{{ $var }}"));
+    }
+
+    public function resolveErrorDataProvider()
+    {
+        return [
+            'simple variable' => ['person'],
+            'nested variable' => ['person.name'],
+            'object function call' => ['person.renderName()'],
+            'object function call with parameters' => ['person.renderName(firstname, lastname)'],
+        ];
+    }
 }