README

基于 Yii 的包系统的一个 JavaScript/CSS 压缩器。

要求

必须安装 Java 运行时环境以使用 YUI 压缩器

特性

使用 YUI 压缩器压缩 Yii 客户端脚本包
不会干扰包外注册的脚本和 CSS
自动或手动触发压缩
用于防止多次并发压缩的锁定机制
解决 thundering herd 问题的工作方式
命令行维护脚本

你可能想知道，为什么还需要另一个压缩扩展扩展扩展为 Yii？关键区别是，现有的所有解决方案都没有使用 Yii 集成的包系统用于客户端脚本。通过此扩展，您可以将所有 CSS 和 JavaScript 组织成包，甚至定义它们之间的依赖关系。这可能对较小的网站来说不是非常有用（尽管您仍然可以在那里使用压缩器）。但当你需要处理许多 JavaScript 文件并将它们聚类成几个压缩包文件时，这非常有用。

注意：您甚至可以将 Yii 的核心脚本包含在包中。不幸的是，一些 Zii 小部件（如 CListView 和 CGridView）仍然没有使用包系统。但希望这将在 Yii 1.1.15 中得到修复。

基本示例

包在您的配置文件中设置。JavaScript 和 CSS 包必须分开。以下是一个示例

<?php
return array(
    // ...
    'clientScript' => array(
        'class'                 => 'ext.packagecompressor.PackageCompressor'
        'coreScriptPosition'    => 2,   // == POS_END
        'packages' => array(

            'forum-js' => array(
                'baseUrl' => 'js',
                'depends' => array('jQuery', 'maskedinput'),
                'js' => array(
                    'modules/main.js',
                    'modules/editor.js',
                    'modules/forum.post.js',
                    'modules/forum.notify.js',
                ),
            ),
            'forum-css' => array(
                // requires write permission for this directory
                'baseUrl' => 'css',
                'css' => array(
                    'main.css',
                    'forum.css',
                ),
            ),
        ),
    ),
    // ...
);

有了上述定义的包，您现在可以例如在您网站的论坛部分注册论坛包

Yii::app()->clientScript->registerPackage('forum-js');
Yii::app()->clientScript->registerPackage('forum-css');

您的用户将接收单个的 js 和 CSS 文件，直到您使用以下命令重置一个包

./yiic packages reset

它是如何工作的？

每当通过 registerPackage() 注册一个包时，就会为用户服务一个单独的压缩文件。如果没有压缩文件，则从包中组合并压缩所有文件，然后此单个文件由资产管理器发布。扩展使用应用程序状态（该状态会自动缓存）来存储有关压缩包的信息。因此，在压缩的初始延迟之后，所有后续请求都将快速交付压缩文件。

还有一个命令行工具可以手动为包创建压缩文件，例如在部署时，以及重置包。

压缩文件名将包含一个哈希值，以确保访客永远不会收到过时的压缩包版本。

安装

将包解压缩到 protected/extensions 中的 packagecompressor 目录（删除 -x.y.z 后缀）。然后配置组件以替换 Yii 的 CClientScript 组件

受保护的/config/main.php

<?php
return array(
    // ...
    'components' => array(

        'clientScript' => array(
            'class' => 'ext.packagecompressor.PackageCompressor'
        ),
        // ...
    ),
    // ...
);

如果您想使用命令行工具，您应该在控制台配置中使捆绑的命令可用

受保护的/config/console.php

<?php
return array(
    // ...
    'commandMap' => array(
        'packages' => array(
            'class' => 'ext.packagecompressor.PackagesCommand',
        ),
        // ...
    ),
    // ...
);

配置

除了常用的 CClientScript 属性外，打包程序还添加了以下其他配置选项，您可以在您的 main.php 配置文件中设置这些选项

enableCompression：是否启用压缩。默认为 true。建议在开发期间关闭此选项。
enableCssImageFingerPrinting：是否启用CSS图像的自动指纹识别，例如根据图像文件的md5散列添加 ?acd4gd3sz。
combineOnly：是否仅组合所有文件，而不压缩。默认为 false。这对于调试打包问题非常有用。
blockDuringCompression：是否在压缩期间暂停其他请求。默认为 true。这在高负载的网站上可能会出现问题，因为暂停的进程可能会消耗所有服务器资源。作为一个解决方案，您可以将其设置为 false。在这种情况下，在压缩期间，任何并发请求都将提供未压缩的单个文件。如果您也不希望这样，您仍然可以在部署之前从命令行创建压缩版本。
javaBin：Java二进制文件的路径。默认为 java，它假定JRE二进制文件在您的操作系统搜索路径中可用（在Linux系统上通常是这样的）。

命令行维护

该组件为yiic提供了一个维护命令。它可以用于从命令行压缩包、重置包或输出有关压缩包的详细信息。

注意：重要的是，您的Web配置中的包配置也应在您的控制台配置中可用。这意味着，您需要在您的 console.php 中具有相同的 clientScript 配置。您可能希望使用共享的包含文件来这样做。如果您想从命令行压缩，您还需要配置资产管理和 webroot 的别名。您还需要修复与 request 组件的问题，它在控制台返回 '.' 作为baseUrl
<?php
  'aliases' => array(
      'webroot' => realpath(__DIR__.'/../..'),
  ),
  'components' =>
      'assetManager'=>array(
          'class'     =>'CAssetManager',
          'basePath'  =>realpath(__DIR__.'/../../assets'),
          'baseUrl'   =>'/assets',
      ),
      'request' => array(
          'baseUrl' => '',
      ),
      //...

注意 2：如果您想重置包，则需要从命令行对 protected/runtime 目录中的 state.bin 文件具有写入权限。

压缩包

./yiic packages compress --name=<packagename>

显示压缩包的元信息

./yiic packages info --name=<packagename>

重置所有压缩包

./yiic packages reset

重置特定包

./yiic packages reset --name=<packagename>

高级示例：CSS资产

CSS文件通常包含对某些资产文件（图像）的相对URL引用。因此，如果压缩CSS文件发布到资产目录，则这些路径将会损坏（除非我们也发布图像，但我们不这样做）。作为一个解决方案，您可以将CSS包发布到源文件所在的同一文件夹中。因此，您必须在包中指定一个 baseUrl。

<?php
return array(
    // ...
    'forum-css' => array(
        'baseUrl' => 'css',
        'css' => array(
            'main.css',
            'forum.css',
        ),
    ),
    // ...
)

现在您可以通过以下方式注册此CSS包

Yii::app()->clientScript->registerPackage('forum-css');

注意：在这里，Web服务器进程必须对CSS文件夹具有写入权限。

高级示例：CSS的媒体支持

CSS包可以包含一个在注册包时使用的 media 规范。

<?php
return array(
    // ...
    'main-css' => array(
        'baseUrl' => 'css',
        'media' => 'screen',
        'css' => array(
            'main.css',
            'forum.css',
        ),
    ),
    'main-css' => array(
        'baseUrl' => 'css',
        'media' => 'print',
        'css' => array(
            'print.css',
        ),
    ),
    // ...
)

高级示例：来自CDN的jQUery

如果您想使用CDN为jQuery配置，可以像不使用压缩器一样配置它。注册此类包时，一切都会正常工作。

<?php
return array(
    // ...
    'clientScript' => array(
        'class'                 => 'ext.packagecompressor.PackageCompressor'
        'coreScriptPosition'    => 2,   // == POS_END
        'scriptMap' => array(
            'jquery.js' => 'https://ajax.googleapis.ac.cn/ajax/libs/jquery/1.8.3/jquery.js',
        ),
        'packages' => array(

            'forum' => array(
                'depends' => array('jQuery', 'maskedinput'),
                'js' => array(
                    // ...
                ),
            ),

        ),
    ),
    // ...
),

已知问题和限制

PackageCompressor 与 Yii的assetManager中的绝对 baseUrl（例如，CDN托管）不兼容

变更日志

1.0.4

修复没有协议的外部URL，例如 //ajax.googleapis.ac.cn/ajax/libs/jquery/1.8.3/jquery.js

1.0.3

为CSS添加 media 支持。

1.0.2

添加对 composer 的支持

1.0.0

初始版本

mikehaertl / packagecompressor

维护者

详细信息