Plugins

A plugin can hook in the compilation process and change its output by registering to events.

The events and callbacks defined by this package are as follow :

'beforeCompile': function (array $files) 
'afterCompile': function (array $files) 
'beforeCompileFile': function (ScssSource $source)
'afterCompileFile': function (ScssSource $source, CompilationResults $results)
'beforeWriteAssets': function (Assets $assets)
'afterWriteAssets': function (Assets $assets) 
'beforeAddAsset': function (Asset $asset)
'afterAddAsset': function (Asset $asset) 
'beforeExtractAssets': function (CompilationResults $results)
'afterExtractAssets': function (CompilationResults $results)
'extractAsset': function (string $path) : ?string  //returning a string will prevent other plugins to access this event
'beforeOptimize': function (CompilationResults $results)
'afterOptimize': function (CompilationResults $results)
'beforeWriteSourcemaps': function (CompilationResults $results, string $name, string $fileName)
'afterWriteSourcemaps': function (CompilationResults $results, string $name, string $fileName)
'importNotFound': function (string $import): ?string  //returning a string will prevent other plugins to access this event

Json manifest

use Ryssbowh\ScssPhp\plugins\JsonManifest;

$plugins = [
    new JsonManifest([
        'name' => 'manifest' //default
    ])
];
$compiler = new Compiler([
    'publicFolder' => '/path/to/public/folder'
], $plugins);

This plugin will write a json manifest file in the public folder at the end of compilation.
It defines 2 new events :

'beforeWriteManifest': function (string $file, array $manifest): ?array //Return an array to modify the manifest
'afterWriteManifest': function (array $file, array $manifest)

File loader

use Ryssbowh\ScssPhp\plugins\FileLoader;

$plugins = [
    new FileLoader([
        'test' => '/.+.(?:ico|jpg|jpeg|png|gif)([\?#].*)?$/',
        'limit' => 8192, //default
        'mimetype' => null //Auto detection
    ])
];
$compiler = new Compiler([
    'publicFolder' => '/path/to/public/folder'
], $plugins);

This plugin extract assets in the public folder, or encode them in base64.

The limit argument defines the limit of file sizes under which files will be encoded in base64, which would minimise your http connections to fetch assets. Keep in mind that encoding in base64 will raise the size of the final css file significantly.

This example would give you a good start to extract files and fonts :

$plugins = [
    new FileLoader([
        'test' => '/.+.(?:ico|jpg|jpeg|png|gif)([\?#].*)?$/',
    ]),
    new FileLoader([
        'test' => '/.+.svg([\?#].*)?$/',
    ]),
    new FileLoader([
        'test' => '/.+.ttf([\?#].*)?$/',
        'mimetype' => 'application/octet-stream',
    ]),
    new FileLoader([
        'test' => '/.+.woff([\?#].*)?$/',
        'mimetype' => 'application/font-woff',
    ]),
    new FileLoader([
        'test' => '/.+.woff2([\?#].*)?$/',
        'mimetype' => 'application/font-woff',
    ]),
    new FileLoader([
        'test' => '/.+.eot([\?#].*)?$/',
    ]),
];

Make your own plugins

A plugin only need to define a init function where it can register to some compilation events :

use Ryssbowh\ScssPhp\Compiler;
use Ryssbowh\ScssPhp\Plugin;

class MyPlugin extends Plugin
{
    public $argument;

    public function init(Compiler $compiler)
    {
        //Validate arguments here
        //Call parent init function
        parent::init($compiler);
        //Subscribe to events
        $this->compiler->on('beforeCompile', [$this, 'beforeCompile']);
    }

    //Optionally define new events this plugin will trigger
    public function defineEvents(): array
    {
        return ['beforeNewPlugin'];
    }

    //This will be called before the compilation starts
    public function beforeCompile(array $files)
    {
        //Optionally trigger a custom event
        $this->compiler->trigger('beforeNewPlugin');
    }
}

Compiler::on(string $event, $callable, int $order = 10) third argument $order is an int (default 10) defining the order the callback should be called in.