Merge branch 'develop' into composer

CHANGELOG.md

@@ -0,0 +1,37 @@
+Kirby Twig Plugin: Change log
+=============================
+
+v3.0.0
+------
+
+**Breaking changes:**
+
+- Removed the `twig.env.classes` option and `new()` Twig function.
+- Twig’s template cache is now disabled by default (enable with `c::set('twig.cache', true);`).
+- Error reporting: the `twig.error` config key is now ignored. Instead, the site’s main error page (whose URI is `error` by default) will be used in some specific situations. See `doc/errors.md` for details.
+- Namespace and class names (and sometimes methods) have changed (again); there is now a `Kirby\Twig\Plugin` class which will act as a stable API, while other implementation details may change.
+
+Deprecated (still working):
+
+- `twig.env.functions` in favor of `twig.function.myFunction`;
+- `twig.env.filters` in favor of `twig.filter.myFilter`;
+- `twig.env.namespace.xyz` in favor of `twig.namespace.xyz`.
+
+v2.x
+----
+
+See on GitHub:
+
+- [v2.1.2](https://github.com/fvsch/kirby-twig/releases/tag/v2.1.2)
+- [v2.1.1](https://github.com/fvsch/kirby-twig/releases/tag/v2.1.1)
+- [v2.1.0](https://github.com/fvsch/kirby-twig/releases/tag/v2.1.0)
+- [v2.0.2](https://github.com/fvsch/kirby-twig/releases/tag/v2.0.2)
+- [v2.0.1](https://github.com/fvsch/kirby-twig/releases/tag/v2.0.1)
+- [v2.0.0](https://github.com/fvsch/kirby-twig/releases/tag/v2.0.0)
+
+v1.x
+----
+
+- [v1.3.0](https://github.com/fvsch/kirby-twig/releases/tag/v1.3.0)
+- [v1.2.0](https://github.com/fvsch/kirby-twig/releases/tag/v1.2.0)
+- [v1.0.0](https://github.com/fvsch/kirby-twig/releases/tag/v1.0.0)

doc/functions.md

@@ -4,16 +4,32 @@ Using your own functions in templates
 
 If you need to expose PHP functions (or static class methods) to your Twig templates, you can list them with those options:
 
-- `twig.env.functions`
-- `twig.env.filters`
+- `twig.function.*`
+- `twig.filter.*`
 
 As with any option in Kirby, you should define these options in your `site/config/config.php`. Let’s show how each option works.
 
 
 Exposing a function
 -------------------
 
-For example if you have a custom function defined in your own plugin file (`site/plugins/myplugin.php`):
+The expected syntax for these configuration options is:
+
+```php
+// In site/config/config.php:
+c::set('twig.function.myFunctionName', $someFunction);
+```
+
+Where:
+
+-   `myFunctionName` is any name you want (only letters and underscores), and is the name that will be available in your Twig templates.
+-   `$someFunction` can be a string, or a Closure.
+
+Let’s use more tangible examples.
+
+### Using a function name (string)
+
+If you have a custom function defined in a plugin file (e.g. `site/plugins/myplugin.php`):
 
 ```php
 <?php
@@ -23,14 +39,14 @@ For example if you have a custom function defined in your own plugin file (`site
  * @return string
  */
 function sayHello($who='') {
-    return 'Hello' . (is_string($who) ? ' ' . $who : '');
+  return 'Hello' . (is_string($who) ? ' ' . $who : '');
 }
 ```
 
 You can make it available as a Twig function:
 
 ```php
-c::set('twig.env.functions', ['sayHello']);
+c::set('twig.function.sayHello', 'sayHello');
 ```
 
 ```twig
@@ -41,7 +57,7 @@ c::set('twig.env.functions', ['sayHello']);
 Or you could expose it as a Twig filter:
 
 ```php
-c::set('twig.env.filters', ['sayHello']);
+c::set('twig.filter.sayHello', 'sayHello');
 ```
 
 ```twig
@@ -51,23 +67,30 @@ c::set('twig.env.filters', ['sayHello']);
 
 I recommend sticking to the Twig function syntax, and only using Twig’s built-in filters. Of course, you should do what you like best.
 
+### Using an anonymous function
 
-Exposing static methods
------------------------
-
-If you just need a couple static methods, you can use the same solution:
+The `twig.function.*` and `twig.filter.*` configs accept anonymous functions (called closures in PHP):
 
 ```php
-c::set('twig.env.functions', ['cookie::set', 'cookie::get']);
+c::set('twig.function.sayHello', function($who='') {
+    return 'Hello' . (is_string($who) ? ' ' . $who : '');
+}
 ```
 
-Note that the `::` will be replaced by two underscores (`__`).
+### Exposing static methods
+
+You can also expose static methods, using the string syntax:
+
+```php
+c::set('twig.function.setCookie', 'Cookie::set');
+c::set('twig.function.getCookie', 'Cookie::get');
+```
 
 ```twig
-{% do cookie__set('test', 'real value') %}
+{% do setCookie('test', 'real value') %}
 
 {# Prints 'real value' #}
-{{ cookie__get('test', 'fallback') }}
+{{ getCookie('test', 'fallback') }}
 ```
 
 
@@ -87,20 +110,16 @@ Let’s look at an example of that second solution:
 // site/plugins/coolplugin/src/verycoolthing.php
 class VeryCoolThing
 {
-    // class implementation
-}
-
-// site/plugins/coolplugin/helpers.php
-function getCoolStuff()
-{
-    return new VeryCoolThing();
+  // class implementation
 }
 
 // site/config/config.php
-c::set('twig.env.functions', ['getCoolStuff']);
+c::set('twig.function.getCoolStuff', function(){
+  return new VeryCoolThing();
+});
 ```
 
-Then in your templates, you can use that helper function to get a class instance:
+Then in your templates, you can use that function to get a class instance:
 
 ```twig
 {% set coolThing = getCoolStuff() %}
@@ -115,8 +134,10 @@ Alternatively, you could define and expose a generic function that allows instan
 
 /**
  * Make a class instance for the provided class name and parameters
+ * Giving this function the name 'new' in Twig templates, for
+ * backwards compatibility with Kirby Twig 2.x.
  */
-function makeInstance($name) {
+c::set('twig.function.new', function($name) {
   if (!class_exists($name)) {
     throw new Twig_Error_Runtime("Unknown class \"$name\"");
   }
@@ -126,13 +147,11 @@ function makeInstance($name) {
     return $reflected->newInstanceArgs($args);
   }
   return new $name;
-}
-
-c::set('twig.env.functions', ['makeInstance']);
+});
 ```
 
 Then in Twig templates:
 
 ```twig
-{% set coolThing = makeInstance('VeryCoolThing') %}
+{% set coolThing = new('VeryCoolThing') %}
 ```

doc/options.md

@@ -2,19 +2,6 @@ Options documentation
 =====================
 
 
-Basic options
--------------
-
-```php
-// REQUIRED: activate Twig plugin
-c::set('twig', true);
-
-// Should we use .php templates as fallback when .twig
-// templates don't exist? Set to false to only allow Twig templates
-c::set('twig.usephp', true);
-```
-
-
 Customizing the Twig environment
 --------------------------------
 
@@ -23,18 +10,26 @@ Customizing the Twig environment
 //   {% include '@mynamespace/something.twig' %}
 c::set('twig.namespace.mynamespace', kirby()->roots()->index().'/mydirectory');
 
-// List of additional functions that should be available in templates
-c::set('twig.env.functions', ['myCustomFunction']);
+// Expose an existing function in templates
+c::set('twig.function.myfunction', 'myCustomFunction');
 
-// List of additional functions that should be available as Twig filters
-c::set('twig.env.filters', ['myCustomFilter']);
+// Expose an existing function in templates as a filter
+c::set('twig.filter.myfilter', 'myCustomFilter');
 ```
 
+See [Using your own functions in templates](functions.md) for details about Twig functions and filters.
+
+Note: Kirby Twig 2.x used a `twig.env.functions` config, accepting an array of function names. This option is deprecated, but will still work in Kirby Twig 3.x.
+
 
 Advanced
 --------
 
 ```php
+// Should we use .php templates as fallback when .twig
+// templates don't exist? Set to false to only allow Twig templates
+c::set('twig.usephp', true);
+
 // Use Twig’s PHP cache?
 // Disabled by default (starting from 2.2).
 // Enabling Twig's cache can give a speed boost to pages with changing

doc/plugins.md

@@ -63,11 +63,8 @@ c::set('twig.namespace.myplugin', __DIR__ . '/templates');
 /**
  * Expose functions from our plugin to the Twig environment
  */
-$twigFunctionNames = array_merge(
-    c::get('twig.env.functions', []),
-    ['myPluginFunction', 'myOtherFunction']
-);
-c::set('twig.env.functions', $twigFunctionNames);
+c::set('twig.function.myPluginHelper', 'myPluginHelper');
+c::set('twig.function.myOtherHelper', 'myOtherHelper');
 ```
 
 See [“Using your own functions in templates”](functions.md) for more details about exposing functions, static methods and classes to templates.