installation.rst 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
  1. .. index::
  2. single: Installation
  3. Installation
  4. ============
  5. Prerequisites
  6. -------------
  7. PHP 5.3 and Symfony 2 are needed to make this bundle work; there are also some Sonata dependencies that need to be installed and configured beforehand:
  8. - `SonataAdminBundle <https://sonata-project.org/bundles/admin>`_
  9. - `SonataEasyExtendsBundle <https://sonata-project.org/bundles/easy-extends>`_
  10. You will need to install those in their 2.0 branches (or master if they don't
  11. have a similar branch). Follow also their configuration step; you will find everything you need in their own installation chapter.
  12. .. note::
  13. If a dependency is already installed somewhere in your project or in
  14. another dependency, you won't need to install it again.
  15. Enable the Bundle
  16. -----------------
  17. .. code-block:: bash
  18. php composer.phar require sonata-project/user-bundle --no-update
  19. php composer.phar require sonata-project/doctrine-orm-admin-bundle --no-update # optional
  20. php composer.phar require friendsofsymfony/rest-bundle --no-update # optional when using api
  21. php composer.phar require nelmio/api-doc-bundle --no-update # optional when using api
  22. php composer.phar update
  23. Next, be sure to enable the bundles in your and ``AppKernel.php`` file:
  24. .. code-block:: php
  25. <?php
  26. // app/AppKernel.php
  27. public function registerbundles()
  28. {
  29. return array(
  30. new Sonata\CoreBundle\SonataCoreBundle(),
  31. new Sonata\BlockBundle\SonataBlockBundle(),
  32. new Sonata\EasyExtendsBundle\SonataEasyExtendsBundle(),
  33. // ...
  34. // You have 2 options to initialize the SonataUserBundle in your AppKernel,
  35. // you can select which bundle SonataUserBundle extends
  36. // Most of the cases, you'll want to extend FOSUserBundle though ;)
  37. // extend the ``FOSUserBundle``
  38. new FOS\UserBundle\FOSUserBundle(),
  39. new Sonata\UserBundle\SonataUserBundle('FOSUserBundle'),
  40. // OR
  41. // the bundle will NOT extend ``FOSUserBundle``
  42. new Sonata\UserBundle\SonataUserBundle(),
  43. // ...
  44. );
  45. }
  46. Configuration
  47. -------------
  48. When using ACL, the ``UserBundle`` can prevent `normal` user to change settings of `super-admin` users, to enable this add to the configuration:
  49. .. code-block:: yaml
  50. # app/config/config.yml
  51. sonata_user:
  52. security_acl: true
  53. manager_type: orm # can be orm or mongodb
  54. sonata_block:
  55. blocks:
  56. #...
  57. sonata.user.block.menu: # used to display the menu in profile pages
  58. sonata.user.block.account: # used to display menu option (login option)
  59. sonata.block.service.text: # used to if you plan to use Sonata user routes
  60. # app/config/security.yml
  61. security:
  62. # [...]
  63. encoders:
  64. FOS\UserBundle\Model\UserInterface: sha512
  65. acl:
  66. connection: default
  67. Doctrine Configuration
  68. ~~~~~~~~~~~~~~~~~~~~~~
  69. Add these config lines
  70. .. code-block:: yaml
  71. # app/config/config.yml
  72. fos_user:
  73. db_driver: orm # can be orm or odm
  74. firewall_name: main
  75. user_class: Sonata\UserBundle\Entity\BaseUser
  76. group:
  77. group_class: Sonata\UserBundle\Entity\BaseGroup
  78. group_manager: sonata.user.orm.group_manager # If you're using doctrine orm (use sonata.user.mongodb.group_manager for mongodb)
  79. service:
  80. user_manager: sonata.user.orm.user_manager # If you're using doctrine orm (use sonata.user.mongodb.user_manager for mongodb)
  81. doctrine:
  82. dbal:
  83. types:
  84. json: Sonata\Doctrine\Types\JsonType
  85. And these in the config mapping definition (or enable `auto_mapping <http://symfony.com/doc/2.0/reference/configuration/doctrine.html#configuration-overview>`_):
  86. .. code-block:: yaml
  87. # app/config/config.yml
  88. doctrine:
  89. orm:
  90. entity_managers:
  91. default:
  92. mappings:
  93. ApplicationSonataUserBundle: ~
  94. SonataUserBundle: ~
  95. FOSUserBundle: ~ # If SonataUserBundle extends it
  96. Use custom SonataUser controllers and templates instead of FOSUser ones
  97. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98. If you wish to use custom ``SonataUserBundle`` templates and controllers instead of ``FOSUser`` ones, you will have to update your ``routing.yml`` file as follows:
  99. Replace:
  100. .. code-block:: yaml
  101. fos_user_security:
  102. resource: "@FOSUserBundle/Resources/config/routing/security.xml"
  103. fos_user_resetting:
  104. resource: "@FOSUserBundle/Resources/config/routing/resetting.xml"
  105. prefix: /resetting
  106. fos_user_profile:
  107. resource: "@FOSUserBundle/Resources/config/routing/profile.xml"
  108. prefix: /profile
  109. fos_user_register:
  110. resource: "@FOSUserBundle/Resources/config/routing/registration.xml"
  111. prefix: /register
  112. fos_user_change_password:
  113. resource: "@FOSUserBundle/Resources/config/routing/change_password.xml"
  114. prefix: /profile
  115. With:
  116. .. code-block:: yaml
  117. sonata_user_security:
  118. resource: "@SonataUserBundle/Resources/config/routing/sonata_security_1.xml"
  119. sonata_user_resetting:
  120. resource: "@SonataUserBundle/Resources/config/routing/sonata_resetting_1.xml"
  121. prefix: /resetting
  122. sonata_user_profile:
  123. resource: "@SonataUserBundle/Resources/config/routing/sonata_profile_1.xml"
  124. prefix: /profile
  125. sonata_user_register:
  126. resource: "@SonataUserBundle/Resources/config/routing/sonata_registration_1.xml"
  127. prefix: /register
  128. sonata_user_change_password:
  129. resource: "@SonataUserBundle/Resources/config/routing/sonata_change_password_1.xml"
  130. prefix: /profile
  131. Integrating the bundle into the Sonata Admin Bundle
  132. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  133. Add the related security routing information:
  134. .. code-block:: yaml
  135. # app/config/routing.yml
  136. sonata_user_admin_security:
  137. resource: '@SonataUserBundle/Resources/config/routing/admin_security.xml'
  138. prefix: /admin
  139. sonata_user_admin_resetting:
  140. resource: '@SonataUserBundle/Resources/config/routing/admin_resetting.xml'
  141. prefix: /admin/resetting
  142. Then, add a new custom firewall handlers for the admin:
  143. .. code-block:: yaml
  144. # app/config/security.yml
  145. security:
  146. role_hierarchy:
  147. ROLE_ADMIN: [ROLE_USER, ROLE_SONATA_ADMIN]
  148. ROLE_SUPER_ADMIN: [ROLE_ADMIN, ROLE_ALLOWED_TO_SWITCH]
  149. SONATA:
  150. - ROLE_SONATA_PAGE_ADMIN_PAGE_EDIT # if you are using acl then this line must be commented
  151. providers:
  152. fos_userbundle:
  153. id: fos_user.user_manager
  154. firewalls:
  155. # Disabling the security for the web debug toolbar, the profiler and Assetic.
  156. dev:
  157. pattern: ^/(_(profiler|wdt)|css|images|js)/
  158. security: false
  159. # -> custom firewall for the admin area of the URL
  160. admin:
  161. pattern: /admin(.*)
  162. context: user
  163. form_login:
  164. provider: fos_userbundle
  165. login_path: /admin/login
  166. use_forward: false
  167. check_path: /admin/login_check
  168. failure_path: null
  169. logout:
  170. path: /admin/logout
  171. target: /admin/login
  172. anonymous: true
  173. # -> end custom configuration
  174. # default login area for standard users
  175. # This firewall is used to handle the public login area
  176. # This part is handled by the FOS User Bundle
  177. main:
  178. pattern: .*
  179. context: user
  180. form_login:
  181. provider: fos_userbundle
  182. login_path: /login
  183. use_forward: false
  184. check_path: /login_check
  185. failure_path: null
  186. logout: true
  187. anonymous: true
  188. The last part is to define 3 new access control rules:
  189. .. code-block:: yaml
  190. # app/config/security.yml
  191. security:
  192. access_control:
  193. # URL of FOSUserBundle which need to be available to anonymous users
  194. - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }
  195. - { path: ^/register, role: IS_AUTHENTICATED_ANONYMOUSLY }
  196. - { path: ^/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }
  197. # Admin login page needs to be accessed without credential
  198. - { path: ^/admin/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }
  199. - { path: ^/admin/logout$, role: IS_AUTHENTICATED_ANONYMOUSLY }
  200. - { path: ^/admin/login_check$, role: IS_AUTHENTICATED_ANONYMOUSLY }
  201. - { path: ^/admin/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }
  202. # Secured part of the site
  203. # This config requires being logged for the whole site and having the admin role for the admin part.
  204. # Change these rules to adapt them to your needs
  205. - { path: ^/admin/, role: [ROLE_ADMIN, ROLE_SONATA_ADMIN] }
  206. - { path: ^/.*, role: IS_AUTHENTICATED_ANONYMOUSLY }
  207. Using the roles
  208. ---------------
  209. Each admin has its own roles, use the user form to assign them to other users.
  210. The available roles to assign to others are limited to the roles available to the user editing the form.
  211. Extending the Bundle
  212. --------------------
  213. At this point, the bundle is functional, but not quite ready yet. You need to generate the correct entities for the media:
  214. .. code-block:: bash
  215. php app/console sonata:easy-extends:generate SonataUserBundle -d src
  216. If you specify no parameter, the files are generated in ``app/Application/SonataUserBundle`` but you can specify the path with ``--dest=src``
  217. .. note::
  218. The command will generate domain objects in an ``Application`` namespace.
  219. So you can point entities' associations to a global and common namespace.
  220. This will make Entities sharing easier as your models will allow to
  221. point to a global namespace. For instance the user will be
  222. ``Application\Sonata\UserBundle\Entity\User``.
  223. Now, add the new ``Application`` Bundle into the kernel:
  224. .. code-block:: php
  225. <?php
  226. // AppKernel.php
  227. class AppKernel {
  228. public function registerbundles()
  229. {
  230. return array(
  231. // Application Bundles
  232. // ...
  233. new Application\Sonata\UserBundle\ApplicationSonataUserBundle(),
  234. // ...
  235. )
  236. }
  237. }
  238. And configure ``FosUserBundle`` to use the newly generated ``User`` and ``Group``
  239. classes:
  240. .. code-block:: yaml
  241. # app/config/config.yml
  242. fos_user:
  243. db_driver: orm # can be orm or odm
  244. firewall_name: main
  245. user_class: Application\Sonata\UserBundle\Entity\User
  246. group:
  247. group_class: Application\Sonata\UserBundle\Entity\Group
  248. group_manager: sonata.user.orm.group_manager # If you're using doctrine orm (use sonata.user.mongodb.group_manager for mongodb)
  249. service:
  250. user_manager: sonata.user.orm.user_manager # If you're using doctrine orm (use sonata.user.mongodb.user_manager for mongodb)
  251. doctrine:
  252. dbal:
  253. types:
  254. json: Sonata\Doctrine\Types\JsonType