Filters and functions
7 min read
Filters and functions are registered by name. A template can only call what is on this page (plus anything your own code adds, see PHP API); it cannot call a PHP function.
- A filter transforms the value on its left:
{{ glb.name | upper }}. Arguments in parentheses:{{ glb.name | truncate(10, '...') }}. Chain with more pipes. - A function is called through
fn:{{ fn.concat('a', 'b') }}.func,fonkandfunctionare aliases offn. - Names are not case sensitive. An unknown filter returns the value unchanged; an unknown function returns nothing.
Examples below use these values: name = Acme Plumbing, price = 1234.5678, born = 1990-05-17, tags = red,green,blue, html = <b>Bold</b> & "q".
Text filters
These work on strings only; any other value passes through unchanged.
Filter | Arguments | What it does | Example | Result |
|---|---|---|---|---|
| Uppercase (UTF-8 safe) |
|
| |
| Lowercase |
|
| |
| Removes spaces at both ends |
|
| |
|
| Removes characters from the start; default is whitespace |
|
|
|
| Removes characters from the end |
|
|
| URL slug ( |
|
| |
|
| Replaces every occurrence (case sensitive) |
|
|
|
| Cuts to |
|
|
| Reverses a string, or a list |
|
| |
|
| Repeats the text; at most 100 times and 10,000 characters |
|
|
|
| Turns a string into a list |
|
|
Escaping filters
Variable output is not escaped. Use these when the value goes somewhere that needs it (see Security).
Filter | Arguments | What it does | Example | Result |
|---|---|---|---|---|
|
|
|
| |
|
|
| same as above | |
|
|
| nothing | |
| Removes HTML tags and script content |
|
| |
| Escapes, then turns line breaks into |
|
|
Number filters
They act on values that look like numbers; anything else passes through unchanged ({{ 'abc' | number(2) }} prints abc). Results are strings.
Filter | Arguments | What it does | Example | Result |
|---|---|---|---|---|
|
| Formats a number |
|
|
European style |
|
| ||
|
| Rounds half away from zero |
|
|
| Rounds up to a whole number |
|
| |
| Rounds down |
|
| |
| Absolute value |
|
| |
| Converts to a decimal |
|
| |
| Converts anything to a whole number; non-numbers become |
|
|
Decimals are capped at 10 (number(99) behaves as number(10)).
Date filters
A value is read as a Unix timestamp when it is numeric, otherwise as a date text (anything strtotime understands). Month and day names are translated to the site language and the site time zone applies. An empty value prints nothing; a text that is not a date is printed as is.
Filter | Arguments | What it does | Example | Result |
|---|---|---|---|---|
|
| Formats with PHP date letters |
|
|
|
| Like |
|
|
| Whole years from the date to now (365.25-day years) |
|
|
{{ 86400 | date('Y-m-d') }} prints 1970-01-02 (a number is a timestamp).
Value and list filters
Filter | Arguments | What it does | Example | Result |
|---|---|---|---|---|
|
| Uses the fallback when the value is nothing, an empty string or |
|
|
|
| Uses the fallback for anything PHP calls empty: also |
|
|
|
| Joins a list; a non-list becomes text |
|
|
| Characters of a string (UTF-8) or items of a list. Anything else is |
|
| |
| Items of a list; |
|
| |
| First item of a list or first character of a string |
|
| |
| Last item or last character |
|
| |
| JSON text (Unicode and slashes unescaped) |
|
| |
|
|
|
| |
|
|
|
|
Functions
Text
Function | Arguments | Returns | Example | Result |
|---|---|---|---|---|
| any number | The parts glued together |
|
|
|
| Same as the filters |
|
|
|
| URL slug |
|
|
|
| Part of a string (UTF-8). A negative start cannot be typed as a literal. |
|
|
|
| Position of the first match (0 is the start); nothing when not found |
|
|
|
| Characters (UTF-8) |
|
|
|
| Words, after stripping HTML. Counts words made of ASCII letters only. |
|
|
|
| MD5 hash |
|
|
|
| Joins the parts |
|
|
|
| A list |
|
|
|
| JSON text |
|
|
The text functions act on strings; a number passed as a literal is returned unchanged by upper, lower, trim and slug, and counted as 0 by characterCount and wordCount.
Numbers
Function | Arguments | Returns | Example | Result |
|---|---|---|---|---|
| any number | The total |
|
|
| any number | Largest, smallest ( |
|
|
|
| Rounded number (precision capped at 10) |
|
|
|
| Absolute value; |
| |
|
| A random whole number between them (inclusive) |
|
|
|
| Items of a list |
|
|
fn.rand returns a new number on every evaluation. Do not use it on pages that are cached.
Dates
Function | Arguments | Returns | Example | Result |
|---|---|---|---|---|
|
| The current date and time |
|
|
|
|
|
| |
| Unix timestamp |
|
| |
|
| A date; today when no timestamp |
|
|
Logic
Function | Arguments | Returns | Example | Result |
|---|---|---|---|---|
|
|
|
|
|
| any number | The first value that is not empty text and not nothing ( |
|
|
Every argument of a function is evaluated, including both branches of fn.if.
Site options
fn.option('name') returns the value of a WordPress option, only for names on a short allow-list. Everything else returns nothing, so no secret can be read.
Allowed option names |
|---|
|
{{ fn.option('blogname') }} My Site
{{ fn.option('admin_email') }} (nothing: not on the list)
{{ fn.option('active_plugins') }} (nothing)Option names are cleaned with sanitize_key. An option whose value is not a single value (an array or object) returns nothing. To allow more, use the wpmcf/variables/allowed_options filter, and only add options that are safe to print on a public page.
Common patterns
{{ glb.phone | default('Call us') }}
{{ fg.products.price | number(2, ',', '.') }} EUR
{{ fg.events.start | date('l, F j') }}
{{ fn.if(fg.products.on_sale, 'Sale', '') }}
{{ wp.post_title | truncate(60) | escape }}
{{ fn.concat(wp.post_title, ' | ', sys.site_name) }}
{{ glb.tags | split(',') | count }} tags
{{ (fg.products.stock > 0 ? 'In stock' : 'Sold out') | upper }}Still stuck? Contact support