Asset Helper

Asset Helper is an open source PHP library that provides convenience functions for CSS, JavaScript, and images:

• stylesheet_tag()
• javascript_tag()
• image_tag()

At their most basic, these functions create the appropriate HTML tags for the supplied arguments. The added value comes from the additional performance-enhancing features of these functions, namely timestamping and asset hosts.

Asset Helper was inspired by the Ruby on Rails AssetTagHelper module. It covers the basic functionality of the Rails helpers for now; further improvements may be made in the future. This library is freely available to use in your own web sites or applications with no restrictions whatsoever, under the terms of the MIT License.

Download Asset Helper from Github

Here’s what you get:

Asset timestamping

All helper functions will append something like ?1234567890 to asset URLs, where this string is the Unix timestamp of the file’s last modified time. This value will automatically change when the file is changed, and enables long-term caching as long as it does not change.

To best take advantage of this, configure your web server with far-future expiration times for your static files. In Apache, that means putting something like this in your .htaccess file or VirtualHost container:

ExpiresActive On
<FilesMatch "\.(ico|gif|jpe?g|png|js|css)$">
	ExpiresDefault "access plus 1 year"
</FilesMatch>

For more information on far-future expiry times, see the Yahoo Developer Network performance tips and Apache's mod_expires documentation.

Asset Hosts

Using a separate hostname for static files can improve your page loading speed by allowing browsers to download more files in parallel. You can benefit from this even if you're not using multiple web servers.

The easiest way to take advantage of this functionality is to create a DNS record for your desired static asset host, such as static.example.com and then configure your web server with this hostname pointed to the same directory as your web site.

More advanced usage would involve a front-end static file server like Nginx that proxies dynamic requests to an Apache/mod_php backend (or similar setup). Describing how to do this is beyond the scope of this documentation but the asset host functionality will work identically in this type of configuration. But note that for timestamping to work, this plugin needs filesystem access to the files in question, so the timestamping functionality only works if the files are physically on the same server.

Once the web server config is done, add the following line to your application’s configuration file or anywhere that will make it available to every page:

define('ASSET_HOST', 'static.example.com');

With this constant set, the Asset Helper functions will all return full URLs using this alternate hostname. These functions are also smart enough to figure out if SSL should be used, so don't worry about setting a protocol.

For more information on the benefits of static file servers, see the Yahoo Developer Network performance tips.

Installation

Installing Asset Helper is easy. Just place the file somewhere your application can find it, include asset-helper.php, and you’re ready to start using it.

<?php require_once '/path/to/asset-helper.php'; ?>

If you’re using it on a WordPress site, drop it into your theme directory, place this line in your theme’s functions.php file, and you’re set.

<?php require_once 'asset-helper.php'; ?>

Function Reference

In order to just work, Asset Helper makes a few assumptions about where your files live. By default, stylesheets, JavaScript, and images are all assumed to be located in /css, /js, and /images, respectively. To override this, either specify a full path to the files you're using or initialize an array called $asset_helper_subdir somewhere in your code before Asset Helper is loaded.

For example, if you prefer keep your CSS files in /stylesheets, simply place this line above the inclusion of Asset Helper:

$asset_helper_subdir['css'] = '/stylesheets';
require_once 'asset-helper.php';

For WordPress sites, it’s assumed that CSS and JavaScript files will live in your theme directory, while images are in a subdirectory called “images” inside your theme directory. Again, you can change those defaults by following the the instructions above.

stylesheet_tag()

<?php stylesheet_tag($files); ?>

This function can be used with one or more arguments. Arguments can be provided as a list of strings; each one will result in a separate <link /> tag. You can provide simply a filename, a filename without an extension, a full URL path, or a complete URL. Paths that do not begin with a slash will be created relative to the default CSS directory.

WordPress users can omit the argument entirely: if no argument is provided, it will print a <link /> tag to the standard WordPress style.css for your theme. This has no effect when used on a non-WordPress site; the function will not print anything at all.

Example usage

The first example shows the output for both a WordPress and non-WordPress site. I've omitted the WordPress examples for the rest but all methods of calling this function work identically.

<?php stylesheet_tag('extras.css'); ?>
// => <link rel='stylesheet' href='/css/extras.css' type='text/css' />
// => <link rel='stylesheet' href='/wp-content/themes/theme-name/extras.css' type='text/css' />

<?php stylesheet_tag('extras'); ?>
// => <link rel='stylesheet' href='/css/extras.css' type='text/css' />

<?php stylesheet_tag('new/styles.css'); ?>
// => <link rel='stylesheet' href='/css/new/styles.css' type='text/css' />

<?php stylesheet_tag('/stylesheets/foo.css'); ?>
// => <link rel='stylesheet' href='/stylesheets/foo.css' type='text/css' />

<?php stylesheet_tag('http://www2.example.com/css/foo.css'); ?>
// => <link rel='stylesheet' href='http://www2.example.com/css/foo.css' type='text/css' />

<?php stylesheet_tag('main.css', 'extras.css', 'ie-bugfixes.css'); ?>
// => <link rel='stylesheet' href='/css/main.css' type='text/css' />
// => <link rel='stylesheet' href='/css/extras.css' type='text/css' />
// => <link rel='stylesheet' href='/css/ie-bugfixes.css' type='text/css' />

/* WordPress users only */
<?php stylesheet_tag(); ?>
// => <link rel='stylesheet' href='/wp-content/themes/theme-name/style.css' type='text/css' />

javascript_tag()

<?php javascript_tag($files); ?>

This function can be used with one or more arguments.

Arguments can be provided as a list of strings; each one will result in a separate <script></script> block. You can provide simply a filename, a filename without an extension, a full URL path, or a complete URL. Paths that do not begin with a slash will be created relative to the default JavaScript location.

Example usage

As above, I'm showing one example from WordPress but, again, all methods of using this function will work correctly.

<?php javascript_tag('javascript.js'); ?>
// => <script src='/js/javascript.js' type='text/javascript'></script>
// => <script src='/wp-content/themes/theme-name/javascript.js' type='text/javascript'></script>

<?php javascript_tag('javascript'); ?>
// => <script src='/js/javascript.js' type='text/javascript'></script>

<?php javascript_tag('third-party/jquery.js'); ?>
// => <script src='/js/third-party/jquery.js' type='text/javascript'></script>

<?php javascript_tag('jquery.js', 'application.js'); ?>
// => <script src='/js/jquery.js' type='text/javascript'></script>
// => <script src='/js/application.js' type='text/javascript'></script>

image_tag()

<?php image_tag($file, $options); ?>

This function works a bit differently than the others. It only allows for one image per function call, but lets you set any HTML attributes you need for the image.

The first argument is the image itself, either a filename, URL path, or complete URL. Paths that do not begin with a slash will be created relative to the default image directory.

The second argument is an associative array of options corresponding to HTML attributes/values. One special option is 'size', which can accept image dimensions as a single string, saving you the trouble of adding both width and height attributes (which you're welcome to do if you prefer). All options are optional (ha!). If an alt attribute is not supplied, an empty one will be created to ensure HTML validity.

The 'size' attribute should be in the format WIDTHxHEIGHT. For example, use '300x100' to specify a width of 300 and a height of 100.

Example usage

Once again, one WordPress example provided but all the rest work as well.

<?php image_tag('logo.png'); ?>
// => <img src='/images/logo.png' alt='' />
// => <img src='/wp-content/themes/theme-name/images/logo.png' alt='' />

<?php image_tag('subdir/logo.png', array('size' => '300x100', 'alt' => 'Alternate text')); ?>
// => <img src='/images/subdir/logo.png' width='300' height='100' alt='Alternate text' />

<?php image_tag('logos/logo.png', array('alt' => 'Alternate text')); ?>
// => <img src='/images/logos/logo.png' alt='Alternate text' />

<?php image_tag('/photos/photo.jpg', array('class' => 'css_class', 'id' => 'some_id')); ?>
// => <img src='/photos/photo.jpg' alt='' class='css_class' id='some_id' />

<?php image_tag('/images/logo.png', array('onmouseover' => 'do_something();')); ?>
// => <img src='/images/logo.png' alt='logo.png' onmouseover='do_something();' />

Download

Download Asset Helper from Github

License

Asset Helper is released under the terms of the MIT License and is free to use and redistribute for any purpose. If you find this code helpful, a link back to my site would be cool, but it’s not required.