Download the PHP package redant/twig-components without Composer
On this page you can find all versions of the php package redant/twig-components. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download redant/twig-components
More information about redant/twig-components
Files in redant/twig-components
Package twig-components
Short Description Define reusable components in Twig.
License MIT
Homepage https://github.com/redantnl/twig-components
Informations about the package twig-components
Twig Components
Twig Components are robust, reusable and automatically documented elements you can
use in your Twig templates using the new component
tag. Twig components allow you
to quickly build and maintain your own UI toolkit, where each button, table or card
has to be designed only once and can be used throughout your entire application.
This approach improves the developer experience in key ways:
- Easy syntax for rendering (using) a component;
- Notifications when a required parameter is missing;
- Useful suggestions when making a typo in a parameter name;
- Alerting when supplying the wrong type of data;
- Flexibility with parameter ordering.
There's also a nifty Symfony bundle available.
Quick start
Installation
The extension is installable via Composer:
or directly in your composer.json
:
Setup
You can add the extension to Twig like this:
What is a component?
Components are, in a way, inspired by plain ol' programming language functions. Components have a fixed list of parameters, so you can't use parameters that haven't been defined on the component. All parameters are type checked and self-documenting. The full component documentation can then be automatically assembled into a folder of Markdown files. Every component must supply a nested hash with configuration options, similar to the macro definition we've used before.
Why be so strict on type checking in a template? One of the reasons is that we want to be able to use these components (and their documentation, as you will see) as a means of communication between technically involved component designers and front-end oriented developers.
Twig is, by design, very forgiving in many aspects, which is great if you have complete knowledge, but may get in the way of that communication between people of different skill or information levels. We don't want a component user to have to dig into the specific component implementation every time---we want them to be able to draw from something like the public API of our regular code. That's why we enforce a more stricter use: now we're able to help users with small typos or type mismatches.
But enough words, let's look at an example component definition: for a button.
A Twig component defines a number of properties with strict typing, default values, and comments for these properties, and specifies which properties are required. Each property can be rendered to an attribute when implementing your component. A property is only required if you mark it required. You can set default values otherwise.
You'll notice how this file starts with a comment, which is optional. When present,
it will be used when rendering documentation for this component. Right after is the
actual component definition in the {% component %}
tag. Three parameters for this
button component are defined, all of type string
, with only one of them required
(the button's label
). We can document each property by providing a short
description (comment
), and an example value in the preview
argument.
In addition, Twig Components enforce some best practices to promote consistency between components, such as:
- The name of the file must equal the name of the component (i.e.,
button.html.twig
must define a component calledbutton
); - Only use snake case (
snake_case
) variable names; - Do not end comments with a period.
Okay, that last one might feel a bit arbitrary or strict but believe me, it looks way better in your documentation if there's some consistency in your parameter descriptions.
This button component will generate a Twig variable button
that contains all properties,
with the value from the options
variable or the specified default value.
Every value inside options
will be checked for its name, type and,
for required properties, whether it's defined or not.
The value can be of a type referencing an object. If the object is not always available
like absent_object
you can prefix it with a ?
to mark the type as nullable,
in which case an error will be avoided.
Usage
Every defined component is accessible through a Twig global that references the
Twig component service, effectively putting the components in the component
namespace. For example, the button
component can be accessed as component.button()
inside any Twig template.
If you don't like the name 'component', we've got you covered! See the next section.
Since all specified properties will be checked, a typo such as
{{ component.button({ lable: 'Click me' })
will be detected.
Also, {{ component.button({}) }}
will throw a runtime error, because the
label
property is required.
The hash you give to the component is first checked for name consistency with
the component definition. For instance, if you would accidentally type lable
instead of label
, Twig Components would give you a nice runtime error message:
Component "button" does not contain property "lable". Did you mean "label"?
.
Also, it does type-checking: when you supply an array as the url
, it fails.
Every parameter is checked using the is_string
, is_bool
, is_int
, is_float
,
and is_array
checks. Parameters can also enforce a specific PHP class, in
which case the instanceof
check is used. This ensures you will actually
notice when you're not using a component correctly.
Note: In reusable bundles, always use the render_component()
function,
because a user may have defined a different component global variable (see below).
A few examples are included in the doc
folder.
Global variable
If you don't like the name of the global variable that defines the components,
use the $globalVariable
parameter of the Extension to change this:
This will register the button component as ui.button()
.
Note: If you set the prefix to false
, no Twig global will be registered for
defined components. You can then only use the render_component
function to render
components.
License
This library is licensed under the MIT License - see the LICENSE file for details.
Twig Components were conceived by Gert Wijnalda [email protected] and were inspired by this post by Pierre Stoffe.
Parts of this documentation were first featured in the article 'Taming Twig', originally published in the April 2019 issue of php[architect] magazine.
Both the Twig Components code and this documentation were greatly enhanced by the invaluable feedback from my colleagues at RedAnt, notably Vincent Vermeulen, Rico Humme, Florian Käding, and Martijn van Beek. Thank you so much, guys!
All versions of twig-components with dependencies
twig/twig Version ^1.34|^2.6.1|^3.0
symfony/property-access Version ^5.4|^6.4|^7.0