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 2 days ago