README

l A simple class to combined and minify JS and CSS assets, and publish them to a public directory.

This can be done on the fly, or via a command that can be included in deployment build steps.

Usage

Create a collection of assets

Instantiate a collection with a path to the public asset directory and a base URL for the assets:

$collection = new \dgifford\Assets\Collection(
    '/var/www/foo.com/assets',  // Publicly accessible directory for assets
    'https://foo.com/assets'    // Base URL for assets
);

Note: ALL content in the public asset directory is deleted during the publishing process.

The public asset directory must be reserved for the assets created by this class.

Add assets using the add() method. The asset type (CSS & JS supported) is determined by the file extension:

$collection->add(
[
    'https:://url.to//A.js',
    '/path/to/A.css',
    '/path/to/B.css',
    '/path/to/B.js',
    '/path/to/C.js',
    'https:://url.to/C.css',
]);

When the extension is not .css or .js, specify the asset type:

$collection->add(
    [
        '/path/to/dynamic_css.php',
        '/path/to/dynamic_css2.php',
    ],
    'css'
);

Or, use specific the methods `addCss() and addJs()`:

$collection->addCss(
[
    '/path/to/dynamic_css.php',
    '/path/to/dynamic_css2.php',
]);

$collection->addJs(
[
    '/path/to/js_no_extension',
    'https://foo.bar/js_file',
]);

Publish assets

Publish the assets:

$collection->publish();

This deletes all existing files and directories in the public asset directory and recreates this structure:

styles.css
styles.min.css
scripts.js
scripts.min.js
css/
js/

The styles and scripts files are the combined and minified versions. The individual assets from local sources are in the css and js directories.

Linking to assets in HTML

$collection->getStyleTags() will return s string of HTML stylesheet tags:

<link href="https://foo.com/assets/A.css?273ab78d" rel="stylesheet" /><link href="https://foo.com/assets/B.css?273ab78d" rel="stylesheet" /><link href="https://foo.com/assets/C.css?273ab78d" rel="stylesheet" />

$collection->getScriptTags() works in the same way for the javascript assets. A cache-busting timestamp URL parameter is automatically added to the URLs.

These methods can be used to get the HTML to link to the combined and minified files:

$collection->getCombinedStyleTag();
$collection->getCombinedScriptTag();
$collection->getMinifiedStyleTag();
$collection->getMinifiedScriptTag();

The HTML tags can be retrieved without the cache busting string by setting the $use_cache_buster property to false on the collection:

$collection->useCacheBuster( false );

Production deployment

During development, the asset collection can be created and published on every page load, ensuring the latest version of the assets are always in use when testing.

In production (or to improve performance during development), assets can be published once in a deployment build step by using a php configuration file in the following format:

<?php
return
[
    'public_path' => __DIR__ . '/../path/to/assets',
    'base_url' => 'https://foo.com/assets',
    'css' =>
    [
        __DIR__ . '/A.css',
        'https://example.com/B.css',
        __DIR__ . '/C.css'
    ],
    'js' =>
    [
        __DIR__ . '/A.js',
        'https://example.com/B.js',
        __DIR__ . '/C.js'
    ],
    'use_cache_buster' => false,

];

The path to the configuration file can be used when creating a collection and then the same methods can be used to generate the HTML style and script tags:

$collection = new \dgifford\Assets\Collection('/path/to/asset.config.php');

echo $collection->getStyleTags();

echo $collection->getScriptTags()

During deployment, call the publish command with the path to the asset configuration file:

php .\vendor\dgifford\assets\src\publish .\assets.config.php