dotco / rebuilder
PHP Asset management.
Requires
- php: >=5.3.2
This package is not auto-updated.
Last update: 2024-10-26 14:34:09 UTC
README
Rebuilder digresses from the usual asset management and pipelining patterns you may be familiar with. The intention of Rebuilder is to not be run in your application pipeline, but rather run via a cronjob, hook, or other means in which you trigger it yourself.
The core concept of Rebuilder is the ability to queue up modules to be run. There is no restriction on what actions these modules may perform or what files they may modify. The only thing Rebuilder cares about is that your modules follow a specific naming convention and directory structure for autoloading purposes.
Pre-requisites
Certain Rebuilder modules may have pre-requisites.
- PHP 5.3+
- Composer (it utilizes the autoloader internally)
- Write access to your public media directory
Existing Modules
The following modules currently exist and are shipped with Rebuilder:
- JSMin - A modified PHP port of php-jsmin that works with Rebuilder
- CSSTidy - A modified version of php-css-tidy that works with Rebuilder
- Gzip - A custom module to generate gzipped files with the extension .gz.ext
- S3 - A modified version of amazon-s3-php-class that works with Rebuilder and Gzip module
- Bundler - A wrapper around JSMin and CSSTidy for creating asset "bundles". Includes a command line binary for "bundling" assets as well as a client side script for including bundles on your frontend.
Below is a rundown of the modules and their configuration parameters.
JSMin
JSMin is a module for combining (merging) a set of JS files into a singular file.
It has handling build in for attempted retrieval of remote HTTP files (i.e. Google
hosted jQuery). JSMin also handles minification of Javascript files.
It also has handling built in which will skip minification of files
that have min.
in their filename. This is necessary to avoid double minification.
JSMin has the following configuration settings:
- basepath - The full base path to the public directory of the files on the server. Gets concatted with relative filepaths below.
- files - An array of the relative paths to the files to be merged. Must be in order.
- output_file - The relative path to the output file where the CSS files get merged.
CSSTidy
CSSTidy is a module for combining (merging) a set of CSS files into a singular file. CSSTidy also handles compression of the CSS into one line or one rule per line.
CSSTidy has the following configuration settings:
- basepath - The full base path to the public directory of the files on the server. Gets concatted with relative filepaths below.
- multi_line - Whether to combine the files on a single line (max compression), or one rule per line.
- files - An array of the relative paths to the files to be merged. Must be in order.
- output_file - The relative path to the output file where the CSS files get merged.
Gzip
Gzip is a module for gzipping media assets as a new file. It's tightly coupled with the S3 module in that the S3 module automatically handles setting the proper headers on gzipped files with the extension .gz.ext. This ensures that you properly serve gzipped files from S3.
Amazon S3
S3 is a module for adding media assets to your Amazon S3 account. It has configurable options for buckets, filename prefixing (making them look like a directory structure), gzipping, and more.
Bundler
Bundler is just plain awesome. It combines all of the above modules into a package deal. You can create asset/media "bundles" and serve them via the included client side script, where it takes care of the gruntwork for determining if you want to serve up individual files, combined files, compressed files, gzipped files, files from S3, or any number of combinations... It's quite powerful.
- bundles - A multi-dimensional array in the format
'bundlename' => array('js' => array('requires' => array(), 'files' => array()), 'css' => array('requires' => array(), 'files' => array()))
- csstidy - An array of CSSTidy configuration options
- gzip - An array of Gzip configuration options
- jsmin - An array of JSMin configuration options
- s3 - An array of S3 configuration options
For all intent purposes, you can initialize bundler pulling configuration options from each of the modules to prevent duplicating config options.
Module Conventions
The conventions you must follow when creating or porting modules for usage with Rebuilder are as follows:
- Modules must be placed within their own namespaced directory in
/modules/
, i.e./modules/CSSTidy/
and/modules/JSMin/
- Modules must include a
config.php
file in their base directory containing deafult configuration settings. Check below in the Usage section for conventions. - Modules may contain sub-directories and classes.
- If you have a class contained within a sub-directory, the class name must
include the sub-directory path included where you replace any
directory separator,
/
, with an underscore_
. - The class naming and directory structure mirrors that of PSR-0 with the exception
of being able to have the following:
/modules/JSMin/JSMin.php
- Modules must have a default constructor,
__construct()
, which takes in a$config
array parameter - Modules must have a
public function run()
method which is called by Rebuilder
Usage
Rebuilder is intended to be very easy to use. At a very high level, you only need to run a few commands, passing in a multi-dimensional array of the modules you wish to run and their configuration options.
Rebuilder requires a $modules
array to be passed in for queueing of modules.
For each module, Rebuilder has a base set of three configuration settings that
need to be passed in for it to determine how to load the module, if the module
should in fact run, and what configuration values to pass to the module:
- class - The name of the module's primary class [CSSTidy]
- enabled - Whether the module is enabled [boolean true|false]
- config - A configuration array specific to the module in question
Below are a few quick examples of using Rebuilder with CSSTidy and JSMin. Specific configuration options for CSSTidy and JSMin will be covered later.
Run CSSTidy
<?php // compress CSS $files into $output_file $modules = array( 'csstidy' => array( 'class' => 'CSSTidy', 'enabled' => TRUE, 'config' => array( 'basepath' => '/path/to/public/directory/', 'multi_line' => TRUE, 'files' => array( 'css/reset.css', 'css/global.css' ), 'output_file' => 'css/combined.css' ) ) ); require('Rebuilder/Core.php'); $rebuilder = new Rebuilder_Core($modules); $rebuilder->run(); <?php
Run JSMin
<?php $modules = array( 'jsmin' => array( 'class' => 'JSMin', 'enabled' => TRUE, 'config' => array( 'basepath' => '/path/to/public/directory/', 'files' => array( 'js/jquery.min.js', 'js/global.js' ) 'output_file' => 'js/combined.js' ) ) ); require('Rebuilder/Core.php'); $rebuilder = new Rebuilder_Core($modules); $rebuilder->run();
Run CSSTidy and JSMin
<?php $modules = array( 'csstidy' => array( 'class' => 'CSSTidy', 'enabled' => TRUE, 'config' => array( 'basepath' => '/path/to/public/directory/', 'multi_line' => TRUE, 'files' => array( 'css/reset.css', 'css/global.css' ), 'output_file' => 'css/combined.css' ) ), 'jsmin' => array( 'class' => 'JSMin', 'enabled' => TRUE, 'config' => array( 'basepath' => '/path/to/public/directory/', 'files' => array( 'js/jquery.min.js', 'js/global.js' ) 'output_file' => 'js/combined.js' ) ) ); require('Rebuilder/Core.php'); $rebuilder = new Rebuilder_Core($modules); $rebuilder->run();
Run Gzip
TODO
Run Amazon S3
<?php $modules = array( 's3' => array( 'class' => 'S3', 'enabled' => TRUE, 'config' => array( 'accessKey' => 'your-access-key', 'privateKey' => 'your-private-key', 'useSSL' => true, 'bucket' => 'bucket-name' ) ) ); require('Rebuilder/Core.php'); $rebuilder = new Rebuilder_Core($modules); $rebuilder->run();
Run Bundler
Bundler should really have it's own README...
Using Rebuilder from the Command Line
Running the Bundler command line script
# specifying a configuration file (wont work without action param) ./vendor/bin/rebuilder --config="/path/to/config.php" --env="local" # run a particular action ./vendor/bin/rebuilder --modules="csstidy,jsmin" --config="/path/to/config.php" --env="local" # run with a type specifier (only upload images to S3) ./vendor/bin/rebuilder --modules="s3" --type="img" --config="/path/to/config.php" --env="local" # run bundler ./vendor/bin/rebuilder --modules="bundler" --config="/path/to/config.php" --env="local"