Download the PHP package ryssbowh/scss-php-compiler without Composer

Based on scssphp/scssphp this package allows more control on the compilation process through plugins, a bit similar to how webpack does it. That allows for example to define aliases, custom imports, asset extraction, manifest, name hashing and all sorts of plugins.

The compiler allows compiling several files at the same time, all outputed in the same public folder. During the compilation it will trigger events that any plugin can subscribe to, here's the general workflow :

• plugins are initialised
• compilation starts
• a file compilation starts
• asset extraction starts
• asset extraction ends
• css optimisation starts
• css optimisation ends
• sourcemap writing starts
• sourcemap writing ends
• a file compilation ends
• assets are written on disk
• compilation ends

Usage

Here's how to define a new compiler with default options and run it :

First argument of compile is an array index by the relative path (to the source folder) of the scss files, the values are relative paths (to the public folder) or absolute paths of css files. If you give relative paths, the absolute path will be built using the second argument.

Second argument is the source folder, where all imports will be considered from.

Third argument is to "fake" the source file (see below)

Default options for the compiler :

This example won't extract assets so unless your assets paths match in the scss, chances are they will not resolve. It won't write a manifest either. For that you need plugins.

Faking the source folder

In some (probably rare) cases you may want to compile a scss file situated in a folder as if it was in another folder, in this example we want the compiler to consider that folder1/src.scss as if it was in the folder2/templates folder :

If you were using the example above to compile, the assets wouldn't be found, as they are in a different folder. Compiling with this :

will resolve your imports and asset urls nicely, giving this results (assuming you have a plugin that extracts the .jpg files) :

Aliases

Aliases can be set to resolve imports :

The aliases can be subfolders (like assets/node_modules) and are relative to the source folder. After this example you'll be able to write in your scss :

Import paths

You can define custom import paths, the compiler will look in those folders if it can't find an import in the current folder :

The compiler will resolve imports according to the folder structure of the current file and look into import paths by ascending order. An example that would work :

app.scss :

:warning: Import paths apply to the @custom rule only, not to assets defined within url() functions.

Logging

The compiler constructor accepts a 3rd argument to define your own logger :

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 :

Json manifest

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

File loader

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 :

Make your own plugins

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

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.

Roadmap

• chunking
• async events