Twig extensions plugin for OctoberCMS adds new filter and functions to your templates. No other plugin dependencies. Tested with the latest stable OctoberCMS 3.1.18 on PHP 8.0.
There are two versions of this plugin - 1.x and 2.x. For older October 1.0.x, 1.1.x or 2.x.x use special branch 1.x. For October 3.1+ use master branch.
For old Laravel 5.4 October's versions use special branch laravel54.
For migrating between plugin's version 1 and version 2 you can use special UPGRADE.md guide.
Install plugin from CMS backend or by Composer:
composer require vojtasvoboda/oc-twigextensions-plugin
Than you can use newly added filters/functions at your templates:
<h1 class="heading">{{ article.heading | ltrim }}</h1>
<p class="created">
Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}
</p>
<p class="perex">
{{ article.perex | wordwrap(80) }}
</p>
session, trans, var_dump, template_from_string, country_timezones
Function moves the functionality of the Laravel session() helper function to Twig.
{{ session('my.session.key') }}
The example would output the value currently stored in my.session.key.
See more about the Laravel session helper function here.
You can also use OctoberCMS function: {{ this.session.get('my.session.key') }}, but it's little bit longer :-)
Function moves the functionality of the Laravel trans() helper function to Twig.
{{ trans('acme.blog::lang.app.name') }}
The example would output a value stored in a localization file of an imaginary blog plugin. See more about localization in October CMS here.
You can also use trans filter: {{ 'acme.blog::lang.app.name'|trans }}.
Dumps information about a variable. Can be also used as a filter.
<pre>{{ var_dump(users) }}</pre>
You can also use {{ dump(users) }} function to dump information about a variable. Properties are "clickable" to expand.
Function loads a template from a string.
{% set name = 'John' %}
{{ include(template_from_string("Hello {{ name }}")) }}
{{ include(template_from_string("Hurry up it is: {{ "now"|date("m/d/Y") }}")) }}
The country_timezones function returns the names of the timezones associated with a given country code:
{# Europe/Paris #}
{{ country_timezones('FR')|join(', ') }}- PHP functions: strftime, ltrim, rtrim, var_dump, wordwrap
- custom functions: revision
- internationalized names filters: country_name, currency_name, currency_symbol, language_name, locale_name, timezone_name
- localized formatters filters: format_currency, format_number, format_*_number, format_datetime, format_date, format_time
Format a local time/date according to locale settings.
Posted at {{ article.date | strftime('%d.%m.%Y %H:%M:%S') }}
The example would output Posted at 04.01.2016 22:57:42. See more format parameters.
You can also use {{ carbon(article.date).formatLocalized('%d.%m.%Y %H:%M:%S') }}.
Strip whitespace (or other characters) from the beginning of a string.
Hello I'm {{ ' jack' | ltrim }}
The example would output Hello I'm jack without whitespaces from the start.
You can also use {{ ' I like Twig. '|trim(side='left') }} native Twig filter.
Strip whitespace (or other characters) from the end of a string.
Hello I'm {{ 'jack ' | rtrim }}
The example would output Hello I'm jack without whitespaces from the end.
You can also use {{ ' I like Twig. '|trim(side='right') }} native Twig filter.
Dumps information about a variable.
<pre>{{ users | var_dump }}</pre>
You can also use <pre>{{ var_dump(users) }}</pre> or {{ dump(users) }} functions.
Use the wordwrap filter to split your text into lines with equal length.
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10) }}
This example would print:
Lorem ipsu
m dolor si
t amet, co
nsectetur
adipiscing
The default separator is "\n", but you can easily change that by providing one:
{{ "Lorem ipsum dolor sit amet, consectetur adipiscing" | wordwrap(10, "zz\n") }}
This would result in:
Lorem ipsuzz
m dolor sizz
t amet, cozz
nsectetur zz
adipiscing
Force the browser to reload cached modified/updated asset files. You can provide a format parameter so that the prepended timestamp gets converted accordingly to the PHP date() function.
<img src="{{ 'assets/images/image_file.jpg' | theme | revision("m.d.y.H.i.s") }}" alt="an image" />
Will return something like
<img src="https://www.example.com/themes/my-theme/assets/image_file.png?12.03.16.04.52.38" alt="An image" />
See: #25
https://stackoverflow.com/questions/32414/how-can-i-force-clients-to-refresh-javascript-files
http://php.net/manual/en/function.date.php
The country_name filter returns the country name given its ISO-3166 two-letter code:
{# France #}
{{ 'FR'|country_name }}By default, the filter uses the current locale. You can pass it explicitly:
{# États-Unis #}
{{ 'US'|country_name('fr') }}The currency_name filter returns the currency name given its three-letter code:
{# Euro #}
{{ 'EUR'|currency_name }}
{# Japanese Yen #}
{{ 'JPY'|currency_name }}By default, the filter uses the current locale. You can pass it explicitly:
{# yen japonais #}
{{ 'JPY'|currency_name('fr_FR') }}The currency_symbol filter returns the currency symbol given its three-letter code:
{# € #}
{{ 'EUR'|currency_symbol }}
{# ¥ #}
{{ 'JPY'|currency_symbol }}By default, the filter uses the current locale. You can pass it explicitly:
{# ¥ #}
{{ 'JPY'|currency_symbol('fr') }}The language_name filter returns the language name given its two-letter code:
{# German #}
{{ 'de'|language_name }}By default, the filter uses the current locale. You can pass it explicitly:
{# allemand #}
{{ 'de'|language_name('fr') }}
{# français canadien #}
{{ 'fr_CA'|language_name('fr_FR') }}The locale_name filter returns the locale name given its two-letter code:
{# German #}
{{ 'de'|locale_name }}By default, the filter uses the current locale. You can pass it explicitly:
{# allemand #}
{{ 'de'|locale_name('fr') }}
{# français (Canada) #}
{{ 'fr_CA'|locale_name('fr_FR') }}The timezone_name filter returns the timezone name given a timezone identifier:
{# Central European Time (Paris) #}
{{ 'Europe/Paris'|timezone_name }}
{# Pacific Time (Los Angeles) #}
{{ 'America/Los_Angeles'|timezone_name }}By default, the filter uses the current locale. You can pass it explicitly:
{# heure du Pacifique nord-américain (Los Angeles) #}
{{ 'America/Los_Angeles'|timezone_name('fr') }}The format_currency filter formats a number as a currency:
{# €1,000,000.00 #}
{{ '1000000'|format_currency('EUR') }}You can pass attributes to tweak the output:
{# €12.34 #}
{{ '12.345'|format_currency('EUR', {rounding_mode: 'floor'}) }}
{# €1,000,000.0000 #}
{{ '1000000'|format_currency('EUR', {fraction_digit: 4}) }}The list of supported options:
- grouping_used;
- decimal_always_shown;
- max_integer_digit;
- min_integer_digit;
- integer_digit;
- max_fraction_digit;
- min_fraction_digit;
- fraction_digit;
- multiplier;
- grouping_size;
- rounding_mode;
- rounding_increment;
- format_width;
- padding_position;
- secondary_grouping_size;
- significant_digits_used;
- min_significant_digits_used;
- max_significant_digits_used;
- lenient_parse.
By default, the filter uses the current locale. You can pass it explicitly:
{# 1.000.000,00 € #}
{{ '1000000'|format_currency('EUR', locale='de') }}The format_number filter formats a number:
{{ '12.345'|format_number }}You can pass attributes to tweak the output:
{# 12.34 #}
{{ '12.345'|format_number({rounding_mode: 'floor'}) }}
{# 1000000.0000 #}
{{ '1000000'|format_number({fraction_digit: 4}) }}The list of supported options:
- grouping_used;
- decimal_always_shown;
- max_integer_digit;
- min_integer_digit;
- integer_digit;
- max_fraction_digit;
- min_fraction_digit;
- fraction_digit;
- multiplier;
- grouping_size;
- rounding_mode;
- rounding_increment;
- format_width;
- padding_position;
- secondary_grouping_size;
- significant_digits_used;
- min_significant_digits_used;
- max_significant_digits_used;
- lenient_parse.
Besides plain numbers, the filter can also format numbers in various styles:
{# 1,234% #}
{{ '12.345'|format_number(style='percent') }}
{# twelve point three four five #}
{{ '12.345'|format_number(style='spellout') }}
{# 12 sec. #}
{{ '12'|format_duration_number }}The list of supported styles:
- decimal;
- currency;
- percent;
- scientific;
- spellout;
- ordinal;
- duration.
As a shortcut, you can use the format_*_number filters by replacing * with a style:
{# 1,234% #}
{{ '12.345'|format_percent_number }}
{# twelve point three four five #}
{{ '12.345'|format_spellout_number }}You can pass attributes to tweak the output:
{# 12.3% #}
{{ '0.12345'|format_percent_number({rounding_mode: 'floor', fraction_digit: 1}) }}By default, the filter uses the current locale. You can pass it explicitly:
{# 12,345 #}
{{ '12.345'|format_number(locale='fr') }}The format_datetime filter formats a date time:
{# Aug 7, 2019, 11:39:12 PM #}
{{ '2019-08-07 23:39:12'|format_datetime() }}You can tweak the output for the date part and the time part:
{# 23:39 #}
{{ '2019-08-07 23:39:12'|format_datetime('none', 'short', locale='fr') }}
{# 07/08/2019 #}
{{ '2019-08-07 23:39:12'|format_datetime('short', 'none', locale='fr') }}
{# mercredi 7 août 2019 23:39:12 UTC #}
{{ '2019-08-07 23:39:12'|format_datetime('full', 'full', locale='fr') }}Supported values are: none, short, medium, long, and full.
For greater flexibility, you can even define your own pattern (see the ICU user guide for supported patterns).
{# 11 oclock PM, GMT #}
{{ '2019-08-07 23:39:12'|format_datetime(pattern="hh 'oclock' a, zzzz") }}By default, the filter uses the current locale. You can pass it explicitly:
{# 7 août 2019 23:39:12 #}
{{ '2019-08-07 23:39:12'|format_datetime(locale='fr') }}By default, the date is displayed by applying the default timezone (the one specified in php.ini or declared in Twig -- see below), but you can override it by explicitly specifying a timezone:
{{ datetime|format_datetime(locale='en', timezone='Pacific/Midway') }}If the date is already a DateTime object, and if you want to keep its current timezone, pass false as the timezone value:
{{ datetime|format_datetime(locale='en', timezone=false) }}The default timezone can also be set globally by calling setTimezone():
$twig = new \Twig\Environment($loader);
$twig->getExtension(\Twig\Extension\CoreExtension::class)->setTimezone('Europe/Paris');
The format_date filter formats a date. It behaves in the exact same way as the format_datetime filter, but without the time.
The format_time filter formats a time. It behaves in the exact same way as the format_datetime filter, but without the date.
Functions used in plugin's version 1.x for October 1.0.x, 1.1.x, 2.0.x and removed from this version:
- config() - it's native function since October 3.1.17
- env() - it's native function since October 3.1.17
Filters used in plugin's version 1.x for October 1.0.x, 1.1.x, 2.0.x and removed from this version:
- uppercase - use str_upper or just upper
- lowercase - use str_lower or just lower
- ucfirst - use str_ucfirst
- lcfirst - use str_lcfirst
- str_repeat - it's native filter now
- plural - use str_plural
- truncate - use str_limit
- strpad - use str_pad_both
- str_replace - it's native filter now
- strip_tags - use html_strip
- leftpad - use str_pad_left
- rightpad - use str_pad_right
- rtl - use str_reverse
- shuffle - use
collect(songs).shuffle() - time_diff - use
carbon(post.published_at).diffForHumans() - localizeddate - use format_date
- localizednumber - use format_number
- localizedcurrency - use format_currency
- mailto - use html_mailto
- var_dump - use dump function
- sortbyfield - use
collect(data).sortBy('age')orcollect(data).sortByDesc('age')
For more info see UPGRADE.md guide.
- Make template_from_string turned off by default and add special checkbox to the backend to allow it.
- Add missing unit tests.
- New filters ga and gtm for adding GA or GTM code (Heap Analytics) - {{ 'UA-1234567' | ga }}.
- Add cache extension.
Feel free to send pullrequest! Please, send Pull Request to master branch.
Twig extensions plugin is open-sourced software licensed under the MIT license same as OctoberCMS platform.