ocubom/twig-svg-extension

A custom suite of Twig filters for SVG manipulation

v2.3.0 2023-12-06 10:38 UTC

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

MIT

• Oscar Cubo Medina

• twig
• svg
• twig-extension

README

A custom suite of Twig filters for SVG manipulation

Explore the docs »

Report Bug · Request Feature

Contents

• About TwigSvgExtension
• Getting Started
  • Installation
  • Usage
• Roadmap
• Contributing
• Authorship
• License

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:

1. Update composer.json file with the lines:

   {
       "require": {
           "ocubom/twig-svg-extension": "^2.0.0"
       }
   }

2. 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".

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/your-feature).
3. Commit your Changes (git commit -m 'Add your-feature').
4. Push to the Branch (git push origin feature/your-feature).
5. 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.