Twig Guide

Master Twig templating to create powerful themes.

Twig Basics

Twig is a flexible, fast, and secure template engine for PHP. It's the templating engine used by Symfony and PteroCA.

Variables:

{{ variable }}
{{ user.username }}
{{ product.name }}

Filters:

{{ text|upper }}
{{ date|date('Y-m-d') }}
{{ price|number_format(2, '.', ',') }}
{{ content|raw }}  {# Render HTML #}

Functions:

{{ asset('assets/theme/my-theme/css/style.css') }}
{{ path('route_name') }}
{{ url('route_name', {id: 123}) }}

Control Structures:

{% if condition %}
    ...
{% elseif other_condition %}
    ...
{% else %}
    ...
{% endif %}

{% for item in items %}
    {{ item.name }}
{% else %}
    No items found
{% endfor %}

Blocks and Inheritance

Define blocks (in parent template):

<!DOCTYPE html>
<html>
<head>
    {% block head_stylesheets %}
        <link rel="stylesheet" href="default.css">
    {% endblock %}
</head>
<body>
    {% block content %}
        Default content
    {% endblock %}
</body>
</html>

Override blocks (in child template):

{% extends 'parent.html.twig' %}

{% block head_stylesheets %}
    {{ parent() }}  {# Include parent content #}
    <link rel="stylesheet" href="custom.css">
{% endblock %}

{% block content %}
    <h1>Custom Content</h1>
{% endblock %}

Including Templates

{# Include another template #}
{% include 'components/navbar.html.twig' %}

{# Include with variables #}
{% include 'components/card.html.twig' with {
    'title': 'Card Title',
    'content': 'Card content here'
} %}

{# Include only if file exists #}
{% include 'optional.html.twig' ignore missing %}

Macros (Reusable Functions)

Define macro:

{# components/macros.html.twig #}
{% macro button(text, url, style='primary') %}
    <a href="{{ url }}" class="btn btn-{{ style }}">
        {{ text }}
    </a>
{% endmacro %}

{% macro card(title, content) %}
    <div class="card">
        <div class="card-header">{{ title }}</div>
        <div class="card-body">{{ content }}</div>
    </div>
{% endmacro %}

Use macro:

{% import 'components/macros.html.twig' as macros %}

{{ macros.button('Click Me', '/path', 'success') }}
{{ macros.card('Title', 'Content here') }}

Common PteroCA Variables

Available in most templates:

{# Current user #}
{{ app.user.email }}
{{ app.user.username }}
{{ is_granted('ROLE_ADMIN') }}

{# Request information #}
{{ app.request.pathInfo }}
{{ app.request.locale }}

{# Flash messages #}
{% for message in app.flashes('success') %}
    <div class="alert alert-success">{{ message }}</div>
{% endfor %}

{# Environment #}
{{ app.environment }}  {# dev, prod #}
{{ app.debug }}        {# true/false #}

Asset Function

{# CSS #}
<link rel="stylesheet" href="{{ asset('assets/theme/my-theme/css/main.css') }}">

{# JavaScript #}
<script src="{{ asset('assets/theme/my-theme/js/main.js') }}"></script>

{# Images #}
<img src="{{ asset('assets/theme/my-theme/images/logo.svg') }}" alt="Logo">

{# Versioned assets (cache busting) #}
<link rel="stylesheet" href="{{ asset('assets/theme/my-theme/css/main.css', 'theme_package') }}">

Translation Function

{# Simple translation #}
{{ 'welcome.message'|trans }}

{# Translation with parameters #}
{{ 'greeting.user'|trans({'%name%': user.username}) }}

{# Translation with domain #}
{{ 'message'|trans({}, 'messages') }}

Useful Twig Filters

Filter

Description

Example

upper

Convert to uppercase

{{ 'hello'|upper }} → HELLO

lower

Convert to lowercase

{{ 'HELLO'|lower }} → hello

capitalize

Capitalize first letter

{{ 'hello'|capitalize }} → Hello

title

Title case

{{ 'hello world'|title }} → Hello World

length

Get length

{{ items|length }}

date

Format date

{{ date|date('Y-m-d') }}

default

Default value if empty

{{ variable|default('N/A') }}

join

Join array

{{ items|join(', ') }}

slice

Get subset

{{ text|slice(0, 100) }}

trim

Remove whitespace

{{ text|trim }}

raw

Output unescaped HTML

{{ html|raw }}

Useful Twig Tests

{# Check if variable is defined #}
{% if variable is defined %}
    {{ variable }}
{% endif %}

{# Check if variable is empty #}
{% if items is empty %}
    No items found
{% endif %}

{# Check if value is null #}
{% if value is null %}
    Value is null
{% endif %}

{# Check if user has role #}
{% if is_granted('ROLE_ADMIN') %}
    Admin content
{% endif %}

Best Practices

Escape output by default (Twig does this automatically)
Use |raw sparingly - only for trusted HTML
Keep logic minimal - use controllers for complex logic
Extract reusable parts - use includes and macros
Name blocks clearly - makes overriding easier
Comment complex sections - helps future maintainers
Test with different data - ensure templates handle edge cases

Common Patterns

Conditional CSS classes:

<div class="card {{ is_active ? 'active' : '' }}">
    ...
</div>

Loop with alternating classes:

{% for item in items %}
    <div class="{{ loop.index is odd ? 'odd' : 'even' }}">
        {{ item.name }}
    </div>
{% endfor %}

Safe navigation (null-safe):

{{ user.profile.avatar|default('default-avatar.png') }}

Multiple conditions:

{% if user and user.isVerified and user.balance > 0 %}
    <button>Purchase</button>
{% endif %}

Debugging

Dump variable:

{{ dump(variable) }}

Print all variables:

{{ dump() }}

Note: Dumps only work in development mode (APP_ENV=dev).

Overriding Templates - Customize specific templates
Theme Structure - File organization
JavaScript - Add interactivity
Testing - Quality assurance

External Resources

PreviousOverriding Templates NextStyling

Last updated 1 month ago

hashtagTwig Basics

hashtagBlocks and Inheritance

hashtagIncluding Templates

hashtagMacros (Reusable Functions)

hashtagCommon PteroCA Variables

hashtagAsset Function

hashtagTranslation Function

hashtagUseful Twig Filters

hashtagUseful Twig Tests

hashtagBest Practices

hashtagCommon Patterns

hashtagDebugging

hashtagRelated Guides

hashtagExternal Resources