susina / twig-extensions
Twig extension with useful functions, filters and tests
Requires
- php: >=8.0
- symfony/options-resolver: >=5.4
- twig/twig: ^3.0
Requires (Dev)
- phpunit/phpunit: ^9.3
- psalm/phar: ^4.6
- susina/coding-standard: ^2.3
README
Susina Twig Extensions is a set of extensions for Twig template engine. It contains some useful functions, tests and filters missing in the original library.
Installation
Firstly, install the package via Composer:
composer require susina/twig-extensions
Then add the extension you want to Twig Engine. Suppose you want to load VariablesExtension
:
<?php declare(strict_types=1); $loader = new Twig\Loader\FileLoader(__DIR__ . '/templates'); $twig = new \Twig\Environment($loader); $twig->addExtension(new \Susina\TwigExtensions\VariablesExtension());
Symfony Framework
If you are working with Symfony, after installing the library with composer, register the extensions you want as services
and tag them as twig.extension
:
// In your `services.yml` file services: Susina\TwigExtensions\GravatarExtension: tags: [twig.extension]
VariablesExtension
VariablesExtension contains some tests and functions useful for manipulating variables.
Tests
When you register this extension you can use the following type tests:
array
to test if a variable is an array; Twig also hasIterable
test but it returns true also for iterable objects.boolean
to test if a variable is boolean.float
anddouble
to test if a variable is a floating point number.integer
to test if a variable is integer.object
to test if a variable is an object.scalar
to test if a variable is a scalar (see https://www.php.net/manual/en/function.is-scalar.php).string
to test if a variable is a string.instanceOf(class_name)
to test if an object is an instance of class_name class
and you can use them in your templates:
{% if variable is string %} The variable {{ variable }} is a string. {% endif %} {% if object is instanceOf('\SplStack') %} Object is a Stack {% endif %}
Functions
get_type
get_type
function returns the variable type:
The variable `variable` is a {{ get_type(variable) }}.
var_export
var_export
function is a wrapper for PHP var_export and it
behaves in the same way. It can be useful if you want to generate some valid php code from a variable.
Filters
bool_to_string
bool_to_string
filter returns the string 'true' if the variable filtered can be evaluated as true, otherwise
it returns the string false:
The "boolVariable" is {{ boolVariable|bool_to_string }}.
it returns The "boolVariable" is true
.
You can customize the true/false strings by passing two variables to the filter: the first one represents the true value, the second one the false value, i.e.:
The "boolVariable" is {{ boolVariable|bool_to_string('yes', 'no' }}.
it returns The "boolVariable" is yes
.
StringExtension
Filters
quote
You can apply quote
filter to a string, if you want to surround it with quotes:
{% set variable = 'Donald Duck' %} {{ variable|quote }}
it returns the quoted string 'Donald Duck'
.
By default, the filter applies single quotes '
but you can pass any character you want, as the argument of the filter:
{% set variable = 'Donald Duck' %} {{ variable|quote('"') }}
then it returns "Donald Duck"
.
to_kb
to_kb
filter transform a number from bytes to kilobytes:
{% set variable = 2048 }} The file size is {{ variable|to_kb }} Kb
it returns: The file size is 2 Kb
.
By default, this filter uses the English decimal and thousands separator: .
for decimal and ,
form thousands.
You can change this behavior by passing different separators:
{% set variable = 5000000 }} English: {{ variable|to_kb }} Kb French: {{ variable|to_kb(',', '.') }}
it returns:
English: 4,882.81
French: 4.882,81
to_mb
to_mb
filter transform a number from bytes to megabytes. The behavior is the same as to_kb
.
Gravatar Extension
Gravatar extension contain a filter to retrieve the Gravatar image from a given email.
gravatar
filter returns the uri for the avatar so that you can easily use it in your html:
<img src="{{ me@my-email.com | gravatar }}" alt="My avatar" />
You can also pass some options to the filter, i.e.:
<img src="{{ me@my-email.com | gravatar({ size: 200, default: mp }) }}" alt="My avatar" />
For a full options description, please see https://en.gravatar.com/site/implement/images/.
Issues
We manage issues and feature requests via Github repository issues.
Contributing
Feel free to fork and submit pull requests: all contributions are welcome!
This library includes some useful composer scripts for developers:
composer test
to run the test suitecomposer analytics
to run Psalm static analysis toolcomposer cs:fix
to fix coding standardcomposer cs:check
to check the coding standard (see https://github.com/susina/coding-standard for details)composer coverage:html
to generate code coverage report in html format (into/coverage
directory)composer coverage:clover
to generate code coverage report in xml formatcomposer check
runs the first three commands
Before submitting a pull request, please run composer check
and fix all errors.
License
This library is released under Apache 2.0 license.