ocubom / twig-svg-extension
A custom suite of Twig filters for SVG manipulation
Installs: 2 355
Dependents: 1
Suggesters: 0
Security: 0
Stars: 2
Watchers: 1
Forks: 0
Open Issues: 0
Requires
- php: >=7.4
- ext-dom: *
- ext-libxml: *
- bentools/iterable-functions: ^2.0
- iconify/json-tools: ^1.0
- masterminds/html5: ^2.0
- ocubom/base-convert: ^2.0
- symfony/deprecation-contracts: ^2.5|^3.2
- symfony/options-resolver: ^5.4|^6.0|^7.0
- twig/twig: ^2.7|^3.0
Requires (Dev)
- enshrined/svg-sanitize: *
- friendsofphp/php-cs-fixer: *
- iconify/json: *
- symfony/phpunit-bridge: ^4.4.9|^5.0.9|^6.0|^7.0
README
Ocubom Twig SVG Extension
A custom suite of Twig filters for SVG manipulation
Contents
About TwigSvgExtension
TwigSvgExtension is a custom suite of Twig filters for SVG manipulation.
This suite started as an internal class to inline SVG files into HTML documents. This class used to be embedded into several projects. Over time, each project adapted its version slightly, leading to fragmented development and difficult maintenance. Therefore, the development is unified in this extension which is made public in case it is useful for other projects.
Getting Started
Installation
Just use composer to add the dependency:
composer require ocubom/twig-svg-extension
Or add the dependency manually:
-
Update
composer.json
file with the lines:{ "require": { "ocubom/twig-svg-extension": "^2.0.0" } }
-
And update the dependencies:
composer update "ocubom/twig-svg-extension"
Usage
Just register the Twig extension:
$twig = new \Twig\Environment(); $twig->addExtension(new \Ocubom\Twig\Extension\SvgExtension()); $twig->addRuntimeLoader([ \Ocubom\Twig\Extension\SvgRuntime::class => function () use ($paths) { return new \Ocubom\Twig\Extension\SvgRuntime( new \Ocubom\Twig\Extension\Svg\Provider\FileSystem\FileSystemLoader($paths) ); }, \Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeRuntime::class => function () use ($paths) { return new \Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeRuntime( new \Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeLoader($paths) ); }, \Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyRuntime::class => function () use ($paths) { return new \Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyRuntime( new \Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyLoader($paths) ); }, ]); // You can also dynamically create a RuntimeLoader $twig->addRuntimeLoader(new class() implements RuntimeLoaderInterface { public function load($class) { if (\Ocubom\Twig\Extension\SvgRuntime::class === $class) { return new \Ocubom\Twig\Extension\SvgRuntime( new \Ocubom\Twig\Extension\Svg\Provider\FileSystem\FileSystemLoader($paths) ); } if (\Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeRuntime::class === $class) { return new \Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeRuntime( new \Ocubom\Twig\Extension\Svg\Provider\FontAwesome\FontAwesomeLoader($paths) ); } if (\Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyRuntime::class === $class) { return new \Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyRuntime( new \Ocubom\Twig\Extension\Svg\Provider\Iconify\IconifyLoader($paths) ); } return null; } });
The extension defines several filters and functions.
SVG Extension Core
svg
function
The svg function embeds an SVG defined in an external file into the template.
{{ svg('path/to/file.svg', {option: value}) }}
The path is relative to the search path provided as the first argument when creating the runtime.
new \Ocubom\Twig\Extension\SvgRuntime( new \Ocubom\Twig\Extension\Svg\Provider\FileSystem\FileSystemLoader( new \Ocubom\Twig\Extension\Svg\Util\PathCollection( 'first/search/path', 'second/search/path', ) ) );
The second argument can be used to add some attributes to the root element:
{{ svg('test', { 'class': 'custom svg class', 'title': 'This is a semantic title', }) }}
svg
(or svg_symbols
) filter
This filter looks for embedded SVGs and converts each of them into a reference to a symbol.
Warning
The filter must be applied at an HTML document level.
If the filter is used in a fragment, an exception will be generated.
{%- apply svg -%} <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> </head> <body> <svg width="500" height="160"> <polygon fill="#006791" class="shape" points="150,75 112.5,140 37.5,140 0,75 37.5,10 112.5,10"/> <rect fill="#006791" class="shape" transform="translate(180 0)" x="10" y="10" width="130" height="130"/> <circle fill="#006791" class="shape" transform="translate(350 0)" r="65" cx="75" cy="75"/> </svg> </body> </html> {%- endapply -%}
Note
The
svg
function can be used to embed SVG files that will be converted with this filter.
FontAwesome Provider
fa
function
Generates a simple FontAwesome HTML tag:
{{ fa('home', {title: "This is a title"}) }}
Will generate:
<span class="fa-solid fa-house" title="This is a title"></span>
Warning
The result may be slightly different. The order of the attributes or their values may vary.
fontawesome
filter
This filter looks for FontAwesome tags and replaces them by embedding the corresponding SVG.
Warning
The filter must be applied at HTML document level.
If the filter is used in a fragment, an exception will be generated.
{%- apply fontawesome -%} <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> </head> <body> <span class="fa-solid fa-house" title="This is a title"></span> </body> </html> {%- endapply -%}
Note
The
fa
function can be used to generate the tags.
Iconify Provider
iconify
filter
This filter looks for Iconify SVG Framework or Web Component and replaces them by embedding the corresponding SVG.
Warning
The filter must be applied at HTML document level.
If the filter is used in a fragment, an exception will be generated.
{%- apply iconify -%} <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> </head> <body> <span class="mdi:home" title="This is a title"></span> </body> </html> {%- endapply -%}
Roadmap
See the open issues for a full list of proposed features (and known issues).
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
- Fork the Project.
- Create your Feature Branch (
git checkout -b feature/your-feature
). - Commit your Changes (
git commit -m 'Add your-feature'
). - Push to the Branch (
git push origin feature/your-feature
). - Open a Pull Request.
Authorship
- Oscar Cubo Medina — https://ocubom.github.io
See also the list of contributors who participated in this project.
License
Distributed under the MIT License. See LICENSE for more information.