Skip to content
  • About
    • What is Symfony?
    • Community
    • News
    • Contributing
    • Support
  • Documentation
    • Symfony Docs
    • Symfony Book
    • Screencasts
    • Symfony Bundles
    • Symfony Cloud
    • Training
  • Services
    • SensioLabs Professional services to help you with Symfony
    • Platform.sh for Symfony Best platform to deploy Symfony apps
    • SymfonyInsight Automatic quality checks for your apps
    • Symfony Certification Prove your knowledge and boost your career
    • Blackfire Profile and monitor performance of your apps
  • Other
  • Blog
  • Download
sponsored by SensioLabs
  1. Home
  2. Documentation
  3. Templating
  4. How to Write a custom Twig Extension
  • Documentation
  • Book
  • Reference
  • Bundles
  • Cloud

Table of Contents

  • Create the Extension Class
  • Register an Extension as a Service
  • Using the custom Extension
  • Learning further

How to Write a custom Twig Extension

Edit this page

Warning: 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 }
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- app/config/services.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://symfony.com/schema/dic/services
        http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="app.twig_extension"
            class="AppBundle\Twig\AppExtension"
            public="false">
            <tag name="twig.extension" />
        </service>
    </services>
</container>
1
2
3
4
5
6
7
// app/config/services.php
use AppBundle\Twig\AppExtension;

$container
    ->register('app.twig_extension', AppExtension::class)
    ->setPublic(false)
    ->addTag('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.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    We stand with Ukraine.
    Version:
    No stress: we've got you covered with our 116 automated quality checks of your code

    No stress: we've got you covered with our 116 automated quality checks of your code

    Check Code Performance in Dev, Test, Staging & Production

    Check Code Performance in Dev, Test, Staging & Production

    Symfony footer

    ↓ Our footer now uses the colors of the Ukrainian flag because Symfony stands with the people of Ukraine.

    Avatar of Antonin CLAUZIER, a Symfony contributor

    Thanks Antonin CLAUZIER (@0x346e3730) for being a Symfony contributor

    8 commits • 208 lines changed

    View all contributors that help us make Symfony

    Become a Symfony contributor

    Be an active part of the community and contribute ideas, code and bug fixes. Both experts and newcomers are welcome.

    Learn how to contribute

    Symfony™ is a trademark of Symfony SAS. All rights reserved.

    • What is Symfony?

      • Symfony at a Glance
      • Symfony Components
      • Case Studies
      • Symfony Releases
      • Security Policy
      • Logo & Screenshots
      • Trademark & Licenses
      • symfony1 Legacy
    • Learn Symfony

      • Symfony Docs
      • Symfony Book
      • Reference
      • Bundles
      • Best Practices
      • Training
      • eLearning Platform
      • Certification
    • Screencasts

      • Learn Symfony
      • Learn PHP
      • Learn JavaScript
      • Learn Drupal
      • Learn RESTful APIs
    • Community

      • SymfonyConnect
      • Support
      • How to be Involved
      • Code of Conduct
      • Events & Meetups
      • Projects using Symfony
      • Downloads Stats
      • Contributors
      • Backers
    • Blog

      • Events & Meetups
      • A week of symfony
      • Case studies
      • Cloud
      • Community
      • Conferences
      • Diversity
      • Documentation
      • Living on the edge
      • Releases
      • Security Advisories
      • SymfonyInsight
      • Twig
      • SensioLabs
    • Services

      • SensioLabs services
      • Train developers
      • Manage your project quality
      • Improve your project performance
      • Host Symfony projects

      Deployed on

    Follow Symfony

    Search by Algolia