How to Write a custom Twig Extension
Edit this pageWarning: You are browsing the documentation for Symfony 2.8, which is no longer maintained.
Read the updated version of this page for Symfony 6.2 (the current stable version).
How to Write a custom Twig Extension
The main motivation for writing an extension is to move often used code into a reusable class like adding support for internationalization. An extension can define tags, filters, tests, operators, global variables, functions, and node visitors.
Creating an extension also makes for a better separation of code that is executed at compilation time and code needed at runtime. As such, it makes your code faster.
Tip
Before writing your own extensions, have a look at the Twig official extension repository.
Create the Extension Class
Note
This article describes how to write a custom Twig extension as of Twig 1.12. If you are using an older version, please read Twig extensions documentation legacy.
To get your custom functionality you must first create a Twig Extension class. As an example you'll create a price filter to format a given number into price:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
// src/AppBundle/Twig/AppExtension.php
namespace AppBundle\Twig;
use Twig\Extension\AbstractExtension;
use Twig\TwigFilter;
class AppExtension extends AbstractExtension
{
public function getFilters()
{
return array(
new TwigFilter('price', array($this, 'formatPrice')),
);
}
public function formatPrice($number, $decimals = 0, $decPoint = '.', $thousandsSep = ',')
{
$price = number_format($number, $decimals, $decPoint, $thousandsSep);
$price = '$'.$price;
return $price;
}
}Note
Prior to Twig 1.26, your extension had to define an additional getName()
method that returned a string with the extension's internal name (e.g.
app.my_extension). When your extension needs to be compatible with Twig
versions before 1.26, include this method which is omitted in the example
above.
Here's how to create a custom function:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
// src/AppBundle/Twig/AppExtension.php
namespace AppBundle\Twig;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;
class AppExtension extends AbstractExtension
{
public function getFunctions()
{
return array(
new TwigFunction('area', array($this, 'calculateArea')),
);
}
public function calculateArea(int $width, int $length)
{
return $width * $length;
}
}Tip
Along with custom filters and functions, you can also register global variables.
Register an Extension as a Service
Now you must let the Service Container know about your newly created Twig Extension:
- YAML
- XML
- PHP
1 2 3 4 5 6 7
# app/config/services.yml
services:
app.twig_extension:
class: AppBundle\Twig\AppExtension
public: false
tags:
- { name: twig.extension }Using the custom Extension
Using your newly created Twig Extension is no different than any other:
1 2 3 4 5 6 7 8
{# Using the filter without arguments. Outputs $5,500.00 #}
{{ '5500'|price }}
{# Passing arguments to the filter. Outputs $5500,2516 #}
{{ '5500.25155'|price(4, ',', '') }}
{# Passing arguments to the function. Outputs 140 #}
Total area: {{ area(20, 7) }}Learning further
For a more in-depth look into Twig Extensions, please take a look at the Twig extensions documentation.
