[Tutorial] Convert to Twig syntax

[Kailey]

Re-posting this here because I find it super useful. Updated the original post with improvements from variaous phpBB versions as well as some other useful insight I've learned over the years. Also fixed the URLs as they were no longer valid. Original topic @ phpBB.com

---

Why should you convert to (or start using) Twig syntax in your extensions?

1. phpBB's template syntax is converted behind the scenes to use twig anyways, so if your extension is already written using twig syntax, it does not need to be converted, which means less processing/memory overhead from your extension.

2. Twig is the most common PHP template syntax format so every reputable IDE and text editor can recognize twig syntax, providing syntax highlighting, auto completion, inspection and error detection, etc. It simply makes writing your code easier to read and inspect.

3. Twig is phpBB's future. While prosilver does still use the old phpBB syntax this is only because it's too much work to rewrite it. Twig will be used as the template language behind the core style that may be developed for a future release of phpBB.

4. You can do a heck of a lot more with Twig than you could ever do with phpBB syntax.

5. There is a Twig Convertor extension that can help convert to the new syntax.

What follows are basic example conversions from old phpBB to twig syntaxes:

Variables
phpBB syntax

Code: Select all

{FOO_BAR}

Twig syntax

Code: Select all

{{ FOO_BAR }}

Language keys
phpBB syntax

Code: Select all

{L_FOO_BAR}

Twig syntax

Code: Select all

{{ lang('FOO_BAR') }}

If combining strings, you can use {{ lang('FOO') ~ lang('BAR') }}.

phpBB syntax

Code: Select all

{LA_ESCAPED_FOR_JAVASCRIPT}

Twig syntax

Code: Select all

{{ lang('ESCAPED_FOR_JAVASCRIPT')|e("js") }}
or
{{ lang('ESCAPED_FOR_JAVASCRIPT')|addslashes }}

Note that as of phpBB 3.3.5, you can use {{ lang_js('ESCAPED_FOR_JAVASCRIPT') }} for escaped javascript language vars.

Logic
phpBB syntax

Code: Select all

<!-- IF S_FOO -->
    ... hello ...
<!-- ELSE -->
    ... world...
<!-- ENDIF -->

Twig syntax

Code: Select all

{% if S_FOO %}
    ... hello ...
{% else %}
    ... world ...
{% endif %}

https://twig.symfony.com/doc/3.x/tags/if.html


Looping
phpBB syntax

Code: Select all

<!-- IF .users -->
    <!-- BEGIN users -->
        This is {users.VALUE}
    <!-- BEGINELSE -->
        no values
    <!-- END users -->
<!-- ENDIF -->

Twig syntax

Code: Select all

{% if loops.users %}
    {% for user in loops.users %}
        This is {{ user.VALUE }}
    {% else %}
        no values
    {% endfor %}
{% endif %}

https://twig.symfony.com/doc/3.x/tags/for.html
Note that where we defined user in the for context, you can name that anything you want. Also note that the loops. prefix is only needed in phpBB 3.1.x, and is not needed if you are writing for 3.2.x or later.


Includes
phpBB syntax

Code: Select all

<!-- INCLUDE overall_header.html -->
<!-- INCLUDECSS @foo_bar/style.css -->
<!-- INCLUDEJS @foo_bar/script.js -->

Twig syntax

Code: Select all

{% include 'overall_header.html' %}
{% INCLUDECSS '@foo_bar/style.css' %}
{% INCLUDEJS '@foo_bar/script.js' %}

https://twig.symfony.com/doc/3.x/tags/include.html


Template events
phpBB syntax

Code: Select all

<!-- EVENT foo_template_event_location -->

Twig syntax

Code: Select all

{% EVENT foo_template_event_location %}

Defining template variables
phpBB syntax

Code: Select all

<!-- DEFINE $FOO = 'foo' -->
<!-- IF $FOO neq '' -->
    {$FOO}
<!-- ENDIF -->

Twig syntax

Code: Select all

{% DEFINE FOO = 'foo' %}
{% if definition.FOO != '' %}
    {{ definition.FOO }}
{% endif %}

{# or if your custom var will never be used in phpBB style syntax use: #}

{% set bar = 'bar' %}
{% if bar != '' %}
    {{ bar }}
{% endif %}

https://twig.symfony.com/doc/3.x/templates.html#setting-variables


Comments
phpBB syntax

Code: Select all

<!-- This is a comment -->

Twig syntax

Code: Select all

{# This is a comment #}