README

Raw SVG symbols in Yii2

Probably the best way to embed icons like those from FontAwesome on your website is to use bare SVGs as SVG symbols. The SVG-code of the icons is embedded in the page. Therefore no extra font file has to be downloaded, no JavaScript needs to run at page set up, and the browser will render the icons as fast as possible.

At the downside, this requires a bit more coding. Until now, that is; because now there is yii2-icon. This provides a helper class for Yii 2.0 that takes the burden out of icons based on bare SVG Symbols.

A demonstration of yii2-icon is here. yii2-icon's GitHub-page is here.

Installation

Install yii2-icon in the usual way with Composer. Add the following to the require section of your composer.json file:

"sjaakp/yii2-icon": "*"

or run:

composer require sjaakp/yii2-icon

You can manually install yii2-icon by downloading the source in ZIP-format.

Setup

For yii2-icon to work, some icon collection has to be installed on your site as well. In many cases this will be installed via npm, other collections (notably FontAwesome Free) via Composer. Refer to the icon provider's web site for details.

In any case, an application parameter named 'icons' has to be defined. This should describe the location of the icon files. The value may, and preferably should, be an Yii2 alias.

As an example, for FontAwesome Free, installed via composer, this will be:

'@vendor/fortawesome/font-awesome/svgs/{family}/{name}.svg'

{family} will be replaced by the icon family (like 'regular', 'solid', or 'thin').
{name} will be replaced by the icon name (like 'bicycle', 'chess-queen', or 'arrow-down').
{phosphor} will be replaced by a combination of icon family and icon name as expected by Phosphor Icons.

Icon families and names can be found at the icon provider's site.

As another example, for FontAwesome Pro, installed via npm, application parameter 'icons' should be:

'@app/node_modules/@fortawesome/fontawesome-pro/svgs/{family}/{name}.svg'

The preferred way to set the application parameter is to add it to 'params'-section of the main site configuration (often web.php, or main.php in the config-directory). The 'params'-section may look something like this:

'params' => [
    'adminEmail' => 'info@example.com',
    'supportEmail' => 'support@example.com',
    'icons'  => '@vendor/fortawesome/font-awesome/svgs/{family}/{name}.svg',
    // ... probably more parameters ...
],

If application parameter 'icons' is not set, yii2-icon will throw an error.

Next, the main layout view of the site (probably 'views/layouts/main.php') should be modified. At the top of the body-section, yii2-icon's class Icon has to render the SVG-symbols. The beginning of the main layout view should look something like this:

<?php

use ...
use sjaakp\icon\Icon;

//...
?>
...
<html ...>
<head> ... </head>
<body class=" ... ">
    <?php $this->beginBody() ?>
    <?= Icon::symbols($this) ?>

    // ...

Using yii2-icon

If everything is set up correctly, you can render icons anywhere in any view. For example, to render an icon of the regular family, just use something like this:

<?= Icon::regular('bicycle') ?>

Likewise for the other families:

<?= Icon::solid('heart') ?>
<?= Icon::light('bell') ?>

If an icon collection has no families, like the Bootstrap Icons, an icon can be rendered with:

<?= Icon::icon('camera') ?>

Styling

Icons can be extended with HTML options, like so:

<?= Icon::regular('bicycle', [ 'class' => 'blue' ]) ?>

By default, yii2-icon includes the FontAwesome styling classes, even for other font collections. This means that classes such as fa-lg, fa-rotate-90, will work out of the box. For example:

<?= Icon::solid('rotate', [ 'class' => 'fa-spin' ]) ?>

Class Icon

All functionality of yii2-icon is bundled in one abstract class, sjaakp\icon\Icon. It has only abstract functions:

renderIcon($fam, $name, $options = []) - render icon witn name $name from family $fam. Returns HTML.
symbols($view) - render the symbol table in View $view, preferably a Layout. Returns HTML.
reset() - reset yii2-icon's status from application parameter 'icons'. May come in handy in case of multiple icon collections.

All other function calls will be translated in a call to renderIcon, where the function name will be the value of $fam. Therefore, a function call like:

Icon::regular('bicycle', [ <options> ]);

will be interpreted as:

Icon::renderIcon('regular', 'bicycle', [ <options> ]);

How icons are rendered

Suppose we have a page with <?= Icon::solid('mug-hot', [ 'class' => 'fa-rotate-90' ]) ?> in it. It will be rendered like:

<body>
    <svg xmlns="http://www.w3.org/2000/svg"> <!-- invisible symbol table -->
        <symbol ...><path d="..."/></symbol>
        <symbol id="i-solid-mug-hot" viewBox="0 0 512 512"><path d="M400 192H32C14.25 192 ..."/></symbol>
        <symbol ...><path d="..."/></symbol> <!-- more symbols -->
    </svg>

    ...
    <!-- lots of other HTML -->
    ...

    ... <svg class="fa-rotate-90 svg-inline--fa">
            <use href="#i-solid-mug-hot"></use>
        </svg> ...

    ...

</body>

Gotcha

Icons in the main layout file may not be rendered if they come after the symbol table. One way to avoid this problem is by assigning the icon to a PHP-variable, like so:

<?php
/* views/layouts/main.php */

use ...
use sjaakp\icon\Icon;

$iconHouse = Icon::solid('house');

//...
?>
...
<html ...>
<head> ... </head>
<body class=" ... ">
    <?php $this->beginBody() ?>
    <?= Icon::symbols($this) ?>

    // ...

    Render house icon: <?= $iconHouse ?>.

    // ...

Advanced setup

In stead of the description of the icon SVG files location, the value of the application parameter 'icons' may also be an array with the following members:

location - the location of the icon SVG files, like previous described. Must be provided.
faCss - Optional. Whether Icon registers Font Awesome styling CSS. Default: true.
template - Optional. The template used for forming the icon's HTML id from the family and name. Default and example: 'i-{family}-{name}'.
iconClass - Optional. The CSS class(es) assigned to icons. Default: 'svg-inline--fa'.

Some icon resources

(Notice: '@node' is an alias for '@app/node_modules'.)

sjaakp / yii2-icon

Maintainers

Details