README

yii-sass 扩展实现了 Sass 和 Compass 支持：即时编译、发布、视图注册。

不使用外部 Sass 工具，编译通过 PHP 编译器完成。

仅支持 SCSS 语法。
不支持缩进语法。

Sass 是 CSS 的扩展，为基本语言增加了力量和优雅。它允许您使用变量、嵌套规则、混合、内联导入等，所有这些都使用完全兼容 CSS 的语法。Sass 有助于保持大型样式表井然有序，并快速启动小型样式表。

Compass 是一个开源的 CSS 编写框架，它使用 Sass 样式表语言使编写样式表变得强大且简单。

此扩展缓存编译的 CSS 代码，并在不需要时防止重新编译。

要求

PHP >= 5.4
Yii 1.0 或 1.1
scssphp 编译器
scssphp-compass 库 - 如果需要 Compass 支持，则需要

安装

可以使用 Composer 或手动下载所需文件进行安装。

使用 Composer 安装

从 Packagist 安装 artem-frolov/yii-sass 包。将自动安装所需库。
在应用程序目录中执行
```
composer require artem-frolov/yii-sass "2.*"
```

更新应用程序配置 (例如 protected/config/main.php) 如下

'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,
    ),
    ...
),

手动安装

下载 yii-sass 扩展
将文件放入 "protected/extensions/yii-sass" 目录，以便 SassHandler.php 的路径看起来像 "protected/extensions/yii-sass/SassHandler.php"
下载 scssphp 编译器
将文件放入 "protected/vendor/scssphp" 目录
下载 scssphp-compass 库
如果不需要 Compass 支持，则跳过此步骤
将文件放入 "protected/vendor/scssphp-compass" 目录

更新应用程序配置 (例如 protected/config/main.php) 如下

'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,
    ),
    ...
),

用法

将以下代码添加到您的视图布局中。
它将编译 SCSS 文件（如果需要，则重新编译），发布并注册编译后的 CSS 文件

Yii::app()->sass->register(
    Yii::getPathOfAlias('application.assets.sass') . '/your-file.scss'
);

组件选项

以下所有选项都是可选的，除了 "class" 项。

'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',
    ),
    ...
),

组件方法

/**
 * 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();

单元测试

在 yii-sass 扩展根目录中执行以下命令以运行单元测试。

对于 Windows

composer install
vendor\bin\phpunit

对于 Linux/Mac 等。

composer install
vendor/bin/phpunit

变更日志

版本 2.0.1 — 2017-11-09
- #15: 修复了空文件的编译错误 (tomaszbrunarski)
版本 2.0.0 — 2017-05-01
- 更新 scssphp 编译器到版本 ~0.6.7
- 最低要求的 PHP 版本更改为 >= 5.4.0
- 允许通过配置 "cacheComponentId" 选项使用自定义 Yii 缓存组件
版本 1.3.0 — 2015-02-21
- 修复了 CAssetManager::publish() 调用 - 将 $hashByName 值传递给 Yii::app()->sass->publish() 和 Yii::app()->sass->register() 方法
- 删除了过时的 PHPUnit strict 设置
- 不再使用当使用 Composer 安装 yii-sass 扩展时安装的 scssphp 编译器的 "dev-master" 版本
- 通过 Composer 安装更容易 - 不再需要 "minimum-stability" 设置
- 添加 writableFilePermissions 选项（默认为 0666），通过调用 chmod 为创建/更新的文件修复操作系统中的某些 umask 设置导致的文件权限问题，始终为可写目录调用 chmod
- 添加 defaultHashByName 设置，允许为所有插件方法设置默认的 $hashByName 值
- 为异常信息添加更多详细信息
- 启用 Travis CI 构建
- 更新文档
版本 1.2.1 — 2014-11-04
- 错误 #4：在编译具有相同基本名的另一个源文件时，不要覆盖已编译的文件
版本 1.2.0 — 2014-08-12
- 修复与 scssphp 编译器新 0.1 版本的兼容性问题 (alexdevid)
- 将最低要求的 PHP 版本设置为 5.3，因为新的 scssphp 编译器需要它
- 添加新的格式化类型 SassHandler::OUTPUT_FORMATTING_CRUNCHED，可以与 compilerOutputFormatting 参数一起使用 (alexdevid)
- 添加单元测试以检查与 scssphp 编译器和 scssphp-compass 库的集成
- 修复一个错误：未正确传递 $hashByName=true 参数到 Yii 的资产管理器
- 小幅度修复和改进
版本 1.1.0 — 2014-02-07
- 允许在特定发布的目录内注册和发布编译的 CSS 文件，以允许在 CSS 中使用图像、字体和其他发布文件的相对引用
- 添加 compilerOutputFormatting 组件选项，允许在 simple、nested 和 compressed 之间切换 (Pavel Volyntsev)
- 将 writableDirectoryPermissions 组件选项的默认值从 0644 更改为 0777。它应该可以防止某些 Linux 服务器上的权限错误
- 更新代码风格和文档
版本 1.0.0 — 2013-12-16
- 首次发布

artem-frolov / yii-sass

维护者

详细信息