README

twig-extension-bundle

Twig extension pack for Symfony.

Installation

composer require alexandre-fernandez/twig-extension-bundle

Verify that the bundle is enabled in config/bundles.php :

return [
	// ...
	AlexandreFernandez\TwigExtensionBundle\TwigExtensionBundle::class => ['all' => true],
];

Configuration

# config/packages/twig_extension.yaml
twig_extension:
    # A list of extensions to disable, available values are: "debug", "html", "i18n", "image", "metadata" and "random".
    disable: []
    image:
		# The image library to use for image manipulation (e.g., `responsive image` twig function), available values are: "gd", "gmagick" and "imagick".
		library: "gd"
		# In which "/public" relative path to store responsive images.
		responsive_dir: "images/responsive"
		# What format will be used to generate responsive versions of your images.
		responsive_format: "webp"
		# What format will be used to generate the fallback for the responsive versions of your images.
		responsive_fallback_format: "webp"
		# What breakpoints (in px) will be used to generate responsive versions of your images.
		responsive_breakpoints: [480, 960, 1920, 2560]

Debug

dd

type: TwigFunction service: TwigDebugExtension method: dd(array ...$vars): void

Symfony's dd (dump & die).

{{ dd(variableToDebug) }}

HTML

attributes

type: TwigFilter service: TwigHtmlExtension method: setTopLevelHtmlAttributes(string $html, array $attributes): string

Sets the given HTML attributes on the top-level elements within an HTML string.

{% set html %}
<p>Captured</p>
<p><span>HTML</span></p>
{% endset %}
<!---->
{{ html = html|attributes({ class: "paragraph" })|raw }}
<!--
<p class="paragraph">Captured</p>
<p class="paragraph"><span>HTML</span></p>
-->

I18N

is_translatable

type: TwigFunction service: TwigI18nExtension method: isTranslatable(mixed $value): bool

Checks if a given value is an instance of the TranslatableInterface (TranslatableMessage implements TranslatableInterface).

{% if is_translatable(object) %}
<p>{{ object|trans }}</p>
{% else %}
<p>Untranslatable</p>
{% endif %}

Image

responsive_image

type: TwigFunction service: TwigImageExtension method: getPictureElement(string $src, array $attributes = [], int $percentage = 1, ?string $uid = null): string

Generates an HTML <picture> element with responsive image sources.

• The first argument is a project-relative path to the asset, it will also be used to generate an unique id for the image if $uid is not given.
• The second argument is optional and allows to add html attributes to the DOM element.
• The third argument is an optional percentage (between 0 and 1) of the maximum space the image will take in the browser window (e.g., A percentage of 0.5 will generate responsive images for half the size of the configured breakpoints, this optimizes the size of the image for that specific case).
• The fourth argument is an optional unique id which will be used to cache the generated image. Before generating an image responsive_image checks if an image already exists for the given uid+breakpoint+percentage, if it does the image is not generated and that one is taken instead.

Additional configuration can be found in the configuration section.

{{ responsive_image("/assets/images/hero.png", { class: "hero" }, 0.75) }}

Like all other extension services TwigImageExtension is autowirable. It also includes methods to delete or update/create responsive images outside of twig, these are deleteResponsiveImages(string $src, ?string $uid = null): static and upsertResponsiveImages(string $src, ?string $uid = null, array $percentages = []): array.

embed_svg

type: TwigFunction service: TwigImageExtension method: getReferencedSvgElement(string $src, array $attributes = [], ?string $uid = null): string

This function enables you to embed a SVG file directly in the template, additionally SVGs which were already embedded once for the current request will be referenced instead of copied.

• The first argument is a project-relative path to the asset, it will also be used to generate an unique id for the image if $uid is not given.
• The second argument is optional and allows to add html attributes to the DOM element.
• The third argument is an optional unique id which will be used as the cache key and reference ID.

{{ embed_svg("/assets/icons/arrow-left.svg") }}

Metadata

class

type: TwigFilter service: TwigMetadataExtension method: getClass(mixed $value): ?string

Gets the class of a variable or null if it's not an object.

{% if object|class == "App\\Entity\\Post" %}
<!-- ... -->
{% endif %}

type

type: TwigFilter service: TwigMetadataExtension method: getType(mixed $value): string

Gets the type of a variable as a string. The possible return values are: "bool", "int", "float", "callable", "enum", "string", "array", "object", "null", "resource", "resource (closed)" and "unknown type".

{% if object|type == "enum" %}
<!-- ... -->
{% endif %}

Random

shuffle

type: TwigFilter service: TwigRandomExtension method: shuffle(string|array $value): string|array

This filter shuffles (randomizes the order of the elements or characters) in an array or string.

{% set items = ["a", "b", "c", "d"]|shuffle|slice(0,2) %}
<!---->
{% for item in items %}
<!-- ... -->
{% endfor %}