vesselinv/fuel-sprockets

Asset management and asset bundling package for FuelPHP

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

Requires

• php: >=5.3.6
• coffeescript/coffeescript: 1.3.*
• composer/installers: ~1.0
• leafo/lessphp: 0.4.*
• leafo/scssphp-compass: dev-master
• mrclay/minify: dev-master

MIT

README

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.

This package is best installed via Composer, and is designed for use with FuelPHP version 1.6 and upwards.

Installation

Installing Fuel Sprockets is as easy as:

1. Add

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

to the require list in your project's composer.json 2. Install with composer install

Don't forget to add it to the Auto Loaded packages block in config.php

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

Asset Structure

Fuel Sprockets will automatically generate your bundle file into your public/assets directory.

To use Fuel Sprockets, you will need the following asset structure:

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.

The package will automatically create its cache folder. You will however need to create app/assets/js/ and app/assets/css/

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

<?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

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

... or if you are using Twig for your views:

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

The above will produce:

  <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:

//= 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.

Supported Comment Types

Fuel Sprockets understands comment blocks in three formats:

/* 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.

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.

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.

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 .

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.

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.

image-url()

The image-url() function is available for the Less and Scss compilers, not for vanilla Css.

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:

// 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.

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.

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.

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:

$ oil t

And watch the cache and compile folders inside tests/ get filled with bundles.

Precompiling your Bundles

A Fuel Task is available through oil to precompile and minify your bundles.

$ 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

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:

• 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

Fuel Sprockets is distributed under an MIT-style license. See LICENSE for details.