Version

Documentation » Admin

2. Getting started with SonataAdminBundle »

« 4. The List View

1. Installation

SonataAdminBundle can be installed at any moment during a project’s lifecycle, whether it’s a clean Symfony installation or an existing project.

1.1. Downloading the code

Use composer to manage your dependencies and download SonataAdminBundle:

$ php composer.phar require sonata-project/admin-bundle

You’ll be asked to type in a version constraint. ‘dev-master’ will get you the latest version, compatible with the latest Symfony version. Check packagist for older versions:

Please provide a version constraint for the sonata-project/admin-bundle requirement: dev-master

1.2. Selecting and downloading a storage bundle

SonataAdminBundle is storage agnostic, meaning it can work with several storage mechanisms. Depending on which you are using on your project, you’ll need to install one of the following bundles. In the respective links you’ll find simple installation instructions for each of them:

Note

Don’t know which to choose? Most new users prefer SonataDoctrineORMAdmin, to interact with traditional relational databases (MySQL, PostgreSQL, etc)

1.3. Enabling SonataAdminBundle and its dependencies

SonataAdminBundle relies on other bundles to implement some features. Besides the storage layer mentioned on step 2, there are other bundles needed for SonataAdminBundle to work:

These bundles are automatically downloaded by composer as a dependency of SonataAdminBundle. However, you have to enable them in your AppKernel.php, and configure them manually. Don’t forget to enable SonataAdminBundle too:

<?php
// app/AppKernel.php

public function registerBundles()
{
    return array(
        // ...

        // The admin requires some twig functions defined in the security
        // bundle, like is_granted
        new Symfony\Bundle\SecurityBundle\SecurityBundle(),

        // Add your dependencies
        new Sonata\CoreBundle\SonataCoreBundle(),
        new Sonata\BlockBundle\SonataBlockBundle(),
        new Knp\Bundle\MenuBundle\KnpMenuBundle(),
        //...

        // If you haven't already, add the storage bundle
        // This example uses SonataDoctrineORMAdmin but
        // it works the same with the alternatives
        new Sonata\DoctrineORMAdminBundle\SonataDoctrineORMAdminBundle(),

        // Then add SonataAdminBundle
        new Sonata\AdminBundle\SonataAdminBundle(),

        // ...
    );
}

Note

Since version 2.3 SonatajQueryBundle is not required anymore as assets are available in this bundle. The bundle is also registered in bower.io so you can use bower to handle your assets. To make sure you get the dependencies that match the version of SonataAdminBundle you are using, you can make bower use the local bower dependency file, like this : bower install ./vendor/sonata-project/admin-bundle/bower.json

Note

You must enable translator service in config.yml.

framework:
    translator: { fallbacks: ["%locale%"] }

For more information: http://symfony.com/doc/current/translation.html#configuration

1.4. Configuring SonataAdminBundle dependencies

You will need to configure SonataAdminBundle’s dependencies. For each of the above mentioned bundles, check their respective installation/configuration instructions files to see what changes you have to make to your Symfony configuration.

SonataAdminBundle provides a SonataBlockBundle block that’s used on the administration dashboard. To be able to use it, make sure it’s enabled on SonataBlockBundle’s configuration:

  • YAML
    # app/config/config.yml
    
    sonata_block:
        default_contexts: [cms]
        blocks:
    
            # enable the SonataAdminBundle block
            sonata.admin.block.admin_list:
                contexts:   [admin]
    

Note

Don’t worry too much if, at this point, you don’t yet understand fully what a block is. SonataBlockBundle is a useful tool, but it’s not vital that you understand it right now.

1.5. Cleaning up

Now, install the assets from the bundles:

$ php bin/console assets:install

Usually, when installing new bundles, it is a good practice to also delete your cache:

$ php bin/console cache:clear

At this point, your Symfony installation should be fully functional, with no errors showing up from SonataAdminBundle or its dependencies. SonataAdminBundle is installed but not yet configured (more on that in the next section), so you won’t be able to use it yet.

If, at this point or during the installation, you come across any errors, don’t panic:

  • Read the error message carefully. Try to find out exactly which bundle is causing the error. Is it SonataAdminBundle or one of the dependencies?
  • Make sure you followed all the instructions correctly, for both SonataAdminBundle and its dependencies.
  • Odds are that someone already had the same problem, and it’s documented somewhere. Check Google, Sonata Users Group or Symfony Support to see if you can find a solution.
  • Still no luck? Try checking the project’s open issues on GitHub.

After you have successfully installed the above bundles you need to configure SonataAdminBundle for administering your models. All that is needed to quickly set up SonataAdminBundle is described in the Getting started with SonataAdminBundle chapter.

Found a typo? Something is wrong in this documentation? Just fork and edit it!