October CMS v3.1 - Upgrade Guide

[daftspunk]

Upgrading to October CMS v3.1

This guide can be used to help migrate from VojtaSvoboda.TwigExtensions. It involves replacing some Twig functions with the native syntax.

Beginning from October CMS v3.1.17, some new functions were added to the core that replaced some functions provided by this plugin, and many of the functions were already available in the core. Use the following document to find the latest syntax for each extension function.

Updated Functions

config

The {{ config(...) }} Twig function is available in v3.1.17+

env

The {{ env(...) }} Twig function is available in v3.1.17+

session

Use {{ this.session.get('my.session.key') }} to access session variables.

trans

Use {{ 'acme.blog::lang.app.name'|trans }} filter to access translations.

var_dump

Use {{ dump(users) }} function to dump information about a variable. Properties are "clickable" to expand.

template_from_string

This function is not supported natively for security reasons. You may add this using a new event in v3.1.17+

Event::listen('system.extendTwig', function ($twig) {
    $twig->addExtension(new \Twig\Extension\StringLoaderExtension);
});

Alternatively, you can register it in your layout code:

function onStart()
{
    $this->getTwig()->addExtension(new \Twig\Extension\StringLoaderExtension);
}

Now the following code will work:

{% set name = 'John' %}
{{ include(template_from_string("Hello {{ name }}")) }}
{{ include(template_from_string("Hurry up it is: {{ 'now'|date('m/d/Y') }}")) }}

strftime

Use the carbon() function to build a carbon object, combined with formatLocalized, available in v3.1.17+

{{ carbon(article.date).formatLocalized('%d.%m.%Y %H:%M:%S') }}

Updated Filters

uppercase

Use the str_upper filter

{{ 'Jack'|str_upper }}

lowercase

Use the str_lower filter

{{ 'JACK'|str_lower }}

ucfirst

Use the str_ucfirst filter

{{ 'jack'|str_ucfirst }}

lcfirst

Use the str_lcfirst filter

{{ 'Jack'|str_lcfirst }}

ltrim

Use the native trim Twig filter: https://twig.symfony.com/doc/2.x/filters/trim.html

rtrim

Use the native trim Twig filter: https://twig.symfony.com/doc/2.x/filters/trim.html

str_repeat

Use the str_repeat filter

I'm the {{ 'best '|str_repeat(3) }}!

plural

Use the str_plural filter

You have {{ count }} new {{ 'mail'|str_plural(count) }}

truncate

Use the str_limit filter

{{ "Hello World!"|str_limit(5) }}

wordwrap

This is not available.

strpad

Use the str_pad_both filter

{{ 'xxx'|str_pad_both(7, 'o') }}

str_replace

Use the str_replace filter

{{ 'Alice'|str_replace('Alice', 'Bob') }}

strip_tags

Use the html_strip filter

{{ '<p><b>Text</b></p>'|html_strip(') }}

leftpad

Use the str_pad_left filter

{{ 'xxx'|str_pad_left(5, 'o') }}

rightpad

Use the str_pad_right filter

{{ 'xxx'|str_pad_right(5, 'o') }}

rtl

Use the str_reverse filter

{{ 'Hello world!'|str_reverse }}

shuffle

Use the collect function with shuffle method

{{ collect(songs).shuffle() }}

time_diff

Use the carbon() function with diffForHumans

{{ carbon(post.published_at).diffForHumans() }}

localizednumber

Install twig/intl-extra package

composer require twig/intl-extra

Register with Twig, add to boot() method in app/Provider.php file.

Event::listen('system.extendTwig', function ($twig) {
    $twig->addExtension(new \Twig\Extra\Intl\IntlExtension);
});

Use the native format_number Twig filter: https://twig.symfony.com/doc/3.x/filters/format_number.html

localizedcurrency

Follow instructions in localizednumber

Use the native format_currency Twig filter: https://twig.symfony.com/doc/3.x/filters/format_currency.html

mailto

Use the html_mailto filter

{{ 'octobercms@gmail.tld'|html_mailto }}

var_dump

Use the dump() function

{{ dump(users) }}

revision

Use carbon() with format

carbon('now').format('m.d.y.H.i.s')

Then build the URL like so

<img src="{{ 'assets/images/image_file.jpg'|theme }}?{{ carbon('now').format('m.d.y.H.i.s') }}" alt="an image" />

sortbyfield

Use collect() with sort

collect(data).sortBy('age')

For example:

{% set data = [{'name': 'David', 'age': 31}, {'name': 'John', 'age': 28}] %}

{% for item in collect(data).sortBy('age') %}
    {{ item.name }} 
{% endfor %}

[daftspunk]

As a side note, a new plugin (or this one) could be used to introduce the twig/intl-extra composer package (described above) and register its extension. That would be pretty cool.

To retrofit this one:

1. Create a branch called 1.x for the current code, you can continue to maintain 1.x tags from this branch
2. Update this plugin to offer the new features
3. Require october/rain at >=3.1 like we have done with the translate plugin
4. Publish the plugin as 2.0 (tag as v2.0.0)
5. Set the supported version on the October CMS marketplace under "Compatibility" to protect v1 sites from getting the new version

I hope this helps!

[vojtasvoboda]

Thank @daftspunk for your help! I started to work on a new version/branch and have a few questions/notes (tested on OctoberCMS 3.1.17):

a) {{ "October CMS" | str_replace('CMS', 'ERP') }} returns ERP, not October ERP... looks like it works only like that: `{{ str_replace('CMS', 'ERP', 'October CMS') }}

b) arr_shuffle not works, nor the array_shuffle, nor the shuffle... it throws a "not existing filter" exception

c) {{ 'octobercms@gmail.tld'|html_mailto|raw }} requires raw on the end, otherwise returns just HTML encoded version

[daftspunk]

Thanks, @vojtasvoboda!

a) This is a bug, fixed in v3.1.18

b) Oops, I thought, arr_* proxied to \Arr::*. We should be using collect().shuffle() here anyway. Docs have been updated:

{{ collect(songs).shuffle() }}

c) Another bug, fixed in v3.1.18

[vojtasvoboda]

One more thing @daftspunk maybe related to html_mailto issue above:

{{ '<p><strong>Test</strong></p>'|html_strip('<p>')|raw }}

When using html_strip with specify allow tags, I have to use raw filter, otherwise, it renders HTML entities.

I've prepared and tested twig/intl-extra integration and the new plugin's version is almost done! :-) Just polishing readme etc.

[daftspunk]

Ok, we can fix this in the next patch. It looks like all html_ functions and filters should not be escaped. It should be fixed in 3.1.19

Great work on the release!