Updates

2013-12-16: Fixed configuration to reflect latest bower changes (use bower.json instead of component.json)

SpBowerbundle

In this post I will talk about SpBowerBundle which I created a few month ago. Some of the benefits you get is a new command to install your defined bower dependencies and an automatic registration of all assets in the assetic manager (if needed). You can even add specific assetic filters to your bower packages.

I used the symfony-standard edition in this article.

First Step

At first we are going to install the bundle with composer

$ php composer.phar require sp/bower-bundle
Please provide a version constraint for the sp/bower-bundle requirement: dev-master
composer.json has been updated
Loading composer repositories with package information
Updating dependencies
  - Installing sp/bower-bundle (dev-master 9c6ce13)
    Cloning 9c6ce13d3b802fd58a095aff9cc93a59d873595f

Writing lock file
Generating autoload files
Clearing the cache for the dev environment with debug true
Installing assets using the hard copy option
Installing assets for Symfony\Bundle\FrameworkBundle into web/bundles/framework
Installing assets for Acme\DemoBundle into web/bundles/acmedemo
Installing assets for Symfony\Bundle\WebProfilerBundle into web/bundles/webprofiler
Installing assets for Sensio\Bundle\DistributionBundle into web/bundles/sensiodistribution

Make sure to enable the bundle in your AppKernel.php

// ...
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Sp\BowerBundle\SpBowerBundle(),
        );
    }
// ...

Configuration

Now that we installed and activated the bundle we can go on with the configuration.

# app/config/config.yml
sp_bower:
    bundles:
        AcmeDemoBundle: ~

This tells the bundle to activate bower handling with the default values for the AcmeDemoBundle. The default lookup path for the bower dependency file bower.json is $bundle/Resources/config/bower.


Adding some bower dependencies.

The AcmeDemoBundle is activated for bower handling, lets add some dependencies to it! To do this, we create a file called bower.json in the directory src/Acme/DemoBundle/Resources/config/bower/.

{
    "dependencies": {
        "bootstrap": "latest"
    }
}


Install bower dependencies

Everything is set up correctly, so we are now able to install the defined dependencies with the integrated command. By default the dependencies will be installed in the directory $bundle/Resources/public/components.

$ app/console sp:bower:install
Installing bower dependencies for "AcmeDemoBundle" into "/home/spea/workspace/test-bower-bundle/src/Acme/DemoBundle/Resources/config/bower/../../public/components"
bower cloning git://github.com/twitter/bootstrap.git
bower cached git://github.com/twitter/bootstrap.git
bower fetching bootstrap
bower checking out bootstrap#v2.2.2
bower copying /home/spea/.bower/cache/bootstrap/c1ee45ee19795a66de4a0c45758fe0b1
bower cloning git://github.com/components/jquery.git
bower cached git://github.com/components/jquery.git
bower fetching jquery
bower checking out jquery#1.8.3
bower copying /home/spea/.bower/cache/jquery/cf68c4c4e7507c8d20fee7b5f26709d9
bower installing bootstrap#2.2.2
bower installing jquery#1.8.3

Use the automatically registered assets

Till now there is nothing special, the bundle installs bower dependencies which could also be achieved with the command bower install, but a great benefit of this bundle is the automatic registration of all your dependencies in the assetic manager.

So if you now want to use the installed bootstrap assets, you can do so by simply writing the following.

{% javascripts
    "@bootstrap_js"
%}
    <script src="{{ asset_url }}"></script>
{% endjavascripts %}
{% stylesheets
    "@bootstrap_css"
%}
    <link rel="stylesheet" href="{{ asset_url }}" />
{% endstylesheets %}

Since bootstrap has a dependency on jquery it will be automatically included in the generated assets.

Some dependencies (like wysihtml5) will not be automatically registered in the assetic manager because some of them haven't defined a main section in their bower.json. But you can still add them manually.

But wait, there is more! You can also add assetic filters to all (or only some specific) packages.

Let's say that you want to add the uglifyjs fillter to all javascript packages and the cssrewrite filter only to the bootstrap package, then you would write the following:

# app/config/config.yml
sp_bower:
    bundles:
        AcmeDemoBundle: ~
    assetic:
        enabled: true
        filters:
            js:
                - uglifyjs
            packages:
                bootstrap:
                    css:
                        - cssrewrite


Advanced Configuration

Adjust asset and bower dependency directory.

Sometimes you want to use a different asset or config directory or you even want to name your bower dependency file differently.

So lets assume you want to name your dependency file bower-dependencies.json and you want to place this file in the following directory: %kernel.root_dir%/Resources/bower.

# app/config/config.yml
sp_bower:
    bundles:
        AcmeDemoBundle:
            config_dir: %kernel.root_dir%/Resources/bower
            json_file: bower-dependencies.json

After we renamed and moved the configuration file to the desired directory we can install the dependencies

$ app/console sp:bower:install
Installing bower dependencies for "AcmeDemoBundle" into "/home/spea/workspace/test-bower-bundle/app/Resources/bower/../../public/components"
bower cloning git://github.com/twitter/bootstrap.git
bower cached git://github.com/twitter/bootstrap.git
bower fetching bootstrap
bower checking out bootstrap#v2.2.2
bower copying /home/spea/.bower/cache/bootstrap/c1ee45ee19795a66de4a0c45758fe0b1
bower cloning git://github.com/components/jquery.git
bower cached git://github.com/components/jquery.git
bower fetching jquery
bower checking out jquery#1.8.3
bower copying /home/spea/.bower/cache/jquery/cf68c4c4e7507c8d20fee7b5f26709d9
bower installing bootstrap#2.2.2
bower installing jquery#1.8.3

As you can see, the assets are now installed into %kernel.root_dir%/public/components, this is due to the fact that the default asset path is always relative to the config directory, so it is necesary to adjust the asset path too.

# app/config/config.yml
sp_bower:
    bundles:
        AcmeDemoBundle:
            config_dir: %kernel.root_dir%/Resources/bower
            asset_dir: %kernel.root_dir%/Resources/public/acme_bundle_components
            json_file: bower-dependencies.json

Lets run the install command again

$ app/console sp:bower:install
Installing bower dependencies for "AcmeDemoBundle" into "/home/spea/workspace/test-bower-bundle/app/Resources/public/acme_bundle_components"
bower cloning git://github.com/twitter/bootstrap.git
bower cached git://github.com/twitter/bootstrap.git
bower fetching bootstrap
bower checking out bootstrap#v2.2.2
bower copying /home/spea/.bower/cache/bootstrap/c1ee45ee19795a66de4a0c45758fe0b1
bower cloning git://github.com/components/jquery.git
bower cached git://github.com/components/jquery.git
bower fetching jquery
bower checking out jquery#1.8.3
bower copying /home/spea/.bower/cache/jquery/cf68c4c4e7507c8d20fee7b5f26709d9
bower installing bootstrap#2.2.2
bower installing jquery#1.8.3
It is also possible to use the bundle notation (@AcmeDemoBundle/path/to/directory) for the config_dir and asset_dir options.

Install on warmup

If you want to install the bower dependencies on every cache warmup, you have to enable the option install_on_warmup.

# app/config/config.yml
sp_bower:
    install_on_warmup: true

Kepping the generated bower configuration file

The bundle automatically creates a .bowerrc file based on the configuration you made in the app/config/config.yml file when installing the dependencies. The default setting is, that this file is only created temporarily, but sometimes you might want to keep this file. By setting the option keep_bowerrc to true the generated files will be placed into the same directory where you have your bower.json.

# app/config/config.yml
sp_bower:
    keep_bowerrc: true

Disable automatic assetic registration of used bower packages

If, for whatever reason, you don't want this bundle to automatically register the packages in the assetic manager, you must set the assetic option to false.

# app/config/config.yml
sp_bower:
    assetic: false

Use the provided composer script to install dependencies on composer install/update

This bundle provides a composer script to install the dependencies when composer update/install is executed.

{
   "scripts": {
       "post-install-cmd": [
           "Sp\\BowerBundle\\Composer\\ScriptHandler::bowerInstall"
       ],
       "post-update-cmd": [
           "Sp\\BowerBundle\\Composer\\ScriptHandler::bowerInstall"
       ]
   }
}

I hope this blog post helped you to easily learn and integrate the SpBowerBundle. I'm always open for criticism (positive and negative), so don't hesitate to share your thoughts in a comment.



blog comments powered by Disqus

Published

22 January 2013

Tags

symfony2 bundle bower SpBowerBundle