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.