Sprockets

A PHP5 port of Sprockets – the ruby library for JavaScript dependency management and concatenation.

Credentials

Full credit goes to

• Stuart Loxton
• Kjell Bublitz

who created and improved php-sprockets in the first place.

Thanks to Sam Stephenson for the initial concept of JavaScript dependency management,

Differences

… from the implementation by Kjell

• added first steps in unit tests (PHPunit) — using original ruby sprockets test cases
• added a command requireonce — allows real-world dependency management (just like ruby sprockets), e.g. for object-oriented JS with each class organized in a separate files. You would not want to see repeated inclusion in this case (but you still can using require).
• added option customCommandsPath — allows using custom commands without messing with the library
• changed application logic to create every command only once — saves memory and allows features like requireonce

Demo

Consider the following demo code to be acceptable in your development system, or for playing around — this is the basis of what it takes to get Sprockets up and running. The scenarios is, that you — just like we here — have a library folder where you drop Sprockets in (say lib/Sprockets), and a document root of your application (say htdocs, just like our demo here). The .htaccess file in the document root causes requests for any .js files to be handled by sprocketize.php.

If you are having problems with the .htaccess file, please see the Apache mod_rewrite documentation.

Please see Use cases for more sophisticated methods of using Sprockets in a productive environment.

.htaccess

RewriteEngine On
RewriteRule \.js$ sprocketize.php [QSA]

sprocketize.php

require_once('../lib/Sprockets.php');	// requiring library
$filePath = preg_replace('/\?.*/', '', $_SERVER['REQUEST_URI']);
$sprockets = new Sprockets(
	$filePath,
	array(
		'baseUri' => '/php-sprockets',
		'autoRender' => true
	)
);

{__DOCUMENT ROOT__}/javascript/lorem.js should show the contents of both lorem.js as well as ipsum.js.

Use cases

This is a rough sketch on how you could use Sprockets integrated into your deployment process — do not copy-paste this code and expect it to work — it cannot, simply because not all scripts and tools mentioned are contained within Sprockets. Consider it pseudo-code.

deployment.sh

#!bin/bash
DIRECTORY=`mktemp -d` || exit 1
svn checkout -q http://myrepo $DIRECTORY
# create js package for live system
php $DIRECTORY/bin/jsPacking.php
# do some more magic
php $DIRECTORY/bin/rmUnitTests.php
# ...
# copy project to live server
rsync $DIRECTORY [email protected]:/coolproject

jsPacking.php

// a definition file listing all JS files needed
$sourceFile = JS_PATH . SPROCKETS_SOURCE;
// the JS file the live app points to
$targetFile = JS_PATH . SPROCKETS_TARGET;
$sprocket = new Sprockets(
	$sourceFile,
	array(
		'debugMode' => true,	// avoid creating cache file
		'autoRender' => false,	// do not echo the result
	)
);
$content = $sprocket->render(true);
$output = JSMin::minify($content);
// write file with all commands executed (requires, ...), and minified
file_put_contents($targetFile, $output);

Todo

Honestly I don’t like the idea of the integrated JSMin™ and CSSMin™ too much – these are separate libraries and should be treated as such. Eventually they are going to be removed.
As, in a real world scenario (production mode), running Sprockets at runtime is not a good idea anyway, these tools are better integrated into the deployment process by a simple bash script handling the process of a) running Sprockets b) applying JSMin™ c) more magic…

• remove integration of JSMin™ and CSSMin™
• implement missing unittests