Skip to content

Latest commit

 

History

History
111 lines (88 loc) · 3.11 KB

asset-converter.md

File metadata and controls

111 lines (88 loc) · 3.11 KB
Raw

Asset converter

Asset converter purpose is to convert assets from one format to another. Out of the box it supports conversion of several popular formats into JavaScript and CSS.

Configuring asset conversion

In order to use asset conversion we have to configure it first. Let's see how it's done. As example let's convert SCSS into CSS.

We'll use foxy. Since it calls npm we'll need NodeJS installed. After it is done, create package.json:

{
    "license": "BSD-3-Clause",
    "dependencies": {
        "sass": "^1.77.0"
    }
}

npm install brings three packages into node_modules directory of our application.

Below we're using bootstrap bundle from "Asset bundles" guide:

namespace App\Assets;

use Yiisoft\Assets\AssetBundle;

/**
 * Asset bundle for the Twitter bootstrap css files.
 *
 * BootstrapAsset.
 */
final class BootstrapAsset extends AssetBundle
{
    public ?string $basePath = '@assets';
    public ?string $baseUrl = '@assetsUrl';
    public ?string $sourcePath = '@npm/bootstrap/scss';

    public array $css = [
        'bootstrap.scss',
    ];

    public array $publishOptions = [
        'only' => [
            'bootstrap.scss',
        ],
    ];

    public array $converterOptions = [
        'scss' => [
            'command' => '-I {path} --style compressed',
            'path' => '@root/tests/public/sourcepath/sass',
        ]
    ];
}

Since in $css we are pointing to .scss, asset manager asks asset converter to check if such a file could be converted to CSS. By default, asset converter has command definitions for less, scss, sass, styl, coffee and ts but since all these are meant to be installed globally, and we have it as local dependency, we need to redefine a command:

/**
 * @var \Psr\Log\LoggerInterface $logger
 * @var \Yiisoft\Aliases\Aliases $aliases
 * @var \Yiisoft\Assets\AssetManager $assetManager
 */

$converter = new \Yiisoft\Assets\AssetConverter($aliases, $logger, [
    'scss' => ['css', '@npm/.bin/sass {options} {from} {to}'],
]);
$assetManager = $assetManager->withConverter($converter);

or, if done via yiisoft/di container:

AssetConverterInterface::class => static function (\Psr\Container\ContainerInterface $container) {
    $aliases = $container->get(\Yiisoft\Aliases\Aliases::class);
    $logger = $container->get(\Psr\Log\LoggerInterface::class);
    return new \Yiisoft\Assets\AssetConverter($aliases, $logger, [
        'scss' => ['css', '@npm/.bin/sass {options} {from} {to}'],
    ]);
}

or, if done via params.php:

'yiisoft/assets' => [
    'assetConverter' => [
        'commands' => [
            'scss' => ['css', '@npm/.bin/sass {options} {from} {to}'],
        ],
        'forceConvert' => false,
    ],
],

Asset bundle's $converterOptions define additional options passed to conversion utility. In this case we're telling sass to minify resulting CSS.

Now, registering asset bundle as usual would result in asset conversion taking place:

$assetManager->register(\App\Assets\BootstrapAsset::class);