You are browsing the documentation for BootstrapBundle v2.0, if you haven't upgraded yet you can still browse the documentation for BraincraftedBootstrapBundle v1.4.

Getting Started

This section helps you through the installation and configuration process of BraincraftedBootstrapBundle and provides guides about how to customize Bootstrap and extend the bundle.

BraincraftedBootstrapBundle has a few required dependencies:

  • PHP 5.3.3 and up
  • Symfony 2.3 and up
  • Twig 1.11 and up
  • AsseticBundle 2.3 and up (optional, but highly recommended)

If you don't use AsseticBundle for managing your assets, you need to manually manage them or use some other tool like Bower. While you can certainly do this, we can't help you setting up the bundle up in this case.

The bundle also comes with support for various third party bundles:

Since this bundle has two main and many additional dependencies, here is a table of compatibilities:

BootstrapBundle Symfony Bootstrap jQuery KnpMenu KnpPaginator lessphp
less.php
scssphp
v1.3.* v2.2.* v2.3.* v1.9.* v1.* v2.* - -
v1.4.* v2.2.* v2.3.* v1.9.* v1.* v2.* v0.3.*
-
-
v2.0.* v2.3.*
v2.4.*
v3.0.*
v3.1.*
v1.10.*
v1.11.*
v1.1.*
v2.0.0-alpha12
dev-master1 -
v1.5.*3
-
v2.1.* v2.3.*
v2.4.*
v2.5.*
v3.0.*
v3.1.*
v3.2.*
v3.2.*-sass
v1.10.*
v1.11.*
v1.1.*
v2.0.0-alpha12
dev-master1 -
v1.5.*3
v1.1.*

1 knplabs/knp-components currently has no release that is compatible with Symfony 2.3.
2 The bundle works fine with 1.* releases of KnpMenu, however, automatically matching the active element only works with 2.* or dev-master.
3 leafo/lessphp does no longer compile recent versions of Bootstrap 3. Instead you can use oyejorge/less.php.

BraincraftedBootstrapBundle should be installed using Composer:

{
    "require": {
        "braincrafted/bootstrap-bundle": "~2.0"
    }
}

By default, BraincraftedBootstrapBundle does not include Bootstrap and jQuery. Some people want to use Composer for these dependencies, other people prefer tools designed for managing assets like Bower. If you want to use such a tool, we assume you know how to use it. If you have no experience with these tools, you probably want to stick with Composer. You can use the following code in your composer.json to include Bootstrap and jQuery in your Symfony2 project:

{
    "repositories": [
        {
            "type": "package",
            "package": {
                "name": "jquery/jquery",
                "version": "1.11.1",
                "dist": {
                    "url": "https://code.jquery.com/jquery-1.11.1.js",
                    "type": "file"
                }
            }
        }
    ],
    "require": {
        ... other dependencies
        "twbs/bootstrap": "3.0.*",
        "jquery/jquery":  "1.11.*"
    }
}
    

Of course you also need to add the bundle to your AppKernel.php:

# app/AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Braincrafted\Bundle\BootstrapBundle\BraincraftedBootstrapBundle(),
        );
        // ...
    }
}

BraincraftedBootstrapBundle highly recommends you to use Assetic for managing assets. If you do use Assetic for managing your assets, you should now run the dump command.

php app/console assetic:dump

In Symfony 3.0 the console command is located in the bin directory.

php bin/console assetic:dump

Please note Assetic needs to compile the LESS files from Bootstrap and therefore requires either LESS or lessphp. The following section explains how to install and configure them.

Installing a LESS compiler

As mentioned above, it is sufficient to install either LESS or lessphp.

Don't forget You have to install the library, configure Assetic to compile .less files using that library and you have to tell BraincraftedBootstrapBundle if you want to use less or lessphp.

LESS

We highly recommend using the original version of LESS, since the developers of Bootstrap only use this version to compile the stylesheets and it can happen that Bootstrap does not compile with lessphp. To install LESS, you need NPM.

npm install -g less

You probably need to configure Assetic to use the installed binary. Change the path to the location of Node.js on your system.

# app/config/config.yml
assetic:
    filters:
        less:
            node: /usr/local/bin/node
            node_paths: [/usr/local/lib/node_modules]
            apply_to: "\.less$"
        cssrewrite: ~
braincrafted_bootstrap:
    css_preprocessor: less

lessphp Deprecated

lessphp does no longer compile recent versions of Bootstrap. If you absolutely don't want to use the Less compiler written in Node.js (or the Sass port of Bootstrap) you should use less.php (see below).

Although it is not recommended to use leafo/lessphp, you can use it and install it via Composer.

{
  "require": {
    "leafo/lessphp": "0.4.0"
  }
}

And add the following section to your config.

# app/config/config.yml
assetic:
    filters:
        lessphp:
             file: %kernel.root_dir%/../vendor/leafo/lessphp/lessc.inc.php
             apply_to: "\.less$"
        cssrewrite: ~
braincrafted_bootstrap:
    css_preprocessor: lessphp

Hint If a new version of Bootstrap no longer compiles with lessphp, check the lessphp website whether a new version has been released.

less.php

Although it is not recommended to use oyejorge/less.php, you can use it and install it via Composer.

{
  "require": {
    "oyejorge/less.php": "~1.5",
  }
}

And add the following section to your config.

# app/config/config.yml
assetic:
    filters:
        lessphp:
             file: %kernel.root_dir%/../vendor/oyejorge/less.php/lessc.inc.php
             apply_to: "\.less$"
        cssrewrite: ~
braincrafted_bootstrap:
    css_preprocessor: lessphp

Hint If a new version of Bootstrap no longer compiles with lessphp, check the less.php website whether a new version has been released.

Installing a Sass compiler

Starting with Version 2.1 BootstrapBundle supports bootstrap-sass, the official Sass port of Bootstrap.

If you change the config value of css_preprocessor to sass BootstrapBundle will automatically use the appropriate default values for the other configuration options.

# app/config/config.yml
assetic:
    filters:
        sass:
            bin: /usr/local/bin/sass
            apply_to: "\.scss$"
braincrafted_bootstrap:
    css_preprocessor: sass

scssphp

BootstrapBundle also supports leafo/scssphp to compile Sass. Just like the PHP port of LESS please be aware that newer versions of Bootstrap can not be compiled with scssphp. If you still want to use it you can install it with Composer:

{
    "require": {
        "leafo/scssphp": "~1.1",
    }
}

And add the following section to your config.

# app/config/config.yml
assetic:
    filters:
        scssphp: ~
            cssrewrite: ~
braincrafted_bootstrap:
    css_preprocessor: scssphp

Installing Glyphicons

Bootstrap comes with support for Glyphicons. However, you need to copy the icon fonts into your web/ directory, so that browsers can find it. BraincraftedBootstrapBundle comes with a command to copy the files for you.

php app/console braincrafted:bootstrap:install

Since you need to do this every time the font changes in Bootstrap, you can also configure a ScriptHandler in your composer.json. Now the icon fonts are copied into the web directory after Composer updates the packages.

{
    ...
    "scripts": {
        "post-install-cmd": [
            ...
            "Braincrafted\\Bundle\\BootstrapBundle\\Composer\\ScriptHandler::install"
        ],
        "post-update-cmd": [
            ...
            "Braincrafted\\Bundle\\BootstrapBundle\\Composer\\ScriptHandler::install"
        ]
    }
    ...
}

BraincraftedBootstrapBundle can be configured using your project's config.yml. The following snippet shows all possible configuration options and their default values.

The options under auto_configure are used to disable the auto configuration functionality of BraincraftedBootstrapBundle. For example, if you want to override the default Assetic configuration of the bundle, you need to set the value to false.

# app/config/config.yml
braincrafted_bootstrap:
    output_dir:
    assets_dir: %kernel.root_dir%/../vendor/twbs/bootstrap
    jquery_path: %kernel.root_dir%/../vendor/jquery/jquery/jquery-1.10.2.js
    css_preprocessor: less # "less", "lessphp", "sass" or "none"
    fonts_dir: %kernel.root_dir%/../web/fonts
    auto_configure:
        assetic: true
        twig: true
        knp_menu: true
        knp_paginator: true
    customize:
        variables_file: ~
        bootstrap_output: %kernel.root_dir%/Resources/less/bootstrap.less
        bootstrap_template: BraincraftedBootstrapBundle:Bootstrap:bootstrap.less.twig
icon_prefix: glyphicon fontawesome_dir: %kernel.root_dir%/../vendor/fortawesome/font-awesome

The option braincrafted_bootstrap.output_dir defines the directory where BootstrapBundle puts the Bootstrap asset files. This directory has to be relative to the Assetic output directory (configured with the assetic.write_to option). For example, if you want to have the Bootstrap assets in web/bootstrap/(css|js) set braincrafted_bootstrap.output_dir to bootstrap.

The option braincrafted_bootstrap.fonts_dir sets the directory where the install command places the font files. The default value is the web directory. This option has been added in BootstrapBundle v2.1.

Assetic Configuration

If the option braincrafted_bootstrap.auto_configure.assetic is set to true the bundle configures Assetic for you. In case you want to adapt the configuration, you can base it on the default one.

# app/config/config.yml

braincrafted_bootstrap:
    auto_configure:
        assetic: false

assetic:
    ...
    assets:
        bootstrap_css:
            inputs:
                - %kernel.root_dir%/../vendor/twbs/bootstrap/less/bootstrap.less
                - %kernel.root_dir%/../vendor/braincrafted/bootstrap-bundle/Braincrafted/Bundle/BootstrapBundle/Resources/less/form.less
            filters:
                - less
                - cssrewrite
            output: css/bootstrap.css
        bootstrap_js:
            inputs:
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/transition.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/alert.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/button.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/carousel.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/collapse.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/dropdown.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/modal.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/tooltip.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/popover.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/scrollspy.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/tab.js
                - %kernel.root_dir%/../vendor/twbs/bootstrap/js/affix.js
                - %kernel.root_dir%/../vendor/braincrafted/bootstrap-bundle/Braincrafted/Bundle/BootstrapBundle/Resources/js/bc-bootstrap-collection.js
            output: js/bootstrap.js
        jquery:
            inputs:
                - %kernel.root_dir%/../vendor/jquery/jquery/jquery-1.10.2.js
            output: js/jquery.js
    

Warning If you don't use Assetic to compile the CSS code you have to manually include the styles from the Resources/less/form.less file that is bundles with BootstrapBundle.

Twig Configuration

If the option braincrafted_bootstrap.auto_configure.twig is set to true (the default value), your project will automatically use the form theme provided with BraincraftedBootstrapBundle. You can turn auto configuration off and manually configure Twig if you want to have more control.

# app/config/config.yml

braincrafted_bootstrap:
    auto_configure:
        twig: false

twig:
    form:
        resources:
            - BraincraftedBootstrapBundle:Form:bootstrap.html.twig

KnpMenuBundle Configuration

If the option braincrafted_bootstrap.auto_configure.knp_menu is set to true (the default value) BraincraftedBootstrapBundle will automatically configure KnpMenuBundle to use Bootstrap. However, if you want more control you can manually configure KnpMenuBundle.

# app/config/config.yml

braincrafted_bootstrap:
    auto_configure:
        knp_menu: false

knp_menu:
    twig:
        template: BraincraftedBootstrapBundle:Menu:bootstrap.html.twig

KnpPaginatorBundle Configuration

Once again, if the option braincrafted_bootstrap.auto_configure.knp_paginator is set to true (the default value), the bundle will be configured automatically. You can set the value to false to manually configure KnpPaginatorBundle.

# app/config/config.yml

braincrafted_bootstrap:
    auto_configure:
        knp_paginator: false

knp_paginator:
    template:
        pagination: BraincraftedBootstrapBundle:Pagination:bootstrap.html.twig

In your template you need to include the CSS and JavaScript files from Bootstrap, that are generated with Assetic. You also need to include jQuery. To enable support for HTML5 elements and media queries to IE8, we recommend to add HTML5 Shim and Respond.js as well.

<!-- src/Acme/DemoBundle/Resources/views/layout.html.twig -->

<!DOCTYPE html>
<html>
<head>

    <title>Bootstrap 101 Template</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!-- Bootstrap -->
    <link href="{{ asset('css/bootstrap.css') }}" rel="stylesheet" media="screen">

    <!-- HTML5 Shim and Respond.js add IE8 support of HTML5 elements and media queries -->
    {% include 'BraincraftedBootstrapBundle::ie8-support.html.twig' %}

</head>

<body>
    <h1>Hello, world!</h1>

    <!-- jQuery (necessary for Bootstraps JavaScript plugins) -->
    <script src="{{ asset('js/jquery.js') }}"></script>
    <!-- Include all JavaScripts, compiled by Assetic -->
    <script src="{{ asset('js/bootstrap.js') }}"></script>
</body>
</html>

BraincraftedBootstrapBundle gives you the ability to customize Bootstrap.

Custom variables.less

Bootstrap has the ability to be modified by manipulating the variables.less file provided with the framework. However, since this bundle uses Composer to download and install Bootstrap, we cannot overwrite the variables.less file (every composer update would eliminate changes made to that file). Because of this it is necessary to build a custom bootstrap.less that includes the custom variables.less and all the other .less files from Bootstrap.

BraincraftedBootstrapBundle helps you by generating a custom bootstrap.less and importing your variables.less and all LESS files from Bootstrap.

This feature is only activated if:

  • The option braincrafted_bootstrap.customize.variables_file is set to a value other than NULL
  • You use LESS, that is, the option braincrafted_bootstrap.css_preprocessor is set to less or lessphp
# app/config/config.yml

braincrafted_bootstrap:
    customize:
        variables_file: %kernel.root_dir%/Resources/less/variables.less

It is also possible to use a file provided by a bundle. You can use the option braincrafted_bootstrap.bootstrap_output to configure where BraincraftedBootstrapBundle stores the generated bootstrap.less file. The default location is app/Resources/less/bootstrap.less. The option braincrafted_bootstrap.customize.bootstrap_template defines the template used to generate the file. You can use the variables variables_file and assets_dir in this template. The latter points to the value of the option braincrafted_bootstrap.assets_dir.

After configuring the bundle with your customer variables.less file, you need to generate the bootstrap.less file.

$ php app/console braincrafted:bootstrap:generate

Now you can use assetic:dump to generate the CSS files.

Warning If you customized the configuration of Assetic you need to change it to use the bootstrap.less file generated by the bundle is used.

# app/config/config.yml

assetic:
    ...
    assets:
        bootstrap_css:
            inputs:
                - %kernel.root_dir%/Resources/less/bootstrap.less
            filters:
                - less
                - cssrewrite
            output: css/bootstrap.css

Custom Form Widgets

If you want to overwrite only a part of the form template provided by BraincraftedBootstrapBundle, you can use template inheritance to achieve this without duplicating code from the bundle.

# app/config/config.yml

braincrafted_bootstrap:
    auto_configure:
        twig: false

twig:
    form:
        resources:
            - AcmeDemoBundle:Form:form_div_layout.html.twig
<!-- src/Acme/DemoBundle/Resources/views/Form/form_div_layout.html.twig -->

{% extends 'BraincraftedBootstrapBundle:Form:bootstrap.html.twig' %}

<!-- Custom code for the URL widget -->
{% block url_widget %}
{% spaceless %}
    {% set type = type|default('url') %}
    {{ block('form_widget_simple') }}
{% endspaceless %}
{% endblock url_widget %}