Sass (SCSS) and Compass support for the Yii framework
yii-sass extension implements Sass and Compass support: compilation on-the-fly,
publishing, registration in views., (*1)
, (*2)
External Sass tools are NOT used, compilation is done using PHP compiler., (*3)
Only SCSS syntax is supported.
Indented syntax is not supported., (*4)
Sass
is an extension of CSS that adds power and elegance to the basic language.
It allows you to use variables, nested rules, mixins, inline imports, and more,
all with a fully CSS-compatible syntax. Sass helps keep large stylesheets
well-organized, and get small stylesheets up and running quickly., (*5)
Compass
is an open-source CSS authoring framework which uses
the Sass stylesheet language to make writing stylesheets powerful and easy., (*6)
This extension caches compiled CSS code and prevents recompilation if there is no need in it., (*7)
Requirements
Installation
Installation can be done using
Composer
or manually by downloading required files., (*8)
- Install artem-frolov/yii-sass
package from Packagist.
Required libraries will be installed automatically.
Execute in your application's directory:
composer require artem-frolov/yii-sass "2.*"
-
Update your application's configuration (e.g. protected/config/main.php) like this:, (*9)
'aliases' => array(
...
// Path to your Composer's "vendor" directory
// You can remove this if you use Composer's autoloader and Yii >= 1.1.15
'vendor' => __DIR__ . '/../../../vendor',
),
...
'components' => array(
...
'sass' => array(
// Path to the SassHandler class
// You need the full path only if you don't use Composer's autoloader
'class' => 'vendor.artem-frolov.yii-sass.SassHandler',
// Use the following if you use Composer's autoloader and Yii >= 1.1.15
//'class' => 'SassHandler',
// Enable Compass support, defaults to false
'enableCompass' => true,
),
...
),
Install manually
-
Download yii-sass extension
Put files to the "protected/extensions/yii-sass" directory so the path to the SassHandler.php
will look like "protected/extensions/yii-sass/SassHandler.php"
-
Download scssphp compiler
Put files to the "protected/vendor/scssphp" directory
-
Download scssphp-compass library
Skip this step if you don't need Compass support
Put files to the "protected/vendor/scssphp-compass" directory
-
Update your application's configuration (e.g. protected/config/main.php) like this:, (*10)
'components' => array(
...
'sass' => array(
// Path to the SassHandler class
'class' => 'ext.yii-sass.SassHandler',
// Path and filename of scss.inc.php
'compilerPath' => __DIR__ . '/../vendor/scssphp/scss.inc.php',
// Path and filename of compass.inc.php
// Required only if Compass support is needed
'compassPath' => __DIR__ . '/../vendor/scssphp-compass/compass.inc.php',
// Enable Compass support, defaults to false
'enableCompass' => true,
),
...
),
Usage
Add the code like the following to your views/layout.
It will compile SCSS file (or recompile if needed), publish and register compiled CSS file:, (*11)
Yii::app()->sass->register(
Yii::getPathOfAlias('application.assets.sass') . '/your-file.scss'
);
Component options
All options below are optional except the "class" item., (*12)
'components' => array(
...
'sass' => array(
// Path to the SassHandler class
'class' => 'vendor.artem-frolov.yii-sass.SassHandler',
// Path and filename of scss.inc.php
// Defaults to the relative location in Composer's vendor directory
'compilerPath' => __DIR__ . "/../../../vendor/leafo/scssphp/scss.inc.php",
// Path and filename of compass.inc.php
// Required only if Compass support is needed
// Defaults to the relative location in Composer's vendor directory
'compassPath' => __DIR__ . '/../../../vendor/leafo/scssphp-compass/compass.inc.php',
// Path for cache files. Will be used if Yii caching is not enabled.
// Will be chmod'ed to become writable,
// see "writableDirectoryPermissions" parameter.
// Yii aliases can be used.
// Defaults to 'application.runtime.sass-cache'
'cachePath' => 'application.runtime.sass-cache',
// Enable Compass support.
// Automatically add required import paths and functions.
// Defaults to false
'enableCompass' => false,
// Path to a directory with compiled CSS files.
// Will be created automatically if it doesn't exist.
// Will be chmod'ed to become writable,
// see "writableDirectoryPermissions" parameter.
// Yii aliases can be used.
// Defaults to 'application.runtime.sass-compiled'
'sassCompiledPath' => 'application.runtime.sass-compiled',
// Force compilation/recompilation on each request.
// False value means that compilation will be done only if
// source SCSS file or related imported files have been
// changed after previous compilation.
// Defaults to false
'forceCompilation' => false,
// Turn on/off overwriting of already compiled CSS files.
// Will be ignored if "forceCompilation" parameter's value is true.
//
// True value means that compiled CSS file will be overwriten
// if the source SCSS file or related imported files have
// been changed after previous compilation.
//
// False value means that compilation will be done only if
// an output CSS file doesn't exist.
//
// Defaults to true
'allowOverwrite' => true,
// Automatically add directory containing SCSS file being processed
// as an import path for the @import Sass directive.
// Defaults to true
'autoAddCurrentDirectoryAsImportPath' => true,
// List of import paths.
// Can be a list of strings or callable functions:
// function($searchPath) {return $targetPath;}
// Defaults to an empty array
'importPaths' => array(),
// Chmod permissions used for creating/updating of writable
// directories for cache files and compiled CSS files.
// Mind the leading zero for octal values.
// Defaults to 0777
'writableDirectoryPermissions' => 0777,
// Chmod permissions used for creating/updating of writable
// cache files and compiled CSS files.
// Mind the leading zero for octal values.
// Defaults to 0666
'writableFilePermissions' => 0666,
// Default value for $hashByName parameter in extension's methods.
// $hashByName value determines whether the published file should be named
// as the hashed basename. If false, the name will be the hash taken
// from dirname of the path being published and path mtime.
//
// Set to true if the path being published is shared
// among different extensions.
//
// Defaults to false
// @see CAssetManager::publish()
'defaultHashByName' => false,
// Customize the formatting of the output CSS.
// Use one of the SassHandler::OUTPUT_FORMATTING_* constants
// to set the formatting type.
// @link http://leafo.net/scssphp/docs/#output_formatting
// Default is OUTPUT_FORMATTING_NESTED
'compilerOutputFormatting' => SassHandler::OUTPUT_FORMATTING_NESTED,
// Id of the cache application component.
// Defaults to 'cache' (the primary cache application component)
'cacheComponentId' => 'cache',
),
...
),
Component methods
/**
* Publish and register compiled CSS file.
* Compile/recompile source SCSS file if needed.
*
* Optionally can publish compiled CSS file inside specific published directory.
* It's helpful when CSS code has relative references to other
* resources (images/fonts) and when these resources are also published
* using Yii asset manager. This method allows to publish compiled CSS files
* along with other resources to make relative references work.
*
* E.g.:
* "image.jpg" is stored inside path alias "application.files.images"
* Somewhere in the code the following is called during page generation:
* Yii::app()->assetManager->publish(Yii::getPathOfAlias('application.files'));
* SCSS file has the following code: background-image: url(../images/image.jpg);
* Then the correct call of the method will be:
* Yii::app()->sass->register(
* 'path-to-scss-file.scss',
* '',
* 'application.files',
* 'css_compiled'
* );
*
* @param string $sourcePath Path to the source SCSS file
* @param string $media Media that the CSS file should be applied to.
* If empty,it means all media types
* @param string $insidePublishedDirectory Path to the directory with
* resource files which is published somewhere in the application explicitly.
* Default is null which means that CSS file will be published separately.
* @param string $subDirectory Subdirectory for the CSS file within
* publicly available location. Default is null
* @param boolean $hashByName Must be the same as in the CAssetManager::publish() call
* for $insidePublishedDirectory. See CAssetManager::publish() for details.
* "defaultHashByName" plugin parameter's value is used by default.
*/
Yii::app()->sass->register(
$sourcePath,
$media = '',
$insidePublishedDirectory = null,
$subDirectory = null,
$hashByName = null
);
/**
* Publish compiled CSS file.
* Compile/recompile source SCSS file if needed.
*
* Optionally can publish compiled CSS file inside specific published directory.
* It's helpful when CSS code has relative references to other
* resources (images/fonts) and when these resources are also published
* using Yii asset manager. This method allows to publish compiled CSS files
* along with other resources to make relative references work.
*
* E.g.:
* "image.jpg" is stored inside path alias "application.files.images"
* Somewhere in the code the following is called during page generation:
* Yii::app()->assetManager->publish(Yii::getPathOfAlias('application.files'));
* SCSS file has the following code: background-image: url(../images/image.jpg);
* Then the correct call of the method will be:
* Yii::app()->sass->publish('path-to-scss-file.scss', 'application.files', 'css_compiled');
*
* @param string $sourcePath Path to the source SCSS file
* @param string $insidePublishedDirectory Path to the directory with resource files
* which is published somewhere in the application explicitly.
* Default is null which means that CSS file will be published separately.
* @param string $subDirectory Subdirectory for the CSS file within publicly
* available location. Default is null
* @param boolean $hashByName Must be the same as in the CAssetManager::publish() call
* for $insidePublishedDirectory. See CAssetManager::publish() for details.
* "defaultHashByName" plugin parameter's value is used by default.
* @return string URL of the published CSS file
*/
Yii::app()->sass->publish(
$sourcePath,
$insidePublishedDirectory = null,
$subDirectory = null,
$hashByName = null
);
/**
* Get path to the compiled CSS file, compile/recompile source file if needed
*
* @param string $sourcePath Path to the source SCSS file
* @throws CException
* @return string
*/
Yii::app()->sass->getCompiledFile($sourcePath);
/**
* Compile SCSS file
*
* @param string $sourcePath
* @throws CException
* @return string Compiled CSS code
*/
Yii::app()->sass->compile($sourcePath);
/**
* Get compiler
* Loads required files on initial request
*
* @return ExtendedScssc
*/
Yii::app()->sass->getCompiler();
Unit Tests
Execute the following commands in the root directory of yii-sass
extension to run unit tests., (*13)
For Windows:, (*14)
composer install
vendor\bin\phpunit
For Linux/Mac/etc.:, (*15)
composer install
vendor/bin/phpunit
Changelog
-
Version 2.0.1 — 2017-11-09, (*16)
- #15: Fix an error with the compilation of empty files (tomaszbrunarski)
-
Version 2.0.0 — 2017-05-01, (*17)
- Update scssphp compiler to version ~0.6.7
- Minimum required PHP version is changed to >= 5.4.0
- Allow to use custom Yii caching components by configuring "cacheComponentId" option
-
Version 1.3.0 — 2015-02-21, (*18)
- Fix
CAssetManager::publish() call - pass $hashByName value used in
Yii::app()->sass->publish() and Yii::app()->sass->register() methods
- Remove deprecated PHPUnit
strict setting
- Do not use unstable (
dev-master) version of scssphp compiler anymore
when Composer is used to install yii-sass extension
- Make installation via Composer easier -
minimum-stability setting
is not needed anymore
- Add
writableFilePermissions option (defaults to 0666),
fix file permissions issues with certain umask settings in OS by calling
chmod for created/updated files, always call chmod for writable directories
- Add
defaultHashByName setting which allows to set a default $hashByName
value for all plugin's methods
- Add more information to exceptions' messages
- Enable Travis CI builds
- Update documentation
-
Version 1.2.1 — 2014-11-04, (*19)
- Bug #4: Don't overwrite a compiled file during the compilation of another
source file which has the same basename
-
Version 1.2.0 — 2014-08-12, (*20)
- Fix compatibility with the new
0.1 version of the
scssphp compiler (alexdevid)
- Set minimum required PHP version to 5.3 because the new version
of
scssphp compiler requires it
- Add new formatting type
SassHandler::OUTPUT_FORMATTING_CRUNCHED which
can be used with compilerOutputFormatting parameter (alexdevid)
- Add unit tests to check integration with
scssphp compiler
and with scssphp-compass library
- Fix a bug:
$hashByName=true argument wasn't properly passed to the Yii's asset manager
- Minor fixes and improvements
-
Version 1.1.0 — 2014-02-07, (*21)
- Allow to register and publish compiled CSS files inside specific published
directory to allow using of relative references in CSS for images, fonts and
other published files
- Add
compilerOutputFormatting component option, allow to switch between
simple, nested and compressed (Pavel Volyntsev)
- Change default value of the
writableDirectoryPermissions component option
from 0644 to 0777. It should prevent permission errors on some Linux servers
- Update code style and documentation
-
Version 1.0.0 — 2013-12-16, (*22)
Resources
Wallogit.com
