scssphp 0.0.12 Documentation
The entire project comes in a single file. Just include it somewhere to start using it:
require "scssphp/scss.inc.php"; Compiling
In order to manually compile code from PHP you must create an instance of the scssc class. The typical flow is to create the instance, set any compile time options, then run the compiler with the compile method.
require "scssphp/scss.inc.php"; $scss = new scssc(); echo $scss->compile(' $color: #abc; div '); - compile($scssCode) will attempt to compile a string of SCSS code. If it succeeds then the CSS will be returned as a string. If there is any error, an exception is thrown with an appropriate error message.
Import Paths
When you import a file using the @import directive, the current path of your PHP script is used as the search path by default. This is often not what you want, so there are two methods for manipulating the import path: addImportPath , and setImportPaths .
- addImportPath($path) will append $path to the list of the import paths that are searched.
- setImportPaths($pathArray) will replace the entire import path with $pathArray . The value of $pathArray will be converted to an array if it isn’t one already.
If the import path is set to array() then importing is effectively disabled. The default import path is array(«») , which means the current directory.
require "scssphp/scss.inc.php"; $scss = new scssc(); $scss->setImportPaths("assets/stylesheets/"); // will search for `assets/stylesheets/mixins.scss' echo $scss->compile('@import "mixins.scss"'); Besides adding static import paths, it’s also possible to add custom import functions. This allows you to load paths from a database, or HTTP, or using files that SCSS would otherwise not process (such as vanilla CSS imports).
require "scssphp/scss.inc.php"; $scss = new scssc(); $scss->addImportPath(function($path) if (!file_exists('stylesheets/'.$path)) return null; return 'stylesheets/'.$path; >); // will import `stylesheets/vanilla.css' echo $scss->compile('@import "vanilla.css"'); Output Formatting
It’s possible to customize the formatting of the output CSS by changing the default formatter.
Three formatters are included:
We can change the formatting using the setFormatter method.
- setFormatter($formatterName) sets the current formatter to $formatterName , the name of a class as a string that implements the formatting interface. See the source for scss_formatter for an example.
.navigation ul line-height: 20px; color: blue; a color: red; > > > .footer .copyright color: silver; > > The formatters will output,
.navigation ul line-height: 20px; color: blue; > .navigation ul a color: red; > .footer .copyright color: silver; > .navigation ul line-height: 20px; color: blue; > .navigation ul a color: red; > .footer .copyright color: silver; > .navigation ulline-height:20px;color:blue;>.navigation ul acolor:red;>.footer .copyrightcolor:silver;> Custom Functions
It’s possible to register custom functions written in PHP that can be called from SCSS. Some possible applications include appending your assets directory to a URL with an asset-url function, or converting image URLs to an embedded data URI to reduce the number of requests on a page with a data-uri function.
We can add and remove functions using the methods registerFunction and unregisterFunction .
- registerFunction($functionName, $callable) assigns the callable value to the name $functionName . The name is normalized using the rules of SCSS. Meaning underscores and dashes are interchangeable. If a function with the same name already exists then it is replaced.
- unregisterFunction($functionName) removes $functionName from the list of available functions.
The $callable can be anything that PHP knows how to call using call_user_func . The function receives two arguments when invoked. The first is an array of SCSS typed arguments that the function was sent. The second is a reference to the current scss instance.
The SCSS typed arguments are actually just arrays that represent SCSS values. SCSS has different types than PHP, and this is how scssphp represents them internally.
For example, the value 10px in PHP would be array(«number», 1, «px») . There is a large variety of types. Experiment with a debugging function like print_r to examine the possible inputs.
The return value of the custom function can either be a SCSS type or a basic PHP type. (such as a string or a number) If it’s a PHP type, it will be converted automatically to the corresponding SCSS type.
As an example, a function called add-two is registered, which adds two numbers together. PHP’s anonymous function syntax is used to define the function.
$scss = new scssc(); $scss->registerFunction("add-two", function($args) list($a, $b) = $args; return $a[1] + $b[1]; >); $scss->compile('.ex1 < result: add-two(10, 10); >'); It’s worth noting that in this example we lose the units of the number, and we also don’t do any type checking. This will have undefined results if we give it anything other than two numbers.
SCSS Server
The SCSS server is a small class that helps with automatically compiling SCSS.
It’s an endpoint for your web application that searches for SCSS files in a directory then compiles and serves them as CSS. It will only compile files if they’ve been modified (or one of the imports has been modified).
Using serveFrom
scss_server::serveFrom is a simple to use function that should handle most cases.
For example, create a file style.php :
$directory = "stylesheets"; require "scssphp/scss.inc.php"; scss_server::serveFrom($directory); Going to the URL example.com/style.php/style.scss will attempt to compile style.scss from the stylesheets directory, and serve it as CSS.
- scss_server::serveFrom($directory) will serve SCSS files out of $directory . It will attempt to get the path to the file out of $_SERVER[«PATH_INFO»] . (It also looks at the GET parameter p )
If it can not find the file it will return an HTTP 404 page:
/* INPUT NOT FOUND scss v0.0.1 */ If the file can’t be compiled due to an error, then an HTTP 500 page is returned. Similar to the following:
Parse error: parse error: failed at `height: ;` stylesheets/test.scss on line 8 By default , the SCSS server must have write access to the style sheet directory. It writes its cache in a special directory called scss_cache .
Also, because SCSS server writes headers, make sure no output is written before it runs.
Using scss_server
Creating an instance of scss_server is just another way of accomplishing what serveFrom does. It let’s us customize the cache directory and the instance of the scssc that is used to compile
- new scss_server($sourceDir, $cacheDir, $scss) creates a new server that serves files from $sourceDir . The cache dir is where the cached compiled files are placed. When null , $sourceDir . «/scss_cache» is used. $scss is the instance of scss that is used to compile.
Just call the serve method to let it render its output.
Here’s an example of creating a SCSS server that outputs compressed CSS:
require "scssphp/scss.inc.php"; $scss = new scssc(); $scss->setFormatter("scss_formatter_compressed"); $server = new scss_server("stylesheets", null, $scss); $server->serve(); Command Line Tool
A really basic command line tool is included for integration with scripts. It is called pscss . It reads a SCSS file from standard out and returns the CSS.
If passed the flag -v , input is ignored and the current version if returned.
The flag -f can be used to set the formatter:
$ ./pscss -f scss_formatter_compressed < styles.scssscssphp v1.11.0 Documentation
The project can be loaded through the composer generated auto-loader.
Alternatively, the entire project can be loaded through a utility file. Just include it somewhere to start using it:
require_once 'scssphp/scss.inc.php'; Compiling
In order to manually compile code from PHP you must create an instance of the Compiler class. The typical flow is to create the instance, set any compile time options, then run the compiler with the compile method.
use ScssPhp\ScssPhp\Compiler; $compiler = new Compiler(); echo $compiler->compileString(' $color: #abc; div < color: lighten($color, 20%); >')->getCss(); compileString($scssCode, $path = null) will attempt to compile a string of SCSS code. If it succeeds, a \ScssPhp\ScssPhp\CompilationResult containing the CSS will be returned. If there is any error, a \ScssPhp\ScssPhp\Exception\SassException is thrown with an appropriate error message.
Import Paths
When you import a file using the @import directive, the import is resolved relatively to the current file. The input of compileString is considered to be in the provided path. If no path is provided, relative imports won’t be resolved. Imports paths will need to be used. In case you want to load files from other folders, there are two methods for manipulating the import path: addImportPath , and setImportPaths .
- addImportPath($path) will append $path to the list of the import paths that are searched.
- setImportPaths($pathArray) will replace the entire list of import paths with $pathArray . The value of $pathArray will be converted to an array if it isn’t one already.
use ScssPhp\ScssPhp\Compiler; $compiler = new Compiler(); $compiler->setImportPaths('assets/stylesheets/'); // will search for 'assets/stylesheets/mixins.scss' echo $compiler->compileString('@import "mixins.scss";')->getCss(); Besides adding static import paths, it’s also possible to add custom import functions.
A list of the included files can be retrieved using the getIncludedFiles method of the CompilationResult . The input file is not included in this list.
Output Formatting
The output formatting can be configured using the setOutputStyle method. 2 styles are provided: \ScssPhp\ScssPhp\OutputStyle::EXPANDED and \ScssPhp\ScssPhp\OutputStyle::COMPRESSED .
/*! Comment */ .navigation ul line-height: 20px; color: blue; a color: red; > > > .footer .copyright color: silver; > > The output will look like that:
/*! Comment */ .navigation ul line-height: 20px; color: blue; > .navigation ul a color: red; > .footer .copyright color: silver; > /* Comment*/.navigation ulline-height:20px;color:blue;>.navigation ul acolor:red;>.footer .copyrightcolor:silver;> Source Maps
Source Maps are useful in debugging compiled css files using browser developer tools.
To enable source maps, use the setSourceMap() and setSourceMapOptions() methods.
use ScssPhp\ScssPhp\Compiler; $compiler = new Compiler(); $compiler->setSourceMap(Compiler::SOURCE_MAP_FILE); $compiler->setSourceMapOptions([ // relative or full url to the above .map file 'sourceMapURL' => './my-style.map', // (optional) relative or full url to the .css file 'sourceMapFilename' => 'my-style.css', // partial path (server root) removed (normalized) to create a relative url 'sourceMapBasepath' => '/var/www/vhost', // (optional) prepended to 'source' field entries for relocating source files 'sourceRoot' => '/', ]); $result = $compiler->compileString('@import "sub.scss";'); file_put_contents('/var/www/vhost/my-style.map', $result->getSourceMap()); file_put_contents('/var/www/vhost/my-style.css', $result->getCss()); // use Compiler::SOURCE_MAP_INLINE for inline (comment-based) source maps Extending scssphp
The Compiler supports several extension points for advanced usages. They are documented in the documentation about extension points.
Security Considerations
If your web application compiles SCSS on-the-fly, you need to handle any potential exceptions thrown by the Compiler. This is especially important in a production environment where the content may be untrusted (e.g., user uploaded) because the exception stack trace may contain sensitive data.
use ScssPhp\ScssPhp\Compiler; try $compiler = new Compiler(); echo $compiler->compileString($content)->getCss(); > catch (\Exception $e) echo ''; syslog(LOG_ERR, 'scssphp: Unable to compile content'); > If your web application allows for arbitrary @import paths, you should tighten the open_basedir setting at run-time to mitigate vulnerability to local file inclusion (LFI) attack.