PHPackages                             dc/bundler - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. dc/bundler

ActiveLibrary[Utility & Helpers](/categories/utility)

dc/bundler
==========

Asset bundling for dc/router

082[1 PRs](https://github.com/digitalcreations/bundler/pulls)PHPCI passing

Since Dec 12Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/digitalcreations/bundler)[ Packagist](https://packagist.org/packages/dc/bundler)[ RSS](/packages/dc-bundler/feed)WikiDiscussions master Synced 1w ago

READMEChangelogDependenciesVersions (3)Used By (0)

Asset bundler
=============

[](#asset-bundler)

This library enables you to bundle your assets into one for quicker loading.

Installation
------------

[](#installation)

```
composer require dc/bundler

```

or in `composer.json`

```
"require": {
    "dc/bundler": "master"
}
```

Setup
-----

[](#setup)

This package depends on `dc/router` but also strongly suggests `dc/ioc`. The samples below assume both are installed.

```
\DC\Bundler\Bundler::registerWithContainer(
    $container,
    new \DC\Bundler\BundlerConfiguration(
        $config, // see the configuration section
        \DC\Bundler\Mode::Production,
        "bar")
    );
```

Compiled asset store
--------------------

[](#compiled-asset-store)

This is an interface you can implement yourself to choose where the compiled files are stored. It is a very simple interface.

The built in implementation (`FileBasedCompiledAssetStore`) by default stores the files in the `/tmp/dc_bundler` on Linux, and `C:\Windows\temp\dc_bundler` on Windows. When registering it, pass the folder you want to use to its constructor.

Configuration
-------------

[](#configuration)

Bundler accepts either a PHP multi-dimensional array or a path to a JSON file on disk for its configuration. For speed purposes, a PHP array is recommended and used throughout this documentation.

The configuration should have the following structure:

```
[
    "__webroot" => "/var/www",
    "bundlename" => [
        "transform" => [
            // array of transforms to apply to these files in order
        ],
        "parts" => [
            // array of file names or other bundles to process
        ],
        "watch" => [
            // array of file names to watch for recompile
        ]
    ]
]
```

The **web root** is important because all paths in the configuration are relative to that root. This needs to be the local path to your web root folder, so Bundler can find the files and serve up non-bundled versions.

Besides the web root, the configuration consists of a range of names pointing to individual bundles. For a bundle to be a bundle, you need at least the `parts` key. This specifies which files to include in the bundle, but you can also write a new bundle here (see Nested bundles below).

When including files you specify a `glob` expression relative to the web root. Here are some samples:

- `app/app.js` — just the `app.js` file in the `app` directory.
- `app/directives/*.js` — all `.js` files in `app/directives`. You knew that already.
- `app/templates/**/*.html` — all `.html` files in any subfolder of `app/templates`.

The **watch** specifies additional files to be watched for changes to determine if the bundle needs to be recompiled. This is useful for e.g. Less files, where `@import` statements are not visible to Bundler. Then it would help if you added a `watch` glob that matches all files in a specific subfolder. If any of those files change, the bundle is recompiled.

The **transforms** specify which transformations should be done on the items in this bundle. Each transform has a name, and all of these come as their own Composer package):

- `less` for transforming Less to CSS (see `dc/bundler-less`)
- `ngtpl` for caching Angular templates as Javascript (see `dc/bundler-ngtpl`)
- `jsmin` for minifying Javascript (see `dc/bundler-jsmin`)

If you do not specify a transform, the default transform will be `["bundle"]`, which means it will simply concatenate all of the parts together in order.

The special "bundle" transform is the only transform that acts on multiple items at once. This makes it possible to decide when bundling happens — if you specify `["bundle", "jsmin"]` (which is the same as `["jsmin"]`), bundling happens before minification. Conversely, if you sepcify `["jsmin", "bundle"]`, bundling happens after minification has been applied separately to each file.

### Nested bundles

[](#nested-bundles)

Nested bundles are useful in some cases. A common case would be wanting to include the following items in your bundle:

- Third party libraries (already minified)
- Your site's Javascript code (written in Angular)
- Angular templates for your Javascript

Here is a configuration that could work well for you:

```
[
    "__webroot" => "/var/www",
    "site.js" => [
        "parts" => [
            // do nothing with dependencies
            "app/dependencies/*.js",
            [
                // minify everything you've written yourself
                "transform" => ["jsmin"],
                "parts" => [
                    "app/app.js",
                    "app/controllers/*.js",
                    "app/directives/*.js",
                    [
                        // convert Angular templates to JS
                        "transform => ["ngtpl"]
                        "parts" => ["app/templates/**/*.html"]
                    ]
                ]
            ]
        ]
    ]
]
```

Automatic routing
-----------------

[](#automatic-routing)

If you ensure that `dc/router` knows about `'\DC\Bundler\BundleController`, your bundles will be available for use in your app directly. The URL is `/bundle/{cacheBreaker}/{bundlename}`, so for the example above: `/bundle/foo/site.js`.

The `{cacheBreaker}` allows (forces?) you to easily skip each user's cache whenever you make changes. It is the recommended approach to use to ensure all of your user's get the latest assets.

Including bundles in your HTML
------------------------------

[](#including-bundles-in-your-html)

`Bundler::getTagsForBundle` helps you by outputting all the HTML tags required for a given bundle. It automatically keeps tracks of debug/production mode, and outputs the correct tags. It even handles the case were you have a Less file that needs compilation even in debug mode.

If you are using a templating system such as Smarty, you may find the following snippet helpful:

```