PHPackages rah/rah\_function - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. rah/rah\_function ActiveTextpattern-plugin rah/rah\_function ================= Every PHP function and method is a Textpattern CMS template tag 0.8.1(3y ago)221GPL-2.0PHPPHP >=5.6.0CI passing Since Apr 25Pushed 9mo ago1 watchersCompare [ Source](https://github.com/gocom/rah_function)[ Packagist](https://packagist.org/packages/rah/rah_function)[ Docs](https://github.com/gocom/rah_function)[ Fund](https://www.paypal.me/jukkasvahn)[ RSS](/packages/rah-rah-function/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (6)Used By (0) rah\_function ============= [](#rah_function) [Download](https://github.com/gocom/rah_function/releases) | [Packagist](https://packagist.org/packages/rah/rah_function) | [Issues](https://github.com/gocom/rah_function/issues) Every PHP function and method is a [Textpattern CMS](https://textpattern.com) template tag. Install ------- [](#install) Using [Composer](https://getcomposer.org): ``` $ composer require rah/rah_function ``` Or [download](https://github.com/gocom/rah_function/releases) an installer package. Basics ------ [](#basics) ``` Contained statement ``` The plugin introduces a `` tag to Textpattern’s arsenal. It’s a multi-purpose tag that enables using public PHP functions and methods as Textpattern tags. Rah\_function is almost like a bridge between PHP and Textpattern’s tag syntax. It allows calling almost any PHP function as a Textpattern tag. Want to encode something? You can. Want use PHP’s string functions to truncate, count or otherwise bend strings at your will? You can. All without needing to write any code for new tags or add raw PHP blocks in page templates. The tag takes a `call` attribute which sets the function that is called by the tag. If omitted, the first boolean attribute name is used the called function. Apart from a `thing`, all attributes used in a tag are passed to the called PHP function as its arguments in the given order. The tag then processes the request and returns the results. Attributes ---------- [](#attributes) Attributes for `` are as follows: **call** Name of the function or the class method you want to use with the tag. Comma-separated if multiple. If omitted, the fist boolean attribute is used as the called function instead. Example: `call="base64_encode"` Default: `""` **thing** Defines the argument position of a container tag’s contained statement. If a `thing` is the last defined attribute in the tag, then the contained statement is used as the last argument too for the PHP function. If `thing` is left undefined, the contained statement is used as the first argument. Example: `foo="bar" thing bar="foo"` Default: *undefined*. **\_is** Converts the tag into a [conditional](https://docs.textpattern.com/tags/tag-basics/conditional-tags). If set, the tag’s results are compared against the value of the `_is` attribute. If they match, the tag’s contained statement is shown. Example: `_is="FALSE"` Default: *undefined*. **\_assign** Creates a [variable](https://docs.textpattern.com/tags/variable) containing the tag’s returned value. The value is used as the variable’s name. Example: `_assign="variable"` Default: *undefined*. **parameter1="" , parameter2="" , parameter3="",\[..\]** Zero or more parameters passed to the called function as arguments. Parameters are assigned to the function in the order they are defined in the tag. These additional tag attributes can be named anything. A valid attribute name can contain letters (A-z) and numbers (0-9). The names `thing` and `call` are reserved. Example: `foo2="bar" foo1="bar" foo4="bar"` Default: *undefined*. Function parameters ------------------- [](#function-parameters) Apart from the tag’s own reserved attributes, including `thing` and `call`, all attributes are passed to the called function as arguments in the order in which they are defined. If no additional attributes are used, then the called PHP function is used as is without arguments. When calling [md5](https://secure.php.net/manual/en/function.md5.php), the first attribute would be used as the string from which a hash is calculated. ``` ``` Above returns `1f3870be274f6c49b3e31a0c6728957f`, a MD5 hash of an apple. Containers and self-closing tags -------------------------------- [](#containers-and-self-closing-tags) Rah\_function supports both container and self-closing, single tag use. ### As a container tag [](#as-a-container-tag) The tag supports both a container and self-closing usage. When using the tag as a container tag, the contained statement is used in the parameter position specified by the tag’s `thing` attribute. If the `thing` attribute is undefined, the contained statement is used as the first parameter of the PHP function. ``` Hello World! ``` In the snippet above, the contained statement `Hi World!` is used as the third parameter of the [str\_replace](https://secure.php.net/manual/en/function.str-replace.php) function because that is where the `thing` is ordered. The snippet returns `Hello World!`, as expected. If `thing` attribute wasn’t used, the contained statement would be applied as first argument, leading to different results. ``` Hello World! ``` Still looks pretty much the same, but unlike the previous example where `thing` was used, now the tag returns `Hello`. Instead of the `to` attribute, the contained statement would be used as the searched needle in str\_replace. ### As a self-closing tag [](#as-a-self-closing-tag) A container translates seamlessly to a singular self-closing tag. The contained statement is a function parameter just like tag attributes, and as such, can be substituted with a tag attribute. The following does exactly same thing as the previous str\_replace examples that used containers. ``` ``` These two [htmlspecialchars](http://php.net/manual/en/function.htmlspecialchars.php) snippets give the same results, but do it with different syntaxes. As a self-closing tag, a string would be passed to the function as a tag attribute. ``` ``` But that string can also be passed as a contained statement. Since the string is htmlspecialchars function’s first parameter, the tag doesn’t need a `thing` attribute. ``` Hello World! ``` Gives a relatively readable formatting and avoids [quote escaping](https://docs.textpattern.com/tags/tag-basics/parsing-tag-attributes) that comes with tag attributes. Conditionals ------------ [](#conditionals) A rah\_function tag can transform into a conditional by applying the `_is` attribute. When `_is` is used, the tag’s results are compared against the attribute’s value. If they match, the tag’s contained statement is shown. If compared values do not match, an [else](https://docs.textpattern.com/tags/else) statement is shown, if defined. ``` Theme is set as blue. No blue? ``` The above snippet checks if an HTTP cookie named `theme` is set as `blue`. Calling multiple functions at once ---------------------------------- [](#calling-multiple-functions-at-once) Since version 0.5, a single tag can call multiple functions. This allows to further process output returned by a function with a second or more functions. Calling multiple functions with a single tag instance is done by simply using comma-separated (`,`) list of functions in the `call` attribute. ``` Some markup to strip and surrounding white-space to trim. ``` Specified functions are processed from left to right. In the above snippet, [strip\_tags](https://secure.php.net/manual/en/function.strip-tags.php) is ran first and its output is then passed on to [trim](https://secure.php.net/manual/en/function.trim.php). The first function in the list acts as the primary one. Its output is passed by reference to the following functions and all tag attributes apply only to it. The second or later functions do not get passed any attributes and the output from the first function is assigned as the consecutive functions’ first parameter. Calling multiple functions works only if the following functions expect a single parameter. If they require more than a one parameter, more than one `` tag is needed. Calling both [str\_replace](https://secure.php.net/manual/en/function.str-replace.php) and [substr](https://secure.php.net/manual/en/function.substr.php) would require two tags as both require two or more parameters. ``` ``` Returned values and legal types ------------------------------- [](#returned-values-and-legal-types) Due to how Textpattern’s template language and PHP work, not every function’s output can be returned to the template in its original format. The limitation comes in the form of [types](https://secure.php.net/manual/en/language.types.php). ### Integers, floats and strings [](#integers-floats-and-strings) Textpattern’s markup language expects strings, and that is what we must give it. Rah\_function returns values of types *integer*, *float* and *string* to the template as is, in their true presentation, with the expectation that the returned type is converted to a string by Textpattern. ### Booleans [](#booleans) The last from the scalars, boolean, is converted to an uppercase string `TRUE` or `FALSE`. This is to allow differentiating an empty string (`""`), numbers `1`, `0` and booleans from one another, otherwise in Textpattern’s template context you would have no idea which is which. For instance, PHP’s [strpos](https://secure.php.net/manual/en/function.strpos.php) returns an integer starting from zero or a boolean `FALSE` when no matches are found. When the output gets converted to a string, that zero and FALSE become the same, and there would be no way of knowing whether there were any matches. ``` ``` If no conversion was done, the above would return a zero/empty, but so it would act as if there were no matches. Through the conversion, the position and boolean are distinguishable. ``` ``` ``` No matches. First match at ``` ### Arrays [](#arrays) Returned [arrays](https://secure.php.net/manual/en/language.types.array.php) will be converted to [JSON](https://secure.php.net/manual/en/function.json-encode.php) representations. The following snippet would split the list of values into an array. ``` ``` The numeric array returned by [explode](https://secure.php.net/manual/en/function.explode.php) would be converted and returned as a literal JavaScript array. ``` ["value1","value2","value3"] ``` ### Discarded [](#discarded) The rest of types, including object, resource, NULL and callable will be discarded and a notice will be issued. Discarding is done to prevent issues. The types that are not returned do not translate to the markup language and are not usable in string context. Thus, they are not returned. While the illegal output will not be returned, the functions will still be executed. For instance, a class method that returns an object can still be executed just fine with rah\_function. There just won’t be any output apart from a harmless, informative error message. Type casting and special attribute prefixes ------------------------------------------- [](#type-casting-and-special-attribute-prefixes) ``` ``` To get around template language’s type juggling limitations, rah\_function packs a couple special attribute prefixes. These prefixes can be added before tag attribute names, allowing to cast values to different types before passing the attributes to the called function as arguments. These special attribute prefixes are `_bool`, `_null`, `_int` and `_array`. ### \_bool [](#_bool) If a tag attribute is prefixed with `_bool`, the value is converted to a boolean type. The value is converted to `FALSE` if it is empty (`""`), `0` or uppercase string `FALSE`. If it’s anything else, it becomes `TRUE`. ``` ``` ### \_null [](#_null) The `_null` prefix converts the value to NULL, no matter what the supplied value is. ``` ``` ### \_int [](#_int) The `_int` prefix converts the value to integer, ensuring that the value is a safe, valid integer. Numeric values will be rounded towards zero and non-numerical strings will be converted based on the initial portion of the string. If the attribute value starts with valid numeric data, this will be used as the value. Otherwise, the value becomes `0` (zero). ``` ``` ### \_array [](#_array) The `_array` prefix is used to generate and pass arrays. An attribute prefixed with an `_array` takes a [JSON](https://json.org/) string (JavaScript Object Notation) and converts it to a PHP’s array. ``` ``` Security related features ------------------------- [](#security-related-features) Considering the plugin’s nature, it comes with few options to limit its access. Limiting extends to both what a rah\_function tag can do and where the tag can be used. The plugin has a whitelisting option for enabling only certain functions, and it follows Textpattern’s PHP evaluation rules and user privileges, the same rules that affect [php](https://docs.textpattern.com/tags/php) tags. ### Privileges in articles [](#privileges-in-articles) User group privileges limit which users can use `` tags within articles. Only user-groups that have privileges granted access to `article.php` resource can use the tags in an article body, custom fields or excerpt. By default only the two highest groups, Publishers and Managing Editors (groups with ID 1 and 2) have access to `article.php` and will be able to publish articles with the plugin’s tags in them. ### Advanced PHP preferences [](#advanced-php-preferences) Rah\_function follows the two PHP options that can be found from Textpattern’s [Preferences](https://docs.textpattern.com/administration/preferences-panel) panel, **Allow PHP in pages** and **Allow PHP in articles**. When **Allow PHP in pages** option is disabled, a rah\_function tag can not be used in a page template or a form partial. When **Allow PHP in articles** option is disabled, rah\_function tag can not be used in articles. The tags won’t be executed, no matter what permissions the article’s author has. ### Function whitelisting [](#function-whitelisting) For added optional security, certain functions can be explicitly whitelisted. If the whitelisting option is defined, then only those whitelisted functions can be called with a rah\_function tag. Whitelisting options can be set from Textpattern’s `config.php` file. Rah\_function expects a constant named `rah_function_whitelist`, populated with a comma-separated list of function names. Function names and class methods should be formatted in the same way as when used in a rah\_function tag’s `call` attribute. ``` define('rah_function_whitelist', 'gps, ps, htmlspecialchars, str_replace, Class::StaticMethod, Class->Method'); ``` Where `gps`, `ps`, `htmlspecialchars`, `str_replace`, `Class::StaticMethod` and `Class::Method` would be the allowed functions and class methods. This whitelisting option is completely optional, and it doesn’t need to be configured. It should only be used if you want to enable certain functions for added security. Examples -------- [](#examples) ### Replacing content using str\_replace in a single tag mode [](#replacing-content-using-str_replace-in-a-single-tag-mode) ``` ``` Returns: `Hi world!` ### Replacing content using str\_replace and containers [](#replacing-content-using-str_replace-and-containers) A contained statement is used as [str\_replace](https://secure.php.net/manual/en/function.str-replace.php's) *subject* parameter. Wrapped content is positioned to the correct location by using `thing` in the tag. ``` Hello world! ``` Returns: `Hi world!` ### Sanitizing and returning HTTP GET value [](#sanitizing-and-returning-http-get-value) Returning GET/POST values and sanitizing the output can be done with a single rah\_function tag instance by using the plugin’s multi-function call feature. First we would use Textpattern’s `gps` function to get a specific value, e.g. `theme`, and then prepare it for the page template by converting HTML’s special characters to entities with [htmlspecialchars](https://secure.php.net/manual/en/function.htmlspecialchars.php). ``` ``` The above would return HTTP GET/POST param’s, named `theme`, value. If the requested value is `?theme=I