Convert to Twig syntax
Posted: Tue Aug 27, 2024 8:20 pm
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
Twig syntax
Language keys
phpBB syntax
Twig syntax
If combining strings, you can use
phpBB syntax
Twig syntax
Note that as of phpBB 3.3.5, you can use
Logic
phpBB syntax
Twig syntax
https://twig.symfony.com/doc/3.x/tags/if.html
Looping
phpBB syntax
Twig syntax
https://twig.symfony.com/doc/3.x/tags/for.html
Note that where we defined
Includes
phpBB syntax
Twig syntax
https://twig.symfony.com/doc/3.x/tags/include.html
Template events
phpBB syntax
Twig syntax
Defining template variables
phpBB syntax
Twig syntax
https://twig.symfony.com/doc/3.x/templates.html#setting-variables
Comments
phpBB syntax
Twig syntax
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}
Code: Select all
{{ FOO_BAR }}
Language keys
phpBB syntax
Code: Select all
{L_FOO_BAR}
Code: Select all
{{ lang('FOO_BAR') }}
{{ lang('FOO') ~ lang('BAR') }}
.phpBB syntax
Code: Select all
{LA_ESCAPED_FOR_JAVASCRIPT}
Code: Select all
{{ lang('ESCAPED_FOR_JAVASCRIPT')|e("js") }}
or
{{ lang('ESCAPED_FOR_JAVASCRIPT')|addslashes }}
{{ lang_js('ESCAPED_FOR_JAVASCRIPT') }}
for escaped javascript language vars.Logic
phpBB syntax
Code: Select all
<!-- IF S_FOO -->
... hello ...
<!-- ELSE -->
... world...
<!-- ENDIF -->
Code: Select all
{% if S_FOO %}
... hello ...
{% else %}
... world ...
{% endif %}
Looping
phpBB syntax
Code: Select all
<!-- IF .users -->
<!-- BEGIN users -->
This is {users.VALUE}
<!-- BEGINELSE -->
no values
<!-- END users -->
<!-- ENDIF -->
Code: Select all
{% if loops.users %}
{% for user in loops.users %}
This is {{ user.VALUE }}
{% else %}
no values
{% endfor %}
{% endif %}
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 -->
Code: Select all
{% include 'overall_header.html' %}
{% INCLUDECSS '@foo_bar/style.css' %}
{% INCLUDEJS '@foo_bar/script.js' %}
Template events
phpBB syntax
Code: Select all
<!-- EVENT foo_template_event_location -->
Code: Select all
{% EVENT foo_template_event_location %}
Defining template variables
phpBB syntax
Code: Select all
<!-- DEFINE $FOO = 'foo' -->
<!-- IF $FOO neq '' -->
{$FOO}
<!-- ENDIF -->
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 %}
Comments
phpBB syntax
Code: Select all
<!-- This is a comment -->
Code: Select all
{# This is a comment #}