README

The purpose of this Symfony2 bundle is to automate the process of updating assets version each time it needs to be changed − doing this manually is a real pain.

The bundle can read and write assets_version parameter in app/config/parameters.yml from Symfony console. One of the advantages of the bundle is that it does not break existing formatting in the yaml file, all user comments are also kept.

So, if you configuration looks the following way:

# app/config/config.yml
framework:
    templating:      { engines: ['twig'], assets_version: %assets_version% }
    # ...

# app/config/parameters.yml
parameters:
    assets_version: v42
    # ...

then you can simply call php app/console assets_version:increment to change version from v42 to v43. It is important to clear prod cache afterwards as this is not done automatically. More features are described below.

Detailed information on using assets versioning can be found in Symfony2 documentation: http://symfony.com/doc/current/reference/configuration/framework.html#ref-framework-assets-version

Installation

Composer

Add the following dependency to your project’s composer.json file:

    "require": {
        // ...
        "kachkaev/assets-version-bundle": "dev-master"
        // ...
    }

Now tell composer to download the bundle by running the command:

$ php composer.phar update kachkaev/assets-version-bundle

Composer will install the bundle to vendor/kachkaev directory.

Adding bundle to your application kernel

// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Kachkaev\AssetsVersionBundle\KachkaevAssetsVersionBundle(),
        // ...
    );
}

Configuration

Here is the default configuration for the bundle:

kachkaev_assets_version:
    filename: %kernel.root_dir%/config/parameters.yml           # name of the file where application parameters are stored
    parametername: assets_version                               # name of property that defines assets version in that file
    manager: Kachkaev\AssetsVersionBundle\AssetsVersionManager  # location of version manager
    scannedfiles:                                               # location list of files where required to search changes.
                  #  - %kernel.root_dir%/../web/css/css.less    # example
                  #  - %kernel.root_dir%/../web/css/second.less # example

In most cases custom configuration is not needed, so simply add the following line to your app/config/config.yml:

kachkaev_assets_version: ~

Note: It is not recommended to store real value of assets version in config.yml because its incrementing will cause git conflicts. It is better to keep it in parameters.yml added to .gitignore and also have parameters.yml.dist with blank or initial value for assets version.

Usage

The bundle adds two commands to symfony console: assets_version:increment and assets_version:set that are incrementing and setting assets version, respectively. Usage examples:

# Increments assets version by 1 (e.g. was v42, became v43)
$ php app/console assets_version:increment

# Increments assets version by 10 (e.g. was 42, became 52; was 0042, became 0052 - leading zeros are kept)
$ php app/console assets_version:increment 10

# Sets version to "1970-01-01_0000"
$ php app/console assets_version:set 1970-01-01_0000

# Sets version to "abcDEF-something_else" (no numeric part, so assets_version:increment will stop working)
$ php app/console assets_version:set abcDEF-something_else

# Decrements assets version by 10 (e.g. was lorem.ipsum.0.15, became lorem.ipsum.0.5)
# Note two dashes before the argument that prevent symfony from parsing -1 as an option
$ php app/console assets_version:increment -- -10

# Decrementing version by a number bigger than current version results 0 (e.g. was v0010, became v0000)
$ php app/console assets_version:increment -- -1000

# Increments assets version by 1 if there were found changes in the files
$ php app/console assets_version:update

Value for assets version must consist only of letters, numbers and the following characters: .-_. Incrementing only works when existing value is integer or has integer ending.

Please don’t forget to clear cache by calling php app/console cache:clear --env=prod for changes to take effect in the production environment.

If you are using assetic bundle on your production server and want to change asset version at each dump automatically, you may find useful the following shell script:

# bin/update_assets
php app/console assets_version:increment --env=prod
php app/console cache:clear --env=prod
php app/console assetic:dump --env=prod

At the moment the bundle only works with yaml files, but more file types can be added if there is a demand.

kachkaev-fork / assets-version-bundle

Maintainers

Details