123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171 |
- Installation
- ============
- SonataAdminBundle can be installed at any moment during a project's lifecycle,
- whether it's a clean Symfony installation or an existing project.
- Downloading the code
- --------------------
- Use composer to manage your dependencies and download SonataAdminBundle:
- .. code-block:: bash
- $ 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 <https://packagist.org/packages/sonata-project/admin-bundle>`_
- for older versions:
- .. code-block:: bash
- Please provide a version constraint for the sonata-project/admin-bundle requirement: dev-master
- 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:
- - `SonataDoctrineORMAdminBundle <https://sonata-project.org/bundles/doctrine-orm-admin/master/doc/reference/installation.html>`_
- - `SonataDoctrineMongoDBAdminBundle <https://github.com/sonata-project/SonataDoctrineMongoDBAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
- - `SonataPropelAdminBundle <https://sonata-project.org/bundles/propel-admin/master/doc/reference/installation.html>`_
- - `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
- .. note::
- Don't know which to choose? Most new users prefer SonataDoctrineORMAdmin, to interact with traditional relational databases (MySQL, PostgreSQL, etc)
- 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:
- - `SonataBlockBundle <https://sonata-project.org/bundles/block/master/doc/reference/installation.html>`_
- - `KnpMenuBundle <https://github.com/KnpLabs/KnpMenuBundle/blob/master/Resources/doc/index.md#installation>`_ (Version 2.*)
- 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:
- .. code-block:: php
- <?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 <https://github.com/sonata-project/SonataAdminBundle>`_ 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`.
- .. code-block:: yaml
- framework:
- translator: { fallbacks: ["%locale%"] }
- For more information: http://symfony.com/doc/current/translation.html#configuration
- 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:
- .. configuration-block::
- .. code-block:: 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.
- Cleaning up
- -----------
- Now, install the assets from the bundles:
- .. code-block:: bash
- $ php bin/console assets:install
- Usually, when installing new bundles, it is a good practice to also delete your cache:
- .. code-block:: bash
- $ 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 :doc:`getting_started` chapter.
- .. _Google: http://www.google.com
- .. _`Sonata Users Group`: https://groups.google.com/group/sonata-users
- .. _`Symfony Support`: http://symfony.com/support
- .. _`open issues on GitHub`: https://github.com/sonata-project/SonataAdminBundle/issues
|