容器/fuel-sprockets

为FuelPHP提供的资产管理及资源捆绑包

维护者

详细信息

github.com/vesselinv/fuel-sprockets

源代码

问题

安装次数: 6 193

依赖者: 0

建议者: 0

安全性: 0

星标: 16

关注者: 4

分支: 7

开放问题: 1

类型:fuel-package

v1.4.0 2015-10-29 04:46 UTC

Requires

MIT ea46b10d8271215e8650f302c33244fe5294b7ec

This package is not auto-updated.

Last update: 2024-09-28 14:58:08 UTC

README

Fuel Sprockets是为FuelPHP设计的资产管理与资源捆绑包。遵循Asset Pipeline的思路以及内置Asset类的易用性，您现在可以轻松地管理应用中的JavaScript和CSS文件。Fuel Sprockets还包含了Sass/Compass、Less和CoffeeScript编译器的PHP端口。

此包最好通过Composer安装，并设计用于FuelPHP 1.6及以上版本。

安装

安装Fuel Sprockets就像

  1. 添加
"vesselinv/fuel-sprockets": "1.*"

到项目的composer.json文件中的require列表中。2. 使用composer install安装

别忘了将其添加到config.php文件中的自动加载包块中

'packages'  => array(
  'sprockets',
),

资源结构

Fuel Sprockets会自动将捆绑文件生成到您的public/assets目录中。

要使用Fuel Sprockets，您需要以下资源结构

fuel/
|-- app/
|    |-- assets/
|    |    |-- js/
|    |    |-- css/
|    |    |-- img/
|    |-- cache/
|    |    |-- sprockets/
|    |    |    |-- js/
|    |    |    |-- css/
public/
|-- assets/
|    |-- js/
|    |-- css/
|    |-- img/

您应该在app/assets/*内放置您的资源文件，这也是Fuel Sprockets期望找到它们的地方。这确保了开发文件与生产捆绑文件的分离。同时也使它们对公众不可访问。

此包会自动创建其缓存文件夹。但您需要创建app/assets/js/和app/assets/css/

约定优于配置

默认情况下，Fuel Sprockets配置为使用上述资源结构，使我们的工作更加便捷。但您可以通过将config/sprockets.php复制到您的fuel/app/config目录来覆盖它

<?php
return array(
  'asset_root_dir'    => APPPATH . 'assets/',
  'asset_compile_dir' => DOCROOT . 'assets/',
  'cache_dir'         => APPPATH . 'cache/sprockets/',
  'js_dir'            => 'js/',
  'css_dir'           => 'css/',
  'img_dir'           => 'img/',
  'base_url'          => \Uri::base(false),
  'force_minify'      => false,
  'coffeescript' => array(
    'bare'   => true,
    'header' => '\/\/ Generated by CoffeeScript 1.3.1\n',
  ),
);

如何使用

在您的视图中，只需像使用Asset一样调用您的捆绑文件即可

  <?php echo Sprockets::js('application.js'); ?>
  <?php echo Sprockets::css('application.scss'); ?>

...或者如果您使用Twig作为视图

  {{ sprockets_js('application.js') }}
  {{ sprockets_css('application.scss') }}

上面的代码将生成

  <script src="https://:8000/assets/js/application_0004abf4a2950d49d237ecd9112fc233.js" type="text/javascript"></script>
  <link rel="stylesheet" href="https://:8000/assets/css/application_73afabf115045b19bfa32fa25de2861e.css">

指令解析器

Fuel Sprockets对每个CSS和JavaScript源文件运行指令解析器。指令解析器会扫描文件中任何注释块中以=开头的注释行。以下是一个示例application.js

//= require jquery-1.9.1.js
//= require vendor/backbone.js
//= require_tree .
//= require_directory vendor/
(function($){
  $(document).ready(function(){
    alert('It effin works, dude!');
    });
  })(jQuery);

指令期望相对文件路径，必须包含文件扩展名。文件路径也可以用单引号'或双引号"包裹。

支持的注释类型

Fuel Sprockets理解以下三种格式的注释块

/* Multi-line comment blocks (CSS, SCSS, Less, JavaScript)
 *= require 'foo.js'
 */

// Single-line comment blocks (SCSS, Less, JavaScript)
//= require "foo.scss"

# Single-line comment blocks (CoffeeScript)
#= require foo.coffee

Fuel Sprockets指令

您可以使用以下指令在资产源文件中声明依赖项。

require指令

require path 插入由 path 指定的资产源文件的内容。如果在扫描的文件中 path 被重复，它将只在前一个require位置插入一次。也支持CDN上的远程文件。

require_directory指令

require_directory path 需求指定path目录中相同格式（Js/Coffee或Css/Scss/Less）的所有源文件。文件以字母顺序需求。忽略以下划线_开头的部分和点文件.。

require_tree指令

require_tree path 与require_directory类似，但它递归地要求指定path目录及其所有子目录中的所有文件。使用此指令时，子文件夹在path的直接子文件之前被包括。

支持的编译器

燃油链轮包含Sass/Compass（仅限Scss语法）、Less和CoffeeScript编译器的php端口，可以自动编译您的资产，无需安装这些gem - 实际上，甚至不需要Ruby安装 - 所有这些都通过php处理。

注意：该包期望在您的JS资产根目录（默认为fuel/app/assets/js/）中找到CoffeeScript，与vanilla Js文件一起，在CSS根目录（默认为fuel/app/assets/css/）中找到Scss和Less样式表，与vanilla Css一起。有些人可能会问为什么把Js和CoffeeScript混在一起，把Css和Sass和Less混在一起，答案很简单，因为最终它们都将编译为相应的plain Js和Css。在未来的某个时候，如果需要，我可能会添加将它们分开到不同文件夹的支持。

image-url()

image-url()函数对Less和Scss编译器可用，但对vanilla Css不可用。

为了正确使用它，所引用的图像必须位于fuel/app/assets/img/或等效于您自定义的asset_root_dir + img_dir的路径。该函数将执行的操作是从fuel/app/assets/img/将图像复制到public/assets/img/。使用如下

// Only inside Less and Scss files:

body {
  background: image-url("my-fabulous-background.jpg");
}

// Will produce:

body {
  background: url("https://:8000/assets/img/my-fabulous-background.jpg");
}

注意：传递给image-url()的参数必须始终用单引号或双引号括起来。

压缩

如果您的Fuel::$env设置为production，所有Sprockets文件都将自动压缩。但是，您可以通过在Sprockets配置文件中将force_minify设置为true来强制在不同的环境中进行压缩。

智能缓存

燃油Sprockets在缓存方面非常智能。每个包含在您的包中的文件的最终编译源都缓存于fuel/app/cache/sprockets中。文件内容的md5字符串和压缩标志（.min）附加到文件名上，以便我们可以比较您的资产文件是否已更改，以及生成的文件是否是最新的。

运行测试

我准备了一个测试用例，包含一组测试所有支持的指令、编译器和压缩器的文件。要运行测试，只需使用oil

$ oil t

并观察tests/中的缓存和编译文件夹被包填满。

预编译您的包

通过oil，有一个Fuel任务可以预编译和压缩您的包。

$ oil r sprockets:compile application.js application.css

当使用Capistrano部署时，这些任务非常有用。只需在您的deploy.rb中定义一个任务

namespace :deploy do
    desc "Precompile Assets"
    task :sprockets do
        run [ "cd #{latest_release}",
            "php oil refine sprockets:compile application.js application.css"
          ].join("; ")
    end
end

after "deploy:migrate", "deploy:sprockets"

路线图

以下是我要做的改进

  • 在Scss、Less和Css资产中引用图像时的图像处理支持。
  • 在css资产中引用字体时的支持 - 将字体文件从asset_root_dir复制到compile_dir
  • CoffeeScript、Scss/Compass和Less编译器的附加配置选项
  • 通过Composer安装包

许可证

版权所有 © 2013 Veselin Vasilev @vesselinv

燃油Sprockets在MIT风格许可证下分发。有关详细信息，请参阅LICENSE。