Sprockets

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

Credentials

Full credit goes to

• Stuart Loxton
• Kjell Bublitz
• wiese

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

Differences

… from the implementation by wiese

• added the ability to inline images in CSS files using base64 encoded data-uri scheme

… 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);