Implemented support for substr, implode and json_encode as modifiers. (…

…#940)

* Implemented support for substr, implode and json_encode as modifiers. Fixes #939
* Added split and join in favor of explode and implode modifiers.
* Documented all available modifiers

changelog/939.md

@@ -0,0 +1 @@
+- Add support for implode, substr and json_encode as modifiers/functions in templates [#939](https://github.com/smarty-php/smarty/issues/939)

docs/designers/language-modifiers/index.md

@@ -6,34 +6,10 @@ or strings. To apply a modifier,
 specify the value followed by a `|` (pipe) and the modifier name. A
 modifier may accept additional parameters that affect its behavior.
 These parameters follow the modifier name and are separated by a `:`
-(colon). Also, *all php-functions can be used as modifiers implicitly*
-(more below) and modifiers can be
-[combined](../language-combining-modifiers.md).
-
-- [capitalize](language-modifier-capitalize.md)
-- [cat](language-modifier-cat.md)
-- [count_characters](language-modifier-count-characters.md)
-- [count_paragraphs](language-modifier-count-paragraphs.md)
-- [count_sentences](language-modifier-count-sentences.md)
-- [count_words](language-modifier-count-words.md)
-- [date_format](language-modifier-date-format.md)
-- [default](language-modifier-default.md)
-- [escape](language-modifier-escape.md)
-- [from_charset](language-modifier-from-charset.md)
-- [indent](language-modifier-indent.md)
-- [lower](language-modifier-lower.md)
-- [nl2br](language-modifier-nl2br.md)
-- [regex_replace](language-modifier-regex-replace.md)
-- [replace](language-modifier-replace.md)
-- [spacify](language-modifier-spacify.md)
-- [string_format](language-modifier-string-format.md)
-- [strip](language-modifier-strip.md)
-- [strip_tags](language-modifier-strip-tags.md)
-- [to_charset](language-modifier-to-charset.md)
-- [truncate](language-modifier-truncate.md)
-- [unescape](language-modifier-unescape.md)
-- [upper](language-modifier-upper.md)
-- [wordwrap](language-modifier-wordwrap.md)
+(colon). 
+
+Modifiers can be applied to any type of variables, including arrays
+and objects.
 
 ## Examples
 
@@ -65,40 +41,63 @@ These parameters follow the modifier name and are separated by a `:`
 {* php's count *}
 {$myArray|@count}
 
-{* this will uppercase and truncate the whole array *}
+{* this will uppercase the whole array *}
 <select name="name_id">
-{html_options output=$my_array|upper|truncate:20}
+{html_options output=$my_array|upper}
 </select>
 ```  
-      
-- Modifiers can be applied to any type of variables, including arrays
-    and objects.
-
-    > **Note**
-    >
-    > The default behavior was changed with Smarty 3. In Smarty 2.x, you
-    > had to use an "`@`" symbol to apply a modifier to an array, such
-    > as `{$articleTitle|@count}`. With Smarty 3, the "`@`" is no
-    > longer necessary, and is ignored.
-    >
-    > If you want a modifier to apply to each individual item of an
-    > array, you will either need to loop the array in the template, or
-    > provide for this functionality inside your modifier function.
-
-    > **Note**
-    >
-    > Second, in Smarty 2.x, modifiers were applied to the result of
-    > math expressions like `{8+2}`, meaning that
-    > `{8+2|count_characters}` would give `2`, as 8+2=10 and 10 is two
-    > characters long. With Smarty 3, modifiers are applied to the
-    > variables or atomic expressions before executing the calculations,
-    > so since 2 is one character long, `{8+2|count_characters}`
-    > gives 9. To get the old result use parentheses like
-    > `{(8+2)|count_characters}`.
-
-- Custom modifiers can be registered
-    with the [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md)
-    function.
+
+## Combining Modifiers
+
+You can apply any number of modifiers to a variable. They will be
+applied in the order they are combined, from left to right. They must be
+separated with a `|` (pipe) character.
+
+```php
+<?php
+
+$smarty->assign('articleTitle', 'Smokers are Productive, but Death Cuts Efficiency.');
+```
+
+where template is:
+
+```smarty
+{$articleTitle}
+{$articleTitle|upper|spacify}
+{$articleTitle|lower|spacify|truncate}
+{$articleTitle|lower|truncate:30|spacify}
+{$articleTitle|lower|spacify|truncate:30:". . ."}
+```
+
+
+The above example will output:
+
+```
+Smokers are Productive, but Death Cuts Efficiency.
+S M O K E R S   A R ....snip....  H   C U T S   E F F I C I E N C Y .
+s m o k e r s   a r ....snip....  b u t   d e a t h   c u t s...
+s m o k e r s   a r e   p r o d u c t i v e ,   b u t . . .
+s m o k e r s   a r e   p. . .
+```
+
+## Using modifiers in expressions
+
+Modifiers can also be used in expressions. For example, you can use the [isset modifier](./language-modifier-isset.md)
+to test if a variable holds a value different from null.
+
+```smarty
+{if $varA|isset}
+    <b>variable A is set</b>
+{/if}
+```
+
+You can also use modifiers in expressions in a PHP-style syntax:
+
+```smarty
+{if isset($varA)}
+    <b>variable A is set</b>
+{/if}
+```
 
 See also [`registerPlugin()`](../../programmers/api-functions/api-register-plugin.md), [combining
 modifiers](../language-combining-modifiers.md). and [extending smarty with

docs/designers/language-modifiers/language-modifier-count.md

@@ -0,0 +1,21 @@
+# count
+
+Returns the number of elements in an array (or Countable object). Will return 0 for null.
+Returns 1 for any other type (such as a string).
+
+If the optional mode parameter is set to 1, count() will recursively count the array. 
+This is particularly useful for counting all the elements of a multidimensional array.
+
+## Basic usage
+```smarty
+{if $myVar|count > 3}4 or more{/if}
+{if count($myVar) > 3}4 or more{/if}
+```
+
+
+## Parameters
+
+| Parameter | Type | Required | Description                                            |
+|-----------|------|----------|--------------------------------------------------------|
+| 1         | int  | No       | If set to 1, count() will recursively count the array. |
+

docs/designers/language-modifiers/language-modifier-debug-print-var.md

@@ -0,0 +1,26 @@
+# debug_print_var
+
+
+
+Returns the value of the given variable in a human-readable format in HTML. 
+Used in the [debug console](../chapter-debugging-console.md), but you can also use it in your template
+while developing to see what is going on under the hood.
+
+> **Note**
+>
+> Use for debugging only! Since you may accidentally reveal sensitive information or introduce vulnerabilities such as XSS using this
+method never use it in production.
+
+## Basic usage
+```smarty
+{$myVar|debug_print_var}
+```
+
+
+## Parameters
+
+| Parameter | Type | Required | Description                                                            |
+|-----------|------|----------|------------------------------------------------------------------------|
+| 1         | int  | No       | maximum recursion depth if $var is an array or object (defaults to 10) |
+| 2         | int  | No       | maximum string length if $var is a string (defaults to 40)             |
+

docs/designers/language-modifiers/language-modifier-isset.md

@@ -0,0 +1,11 @@
+# isset
+
+Returns true if the variable(s) passed to it are different from null.
+
+If multiple parameters are supplied then isset() will return true only if all of the parameters are 
+not null.
+
+## Basic usage
+```smarty
+{if $myVar|isset}all set!{/if}
+```

docs/designers/language-modifiers/language-modifier-join.md

@@ -0,0 +1,26 @@
+# join
+
+Returns a string containing all the element of the given array 
+with the separator string between each.
+
+## Basic usage
+
+For `$myArray` populated with `['a','b','c']`, the following will return the string `abc`.
+```smarty
+{$myArray|join}
+```
+
+
+## Parameters
+
+| Parameter | Type   | Required | Description                                                 |
+|-----------|--------|----------|-------------------------------------------------------------|
+| 1         | string | No       | glue used between array elements. Defaults to empty string. |
+
+## Examples
+
+
+For `$myArray` populated with `[1,2,3]`, the following will return the string `1-2-3`.
+```smarty
+{$myArray|join:"-"}
+```

docs/designers/language-modifiers/language-modifier-json-encode.md

@@ -0,0 +1,27 @@
+# json_encode
+
+Transforms a value into a valid JSON string.
+
+## Basic usage
+```smarty
+{$user|json_encode}
+```
+Depending on the value of `$user` this would return a string in JSON-format, e.g. `{"username":"my_username","email":"my_username@smarty.net"}`.
+
+
+## Parameters
+
+| Parameter | Type | Required | Description                                                                               |
+|-----------|------|----------|-------------------------------------------------------------------------------------------|
+| 1         | int  | No       | bitmask of flags, directly passed to [PHP's json_encode](https://www.php.net/json_encode) |
+
+
+## Examples
+
+By passing `16` as the second parameter, you can force json_encode to always format the JSON-string as an object.
+Without it, an array `$myArray = ["a","b"]` would be formatted as a javascript array: 
+
+```smarty
+{$myArray|json_encode} # renders: ["a","b"]
+{$myArray|json_encode:16} # renders: {"0":"a","1":"b"}
+```

docs/designers/language-modifiers/language-modifier-noprint.md

@@ -0,0 +1,9 @@
+# noprint
+
+Always returns an empty string. This can be used to call a function or a method on an object that 
+returns output, and suppress the output.
+
+## Basic usage
+```smarty
+{$controller->sendEmail()|noprint}
+```

docs/designers/language-modifiers/language-modifier-number-format.md

@@ -0,0 +1,32 @@
+# number_format
+
+Allows you to format a number using decimals and a thousands-separator. By default, the number of decimals is 0 
+and the number is rounded.
+
+## Basic usage
+```smarty
+{$num  = 2000.151}
+{$num|number_format} # renders: 2,000
+```
+
+
+## Parameters
+
+| Parameter | Type   | Required | Description                           |
+|-----------|--------|----------|---------------------------------------|
+| 1         | int    | No       | number of decimals (defaults to 0)    |
+| 2         | string | No       | decimal separator (defaults to ".")   |
+| 3         | string | No       | thousands-separator (defaults to ",") |
+
+
+## Examples
+
+```smarty
+{$num  = 2000.151}
+{$num|number_format:2} # renders: 2,000.15
+```
+
+```smarty
+{$num  = 2000.151}
+{$num|number_format:2:".":""} # renders: 2000.15
+```

docs/designers/language-modifiers/language-modifier-round.md

@@ -0,0 +1,35 @@
+# round
+
+Rounds a number to the specified precision.
+
+## Basic usage
+```smarty
+{3.14|round} # renders: 3
+```
+
+```smarty
+{3.141592|round:2} # renders: 3.14
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description               |
+|-----------|------|----------|---------------------------|
+| 1         | int  | No       | precision (defaults to 0) |
+| 2         | int  | No       | mode (defaults to 1)      |
+
+If 'precision' is negative, the number is rounded to the nearest power of 10. See examples below.
+
+The parameter 'mode' defines how the rounding is done. By default, 2.5 is rounded to 3, whereas 2.45 is rounded to 2.
+You usually don't need to change this. For more details on rounding modes, 
+see [PHP's documentation on round](https://www.php.net/manual/en/function.round).
+
+## Examples
+
+By passing `16` as the second parameter, you can force json_encode to always format the JSON-string as an object.
+Without it, an array `$myArray = ["a","b"]` would be formatted as a javascript array:
+
+```smarty
+{$myArray|json_encode} # renders: ["a","b"]
+{$myArray|json_encode:16} # renders: {"0":"a","1":"b"}
+```

docs/designers/language-modifiers/language-modifier-split.md

@@ -0,0 +1,32 @@
+# split
+
+Splits a string into an array, using the optional second parameter as the separator.
+
+## Basic usage
+
+For `$chars` populated with `'abc'`, the following will produce a html list with 3 elements (a, b and c).
+```smarty
+<ol>
+    {foreach $chars|split as $char}
+        <li>{$char|escape}</li>
+    {/foreach}
+</ol>
+```
+
+## Parameters
+
+| Parameter | Type   | Required | Description                                                                                                                  |
+|-----------|--------|----------|------------------------------------------------------------------------------------------------------------------------------|
+| 1         | string | No       | separator used to split the string on. Defaults to empty string, causing each character in the source string to be separate. |
+
+## Examples
+
+
+For `$ids` populated with `'1,2,3'`, the following will produce a html list with 3 elements (1, 2 and 3).
+```smarty
+<ol>
+    {foreach $ids|split:',' as $id}
+        <li>{$id|escape}</li>
+    {/foreach}
+</ol>
+```

docs/designers/language-modifiers/language-modifier-str-repeat.md

@@ -0,0 +1,14 @@
+# str_repeat
+
+Repeats the given value n times.
+
+## Basic usage
+```smarty
+{"hi"|str_repeat:2} # renders: hihi
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description           |
+|-----------|------|----------|-----------------------|
+| 1         | int  | yes      | number of repetitions |

docs/designers/language-modifiers/language-modifier-strlen.md

@@ -0,0 +1,9 @@
+# strlen
+
+Returns the length (number of characters) in the given string, including spaces.
+
+## Basic usage
+```smarty
+{"Smarty"|strlen} # renders: 6
+{156|strlen} # renders: 3
+```