Custom Twig Extensions (#49)

* Adding the ability to load custom Twig Extensions

* Adding Twig Extension docs and example

README.md

@@ -319,6 +319,52 @@ This tag would be used like this in a pattern:
 {{ name }}
 ```
 
+### Adding a custom Twig Extension
+
+A [Twig Extension](https://twig.symfony.com/doc/1.x/advanced.html#creating-an-extension) is a collection of Twig functions, filters, tags, globals, and tests all as a single bundle. This approach is more advanced than adding a single function or filter using the above method, but allows greater flexibility as the whole Twig Extension can be installed in multiple environments.
+
+To add a Twig Extension using the PHP class `\MyProject\MyCustomTwigExtension`, add this to `config.yml`:
+
+```yml
+twigExtensions:
+ - '\MyProject\MyCustomTwigExtension'
+```
+
+What happens under the hood is basically this:
+
+```php
+$twig = new Twig_Environment($loader);
+
+foreach ($twigExtensions as $twigExtension) {
+ $twig->addExtension(new $twigExtension());
+}
+```
+
+If two Twig Extensions declare a function, filter, etc; the later ones override earlier ones. Any ones declared in Pattern Lab's `_twig-components` folder will override any declared using this method of custom Twig Extensions.
+
+For an example of how this works, see `ExampleTwigExtension.php` in this repo. You can enable it by adding this to your `config.yml`:
+
+```yml
+twigExtensions:
+ - '\PatternLab\PatternEngine\Twig\ExampleTwigExtension'
+```
+
+Then place this in any Twig file:
+
+```twig
+<p>Testing: {{ testPlFunction('testing...') }}</p>
+```
+
+That function declaration looks like this in `ExampleTwigExtension.php`:
+
+```php
+new Twig_SimpleFunction('testPlFunction', function($arg) {
+ return 'Thanks for testing out the Pattern Lab Example Twig Extension with this arg: ' . $arg;
+}),
+```
+
+An incredible amount of exciting possibilities are enabled with this; have fun!
+
 ### Enable `dump()`
 
 To use `dump()` set `twigDebug` in `config/config.yml` to `true`.

src/PatternLab/PatternEngine/Twig/ExampleTwigExtension.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace PatternLab\PatternEngine\Twig;
+
+use Twig_Extension;
+use Twig_ExtensionInterface;
+use Twig_SimpleFilter;
+use Twig_SimpleFunction;
+
+class ExampleTwigExtension extends Twig_Extension implements Twig_ExtensionInterface {
+
+ /**
+ * Returns the name of the extension.
+ *
+ * @return string The extension name
+ *
+ * @deprecated since 1.26 (to be removed in 2.0), not used anymore internally
+ */
+ function getName() {
+ return 'Pattern Lab Twig ExampleTwigExtension';
+ }
+
+ /**
+ * Returns a list of filters to add to the existing list.
+ *
+ * @return Twig_SimpleFilter[]
+ */
+ function getFilters() {
+ return [];
+ }
+
+ /**
+ * Returns a list of functions to add to the existing list.
+ *
+ * @return Twig_SimpleFunction[]
+ */
+ function getFunctions() {
+ return [
+ new Twig_SimpleFunction('testPlFunction', function($arg) {
+ return 'Thanks for testing out the Pattern Lab Example Twig Extension with this arg: ' . $arg;
+ }),
+ ];
+ }
+
+ /**
+ * Returns a list of operators to add to the existing list.
+ *
+ * @return array<array> First array of unary operators, second array of binary operators
+ */
+ function getOperators() {
+ return [];
+ }
+
+ /**
+ * Returns a list of global variables to add to the existing list.
+ *
+ * @return array An array of global variables
+ *
+ * @deprecated since 1.23 (to be removed in 2.0), implement Twig_Extension_GlobalsInterface instead
+ */
+ function getGlobals() {
+ return [
+ 'pl' => 'is awesome',
+ ];
+ }
+
+ /**
+ * Returns a list of tests to add to the existing list.
+ *
+ * @return Twig_SimpleTest[]
+ */
+ function getTests() {
+ return [];
+ }
+ /**
+ * Returns the token parser instances to add to the existing list.
+ *
+ * @return (Twig_TokenParserInterface|Twig_TokenParserBrokerInterface)[]
+ */
+ function getTokenParsers() {
+ return [];
+ }
+
+ /**
+ * Returns the node visitor instances to add to the existing list.
+ *
+ * @return Twig_NodeVisitorInterface[]
+ */
+ function getNodeVisitors() {
+ return [];
+ }
+
+}

src/PatternLab/PatternEngine/Twig/Loaders/FilesystemLoader.php

@@ -50,6 +50,7 @@ public function __construct($options = array()) {
 
  // customize Twig
  TwigUtil::setInstance($instance);
+ TwigUtil::loadCustomExtensions();
  TwigUtil::loadFilters();
  TwigUtil::loadFunctions();
  TwigUtil::loadTags();

src/PatternLab/PatternEngine/Twig/Loaders/PatternLoader.php

@@ -92,6 +92,7 @@ public function __construct($options = array()) {
 
  // customize Twig
  TwigUtil::setInstance($instance);
+ TwigUtil::loadCustomExtensions();
  TwigUtil::loadFilters();
  TwigUtil::loadFunctions();
  TwigUtil::loadTags();

src/PatternLab/PatternEngine/Twig/Loaders/StringLoader.php

@@ -56,6 +56,7 @@ public function __construct($options = array()) {
 
  // customize Twig
  TwigUtil::setInstance($instance);
+ TwigUtil::loadCustomExtensions();
  TwigUtil::loadFilters();
  TwigUtil::loadFunctions();
  TwigUtil::loadTags();

src/PatternLab/PatternEngine/Twig/TwigUtil.php

@@ -50,6 +50,27 @@ public static function setInstance($instance = "") {
 
  }
 
+ /**
+ * Load Custom Twig Extensions
+ * Looks in config for an array of strings that are classes that can be called and implements the interface `Twig_ExtensionInterface`
+ * Config example:
+ * twigExtensions:
+ * - '\MyProject\MyCustomTwigExtension'
+ * @link https://twig.symfony.com/doc/1.x/advanced.html#creating-an-extension
+ */
+ public static function loadCustomExtensions() {
+ $twigExtensions = Config::getOption("twigExtensions");
+ if ($twigExtensions) {
+ foreach ($twigExtensions as $twigExtension) {
+ if (class_exists($twigExtension)) {
+ self::$instance->addExtension(new $twigExtension());
+ } else {
+ Console::writeError("Your custom Twig Extension setting isn't a PHP class that exists: `" . $twigExtension . "`");
+ }
+ }
+ }
+ }
+
  /**
  * Get an instance of the Twig loaders
  *