craue/twigextensions-bundle

Useful Twig extensions for your Symfony project.

2.9.0 2022-01-24 15:19 UTC

Requires

• php: ^7.3|^8
• symfony/config: ~4.4|~5.3|^6
• symfony/dependency-injection: ~4.4|~5.3|^6
• symfony/twig-bundle: ~4.4|~5.3|^6

Requires (Dev)

• phpunit/phpunit: ^9.5
• symfony/browser-kit: ~4.4|~5.3|^6
• symfony/form: ~4.4|~5.3|^6
• symfony/framework-bundle: ~4.4|~5.3|^6
• symfony/phpunit-bridge: ^6
• symfony/translation: ~4.4|~5.3|^6
• symfony/yaml: ~4.4|~5.3|^6

MIT

• Christian Raue
• Symfony Community

• symfony
• twig
• extensions

README

TwigExtensionsBundle is a collection of useful Twig extensions for your Symfony project.

A live demo with code examples can is available at http://craue.de/symfony-playground/en/CraueTwigExtensions/.

DecorateEmptyValueExtension

Provides an enhanced default filter, craue_default, to decorate empty values with a placeholder which can even be HTML.

Usually, if you want to use HTML, e.g. the HTML entity —, as value for the default filter in an HTML Twig template you have to do cumbersome

{{ somevalue | e | default('—') | raw }}

to make it render properly. With this extension you can write

{{ somevalue | craue_default }}

instead.

ArrayHelperExtension

Provides the filters

• craue_without wrapping PHP's array_diff function,
• craue_replaceKey which adds/replaces an array entry (whereupon the key can be a variable),
• craue_removeKey which removes an array entry by key (whereupon the key can be a variable), and
• craue_translateArray which translates all entries in an array.

FormExtension

Provides a mechanism to render a form several times on one page. This is done by cloning the form prior to rendering using the craue_cloneForm function.

StringHelperExtension

Provides the craue_trailingDot filter for ensuring that a text ends with a dot. This comes in handy when using error messages (e.g. for validation) of vendor bundles (which are written like sentences but are missing the trailing dots) together with your own ones (which should include the trailing dot).

FormatDateTimeExtension

Provides the filters craue_date, craue_time, and craue_datetime for locale-aware formatting of date, time, and date/time values.

FormatNumberExtension

Provides the filters craue_number, craue_currency, and craue_spellout for locale-aware formatting of numbers and currencies.

ChangeLanguageExtension

Provides the functions craue_languageName and craue_availableLocales as well as a template for implementing a language change mechanism.

Installation

Get the bundle

Let Composer download and install the bundle by running

composer require craue/twigextensions-bundle

in a shell.

Enable the bundle

If you don't use Symfony Flex, register the bundle manually:

// in config/bundles.php
return [
	// ...
	Craue\TwigExtensionsBundle\CraueTwigExtensionsBundle::class => ['all' => true],
];

Or, for Symfony 3.4:

// in app/AppKernel.php
public function registerBundles() {
	$bundles = [
		// ...
		new Craue\TwigExtensionsBundle\CraueTwigExtensionsBundle(),
	];
	// ...
}

Examples to use the extensions in your Twig template

DecorateEmptyValueExtension

{{ someValueWhichMayBeEmpty | craue_default }}<br />
{{ someValueWhichMayBeEmpty | craue_default('no value') }}<br />
{{ someValueWhichMayBeEmpty | craue_default('&ndash;') }}<br />
{{ someValueWhichMayBeEmpty | craue_default(0) }}

ArrayHelperExtension

{{ anArray | craue_without(aValueOrAnArray) | join(', ') }}<br />
{{ ['red', 'green', 'yellow', 'blue'] | craue_without('yellow') | join(', ') }} will print "red, green, blue"<br />
{{ ['red', 'green', 'yellow', 'blue'] | craue_without(['yellow', 'black', 'red']) | join(', ') }} will print "green, blue"

{{ anArray | craue_replaceKey(key, value) | join(', ') }}<br />
{% set newKey = 'key3' %}
{{ {'key1': 'value1', 'key2': 'value2'} | craue_replaceKey(newKey, 'value3') | join(', ') }} will print "value1, value2, value3"

{{ anArray | craue_removeKey(key) | join(', ') }}<br />
{{ {'key1': 'value1', 'key2': 'value2'} | craue_removeKey('key1') | join(', ') }} will print "value2"

{{ anArray | craue_translateArray() | join(', ') }}<br />

FormExtension

{% for myEntity in myEntities %}
	{% set myFormInstance = craue_cloneForm(myForm) %}
	<form action="{{ path('my_route', {'id': myEntity.getId()}) }}" method="post" {{ form_enctype(myFormInstance) }}>
		{{ form_widget(myFormInstance) }}
		<input type="submit" />
	</form>
{% endfor %}

StringHelperExtension

{{ aString | craue_trailingDot }}<br />
{{ 'This text should end with a dot' | craue_trailingDot }}<br />
{{ 'This text should end with exactly one dot.' | craue_trailingDot }}

FormatDateTimeExtension

<h2>with the current locale</h2>
date: {{ someDateTimeValue | craue_date }}<br />
time: {{ someDateTimeValue | craue_time }}<br />
both: {{ someDateTimeValue | craue_datetime }}

<h2>with a specific locale</h2>
date: {{ someDateTimeValue | craue_date('de-DE') }}<br />
time: {{ someDateTimeValue | craue_time('de') }}<br />
both: {{ someDateTimeValue | craue_datetime('en-GB') }}

FormatNumberExtension

<h2>with the current locale</h2>
thousands separator: {{ someNumber | craue_number }}<br />
default currency: {{ someNumber | craue_currency }}<br />
specific currency: {{ someNumber | craue_currency('EUR') }}<br />
spelled out number: {{ someNumber | craue_spellout }}

<h2>with a specific locale</h2>
thousands separator: {{ someNumber | craue_number('de-DE') }}<br />
default currency: {{ someNumber | craue_currency(null, 'de-DE') }}<br />
specific currency: {{ someNumber | craue_currency('EUR', 'de-DE') }}<br />
spelled out number: {{ someNumber | craue_spellout('de-DE') }}

ChangeLanguageExtension

There's a Twig template provided which you can use to render a "change language" menu like this:

{% include '@CraueTwigExtensions/ChangeLanguage/changeLanguage.html.twig' %}

This will render a list of links to the current route in all defined languages. Wrap it in a div to style it via CSS. Take a look at the template if you want to customize it.

Set/override default values

DecorateEmptyValueExtension

# in app/config/parameters.yml
  craue_twig_extensions.decorateEmptyValue.placeholder: –

FormatDateTimeExtension

# in app/config/parameters.yml
  craue_twig_extensions.formatDateTime.datetype: full
  craue_twig_extensions.formatDateTime.timetype: short
  craue_twig_extensions.formatDateTime.timeZone: Europe/Berlin

FormatNumberExtension

# in app/config/parameters.yml
  craue_twig_extensions.formatNumber.currency: EUR

ChangeLanguageExtension

# in app/config/parameters.yml
  craue_twig_extensions.changeLanguage.availableLocales: [de, en, ru]
  craue_twig_extensions.changeLanguage.showForeignLanguageNames: true
  craue_twig_extensions.changeLanguage.showFirstUppercase: false

You can also set the keys to be more specific about the locales:

# in app/config/parameters.yml
  craue_twig_extensions.changeLanguage.availableLocales:
    de_DE: de
    en: en
    ru: ru

<!-- in app/config/parameters.xml -->
<parameter key="craue_twig_extensions.changeLanguage.availableLocales" type="collection">
	<parameter key="de_DE">de</parameter>
	<parameter key="en">en</parameter>
	<parameter key="ru">ru</parameter>
</parameter>

Advanced stuff

Aliases

Optionally, you can define aliases for all provided filters/functions to be used within your project. This allows you to use names you prefer instead of the pre-defined ones. E.g., if you don't like to write

{{ somevalue | craue_default }}

all the time, you may define an alias like d for the craue_default filter which allows you to write

{{ somevalue | d }}

in your Twig templates. But pay attention to not accidentally override built-in filters/functions, although you can do it intentionally.

DecorateEmptyValueExtension

# in app/config/parameters.yml
  craue_twig_extensions.decorateEmptyValue.filterAlias: d

ArrayHelperExtension

# in app/config/parameters.yml
  craue_twig_extensions.arrayHelper.withoutAlias: without
  craue_twig_extensions.arrayHelper.replaceKeyAlias: replaceKey
  craue_twig_extensions.arrayHelper.removeKeyAlias: removeKey
  craue_twig_extensions.arrayHelper.translateArrayAlias: translateArray

FormExtension

# in app/config/parameters.yml
  craue_twig_extensions.form.cloneFormAlias: cloneForm

StringHelperExtension

# in app/config/parameters.yml
  craue_twig_extensions.stringHelper.trailingDotAlias: trailingDot

FormatDateTimeExtension

# in app/config/parameters.yml
  craue_twig_extensions.formatDateTime.dateFilterAlias: date
  craue_twig_extensions.formatDateTime.timeFilterAlias: time
  craue_twig_extensions.formatDateTime.dateTimeFilterAlias: datetime

FormatNumberExtension

# in app/config/parameters.yml
  craue_twig_extensions.formatNumber.numberFilterAlias: number
  craue_twig_extensions.formatNumber.currencyFilterAlias: currency
  craue_twig_extensions.formatNumber.spelloutFilterAlias: spellout

ChangeLanguageExtension

# in app/config/parameters.yml
  craue_twig_extensions.changeLanguage.languageNameAlias: languageName
  craue_twig_extensions.changeLanguage.availableLocalesAlias: availableLocales

Enabling only specific extensions

By default, all provided extensions are enabled. If you're using only one or some of them, you may want to disable the others. The following enables them all, so remove the ones you don't need:

# in app/config/config.yml
craue_twig_extensions:
  enable_only:
    - ArrayHelperExtension
    - ChangeLanguageExtension
    - DecorateEmptyValueExtension
    - FormatDateTimeExtension
    - FormatNumberExtension
    - FormExtension
    - StringHelperExtension