Fuel Sprockets: Asset Bundling for FuelPHP
Fuel Sprockets is an asset management and asset bundling package
for FuelPHP. Following the idea behind the Asset Pipeline and the ease
of use of the build-in Asset class, you can now manage your javascript
and css files in your application with ease. Fuel Sprockets also comes
with php ports of Sass/Compass, Less and CoffeeScript compilers., (*1)
This package is best installed via Composer, and is designed for use with FuelPHP
version 1.6 and upwards., (*2)
Installation
Installing Fuel Sprockets is as easy as:, (*3)
- Add
"vesselinv/fuel-sprockets": "1.*"
to the require list in your project's composer.json
2. Install with composer install, (*4)
Don't forget to add it to the Auto Loaded packages block in config.php, (*5)
'packages' => array(
'sprockets',
),
Asset Structure
Fuel Sprockets will automatically generate your bundle file into your public/assets directory., (*6)
To use Fuel Sprockets, you will need the following asset structure:, (*7)
fuel/
|-- app/
| |-- assets/
| | |-- js/
| | |-- css/
| | |-- img/
| |-- cache/
| | |-- sprockets/
| | | |-- js/
| | | |-- css/
public/
|-- assets/
| |-- js/
| |-- css/
| |-- img/
You should be placing your asset files inside app/assets/* and that's where Fuel Sprockets will
expect to find them. This ensures separation of development files from production bundles. It
also makes them publicly unaccessible., (*8)
The package will automatically create its cache folder. You will however need to create
app/assets/js/ and app/assets/css/, (*9)
Convention over Configuration
Fuel Sprockets, by default, is configured to use the afore-mentioned asset
structure and make our lives a little bit easier. You can however, overwrite it
by copying config/sprockets.php into your fuel/app/config directory, (*10)
<?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',
),
);
How to Use
Inside your views, simply invoke your bundle file just as you would with Asset, (*11)
<?php echo Sprockets::js('application.js'); ?>
<?php echo Sprockets::css('application.scss'); ?>
... or if you are using Twig for your views:, (*12)
{{ sprockets_js('application.js') }}
{{ sprockets_css('application.scss') }}
The above will produce:, (*13)
<script src="http://localhost:8000/assets/js/application_0004abf4a2950d49d237ecd9112fc233.js" type="text/javascript"></script>
<link rel="stylesheet" href="http://localhost:8000/assets/css/application_73afabf115045b19bfa32fa25de2861e.css">
The Directive Parser
Fuel Sprockets runs the directive parser on each CSS and JavaScript
source file. The directive parser scans for comment lines beginning with
= in comment blocks anywhere in the file. A sample application.js:, (*14)
//= 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);
Directives expect relative file paths, which must include the file extension.
File paths can also be wrapped in single ' or double " quotes., (*15)
Fuel Sprockets understands comment blocks in three formats:, (*16)
/* 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 Directives
You can use the following directives to declare dependencies in asset
source files., (*17)
The require Directive
require path inserts the contents of the asset source file
specified by path. If anywhere in the scanned files path is duplicated,
it will only be inserted once at the first require spot. Also supports remote
files from CDNs., (*18)
The require_directory Directive
require_directory path requires all source files of the same
format - Js/Coffee or Css/Scss/Less - in the directory specified by path.
Files are required in alphabetical order. Partials (filenames starting with an underscore _) and dotfiles . are ignored., (*19)
The require_tree Directive
require_tree path works like require_directory, but operates
recursively to require all files in all subdirectories of the
directory specified by path. When using this directive, subfolders are included prior to any files that are direct children of path ., (*20)
Supported Compilers
Fuel Sprockets comes with php ports of Sass/Compass (only the Scss syntax),
Less and CoffeeScript compilers that will automatically compile your assets,
without having to have these gems installed - in fact, no Ruby installation is
needed either - all is handled through php., (*21)
Note: The package will expect to find CoffeeScripts inside your JS Asset Root
(fuel/app/assets/js/ by default) along with vanilla Js file, and Scss and Less stylesheeets
inside your CSS Root Dir (fuel/app/assets/css/ by default) along with vanilla Css. Some may
say why mix up Js with Coffee and Css with Sass and Less and the answer simply is because
in the end they all get compiled to plain Js and Css respectively. At a future point, if requested,
I may add support for separating them into different folders., (*22)
image-url()
The image-url() function is available for the Less and Scss compilers, not for vanilla Css., (*23)
To make proper use of it, the referenced image must reside in fuel/app/assets/img/ or a path that is equivalent to your customly defined asset_root_dir + img_dir. What the function will do is copy the image from fuel/app/assets/img/ into public/assets/img/. Use as such:, (*24)
// Only inside Less and Scss files:
body {
background: image-url("my-fabulous-background.jpg");
}
// Will produce:
body {
background: url("http://localhost:8000/assets/img/my-fabulous-background.jpg");
}
Note: The argument passed to image-url() must always be wrapped in single or double quotes., (*25)
Minification
All Sprockets files will be automatically minified if your Fuel::$env is set to
production. You can, however, force minification in different environments by
setting force_minify to true in the Sprockets config file., (*26)
Smart Caching
Fuel Sprockets is smart about caching. The final compiled source for each file that is
included in your bundles in cached inside fuel/app/cache/sprockets. An md5 string of the
file contents and minification flag (.min) are appended to the filename so that we can
compare when your asset file has changed and whether the generated file is up-to-date., (*27)
Running Tests
I've prepared a Test Case with a set of files that will test all of the supported directives,
compilers and minifier. To run the tests, simply use oil:, (*28)
$ oil t
And watch the cache and compile folders inside tests/ get filled with bundles., (*29)
Precompiling your Bundles
A Fuel Task is available through oil to precompile and minify your bundles., (*30)
$ oil r sprockets:compile application.js application.css
These tasks come in very handy when deploying with Capistrano. Simply define a
task in your deploy.rb, (*31)
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"
Roadmap
The following improvements are on my list:, (*32)
- ~~Support for image processing when referenced in Scss, Less and Css assets.~~
- Support for fonts referenced in css assets - copy font files from
asset_root_dir to compile_dir
- ~~Additional Config options for the CoffeeScript, Scss/Compass and Less compilers~~
- ~~Make package installable through Composer~~
License
Copyright © 2013 Veselin Vasilev @vesselinv, (*33)
Fuel Sprockets is distributed under an MIT-style license. See LICENSE for
details., (*34)
Wallogit.com
