https://github.com/studiometa/twig-toolkit
🔧 A set of useful extension and components for Twig
https://github.com/studiometa/twig-toolkit
Last synced: about 1 year ago
JSON representation
🔧 A set of useful extension and components for Twig
- Host: GitHub
- URL: https://github.com/studiometa/twig-toolkit
- Owner: studiometa
- License: mit
- Created: 2020-11-04T13:07:26.000Z (over 5 years ago)
- Default Branch: develop
- Last Pushed: 2025-01-27T08:55:24.000Z (over 1 year ago)
- Last Synced: 2025-03-18T06:30:00.153Z (over 1 year ago)
- Language: PHP
- Size: 1.34 MB
- Stars: 9
- Watchers: 11
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# studiometa/twig-toolkit
[](https://packagist.org/packages/studiometa/twig-toolkit)
[](https://packagist.org/packages/studiometa/twig-toolkit)
[](https://packagist.org/packages/studiometa/twig-toolkit)
[](https://github.com/studiometa/twig-toolkit/blob/master/LICENSE)
> A set of useful extension and components for Twig.
## Installation
```bash
composer require studiometa/twig-toolkit
```
## Usage
Add the `Studiometa\TwigToolkit\Extension` to your Twig instance:
```php
$loader = new \Twig\Loader\FilesystemLoader();
$twig = new \Twig\Environment($loader);
$twig->addExtension(new \Studiometa\TwigToolkit\Extension());
```
## Reference
### Functions
#### `{{ html_classes() }}`
A function to manage classes more easily.
**Params**
- `classes` (`String | Array | Object`)
**Examples**
```twig
{# The following examples will render the same HTML #}
{# HTML #}
```
#### `{{ html_styles() }}`
A function to manage style attributes more easily.
**Params**
- `styles` (`Object`)
**Examples**
```twig
```
#### `{{ html_attributes() }}`
A function to render HTML attributes more easily with the following features:
- The `class` attribute will automatically be processed by the `class` method described above
- Array and objects will be converted to JSON
- Attributes keys will be converted from any format to kebab-case
- Values will be escaped to prevent XSS attacks
**Params**
- `attrs` (`Object`): The attributes to render
**Examples**
```twig
{# HTML #}
```
#### `{{ merge_html_attributes(attr, default_attr, required_attr) }}`
Merge HTML attributes smartly, useful to define default and required attributes at the component level and allow users to add custom ones.
This filter can also be used as a function.
**Params**
- `attr` (`Object`): The user provided attributes
- `default` (`Object`): The default attributes
- `required` (`Object`): The required attributes
**Examples**
You can define default and required attributes in a component's template:
```twig
{#
/**
* @file
* component
*
* @param array $attr
* Custom attributes to apply to the root element.
*/
#}
{% set default_attributes = { class: 'bar' } %}
{% set required_attributes = { data_component: 'Component' } %}
{# Merge all attributes #}
{% set attributes = merge_html_attributes(attr, default_attributes, required_attributes)}
{# or #}
{% html_element 'div' with attributes %}
```
And then include your component with custom attributes:
```twig
{% include 'component.twig' with {
attr: {
class: 'mb-10',
aria_hidden: 'true'
}
} %}
```
You can take advantage of [named arguments](http://twig.symfony.com/doc/3.x/templates.html#named-arguments) to avoid passing a value for the default attributes argument:
```twig
{% set required_attributes = { id: 'block' } %}
{% set merged_attributes = merge_html_attributes(attr, required=required_attribute) %}
```
#### `{{ twig_toolkit_url(string) }}`
Wrapper for the `Spatie\Url\Url` class to easily manipulate URLs. See the [`spatie/url` documentation](https://github.com/spatie/url) for details on its API.
**Params**
- `url` (`string`): The URL to parse for manipulation
**Examples**
```twig
{# Change host #}
{% set url = twig_toolkit_url(url).withHost('cdn.fqdn.com') %}
{# Change/add query parameters #}
{% set url = twig_toolkit_url(url).withQueryParameter('key', 'value') %}
```
### Tags
#### `{% html_element '' with attrs %}`
Render an HTML element with the given attributes. Useful to avoid setting dynamic HTML element tags with the `<{{ tag }}>...{{ tag }}>` pattern.
**Params**
- `tag` (`String`): The name of the tag
- `attrs` (`Object`): An object describing the element's attribues
**Examples**
```twig
{# Twig #}
{% html_element 'h1' with { class: 'block' } %}
Hello world
{% end_html_element %}
{# HTML #}
Hello world
```