installation.rst 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171
  1. Installation
  2. ============
  3. SonataAdminBundle can be installed at any moment during a project's lifecycle,
  4. whether it's a clean Symfony installation or an existing project.
  5. Downloading the code
  6. --------------------
  7. Use composer to manage your dependencies and download SonataAdminBundle:
  8. .. code-block:: bash
  9. $ php composer.phar require sonata-project/admin-bundle
  10. You'll be asked to type in a version constraint. 'dev-master' will get you the latest
  11. version, compatible with the latest Symfony version. Check `packagist <https://packagist.org/packages/sonata-project/admin-bundle>`_
  12. for older versions:
  13. .. code-block:: bash
  14. Please provide a version constraint for the sonata-project/admin-bundle requirement: dev-master
  15. Selecting and downloading a storage bundle
  16. ------------------------------------------
  17. SonataAdminBundle is storage agnostic, meaning it can work with several storage
  18. mechanisms. Depending on which you are using on your project, you'll need to install
  19. one of the following bundles. In the respective links you'll find simple installation
  20. instructions for each of them:
  21. - `SonataDoctrineORMAdminBundle <https://sonata-project.org/bundles/doctrine-orm-admin/master/doc/reference/installation.html>`_
  22. - `SonataDoctrineMongoDBAdminBundle <https://github.com/sonata-project/SonataDoctrineMongoDBAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
  23. - `SonataPropelAdminBundle <https://sonata-project.org/bundles/propel-admin/master/doc/reference/installation.html>`_
  24. - `SonataDoctrinePhpcrAdminBundle <https://github.com/sonata-project/SonataDoctrinePhpcrAdminBundle/blob/master/Resources/doc/reference/installation.rst>`_
  25. .. note::
  26. Don't know which to choose? Most new users prefer SonataDoctrineORMAdmin, to interact with traditional relational databases (MySQL, PostgreSQL, etc)
  27. Enabling SonataAdminBundle and its dependencies
  28. -----------------------------------------------
  29. SonataAdminBundle relies on other bundles to implement some features.
  30. Besides the storage layer mentioned on step 2, there are other bundles needed
  31. for SonataAdminBundle to work:
  32. - `SonataBlockBundle <https://sonata-project.org/bundles/block/master/doc/reference/installation.html>`_
  33. - `KnpMenuBundle <https://github.com/KnpLabs/KnpMenuBundle/blob/master/Resources/doc/index.md#installation>`_ (Version 2.*)
  34. These bundles are automatically downloaded by composer as a dependency of SonataAdminBundle.
  35. However, you have to enable them in your ``AppKernel.php``, and configure them manually. Don't
  36. forget to enable SonataAdminBundle too:
  37. .. code-block:: php
  38. <?php
  39. // app/AppKernel.php
  40. public function registerBundles()
  41. {
  42. return array(
  43. // ...
  44. // The admin requires some twig functions defined in the security
  45. // bundle, like is_granted
  46. new Symfony\Bundle\SecurityBundle\SecurityBundle(),
  47. // Add your dependencies
  48. new Sonata\CoreBundle\SonataCoreBundle(),
  49. new Sonata\BlockBundle\SonataBlockBundle(),
  50. new Knp\Bundle\MenuBundle\KnpMenuBundle(),
  51. //...
  52. // If you haven't already, add the storage bundle
  53. // This example uses SonataDoctrineORMAdmin but
  54. // it works the same with the alternatives
  55. new Sonata\DoctrineORMAdminBundle\SonataDoctrineORMAdminBundle(),
  56. // Then add SonataAdminBundle
  57. new Sonata\AdminBundle\SonataAdminBundle(),
  58. // ...
  59. );
  60. }
  61. .. note::
  62. Since version 2.3 SonatajQueryBundle is not required anymore as assets are available in this
  63. bundle. The bundle is also registered in `bower.io <https://github.com/sonata-project/SonataAdminBundle>`_ so
  64. you can use bower to handle your assets. To make sure you get the dependencies
  65. that match the version of SonataAdminBundle you are using, you can make bower
  66. use the local bower dependency file, like this : ``bower install ./vendor/sonata-project/admin-bundle/bower.json``
  67. .. note::
  68. You must enable translator service in `config.yml`.
  69. .. code-block:: yaml
  70. framework:
  71. translator: { fallbacks: ["%locale%"] }
  72. For more information: http://symfony.com/doc/current/translation.html#configuration
  73. Configuring SonataAdminBundle dependencies
  74. ------------------------------------------
  75. You will need to configure SonataAdminBundle's dependencies. For each of the above
  76. mentioned bundles, check their respective installation/configuration instructions
  77. files to see what changes you have to make to your Symfony configuration.
  78. SonataAdminBundle provides a SonataBlockBundle block that's used on the administration
  79. dashboard. To be able to use it, make sure it's enabled on SonataBlockBundle's configuration:
  80. .. configuration-block::
  81. .. code-block:: yaml
  82. # app/config/config.yml
  83. sonata_block:
  84. default_contexts: [cms]
  85. blocks:
  86. # enable the SonataAdminBundle block
  87. sonata.admin.block.admin_list:
  88. contexts: [admin]
  89. .. note::
  90. Don't worry too much if, at this point, you don't yet understand fully
  91. what a block is. SonataBlockBundle is a useful tool, but it's not vital
  92. that you understand it right now.
  93. Cleaning up
  94. -----------
  95. Now, install the assets from the bundles:
  96. .. code-block:: bash
  97. $ php bin/console assets:install
  98. Usually, when installing new bundles, it is a good practice to also delete your cache:
  99. .. code-block:: bash
  100. $ php bin/console cache:clear
  101. At this point, your Symfony installation should be fully functional, with no errors
  102. showing up from SonataAdminBundle or its dependencies. SonataAdminBundle is installed
  103. but not yet configured (more on that in the next section), so you won't be able to
  104. use it yet.
  105. If, at this point or during the installation, you come across any errors, don't panic:
  106. - Read the error message carefully. Try to find out exactly which bundle is causing the error. Is it SonataAdminBundle or one of the dependencies?
  107. - Make sure you followed all the instructions correctly, for both SonataAdminBundle and its dependencies.
  108. - 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.
  109. - Still no luck? Try checking the project's `open issues on GitHub`_.
  110. After you have successfully installed the above bundles you need to configure
  111. SonataAdminBundle for administering your models. All that is needed to quickly
  112. set up SonataAdminBundle is described in the :doc:`getting_started` chapter.
  113. .. _Google: http://www.google.com
  114. .. _`Sonata Users Group`: https://groups.google.com/group/sonata-users
  115. .. _`Symfony Support`: http://symfony.com/support
  116. .. _`open issues on GitHub`: https://github.com/sonata-project/SonataAdminBundle/issues