1 Getting Started With FOSUserBundle

     2 ==================================

     3 

     4 The Symfony2 security component provides a flexible security framework that

     5 allows you to load users from configuration, a database, or anywhere else

     6 you can imagine. The FOSUserBundle builds on top of this to make it quick

     7 and easy to store users in a database.

     8 

     9 So, if you need to persist and fetch the users in your system to and from

    10 a database, then you're in the right place.

    11 

    12 ## Prerequisites

    13 

    14 ### Translations

    15 

    16 If you wish to use default texts provided in this bundle, you have to make

    17 sure you have translator enabled in your config.

    18 

    19 ```

    20 # app/config/config.yml

    21 

    22 framework:

    23     translator: ~

    24 ```

    25 

    26 For more information about translations, check [Symfony documentation](http://symfony.com/doc/2.0/book/translation.html).

    27 

    28 ## Installation

    29 

    30 Installation is a quick (I promise!) 8 step process:

    31 

    32 1. Download FOSUserBundle

    33 2. Configure the Autoloader

    34 3. Enable the Bundle

    35 4. Create your User class

    36 5. Configure your application's security.yml

    37 6. Configure the FOSUserBundle

    38 7. Import FOSUserBundle routing

    39 8. Update your database schema

    40 

    41 ### Step 1: Download FOSUserBundle

    42 

    43 Ultimately, the FOSUserBundle files should be downloaded to the

    44 `vendor/bundles/FOS/UserBundle` directory.

    45 

    46 This can be done in several ways, depending on your preference. The first

    47 method is the standard Symfony2 method.

    48 

    49 **Using the vendors script**

    50 

    51 Add the following lines in your `deps` file:

    52 

    53 ```

    54 [FOSUserBundle]

    55     git=git://github.com/FriendsOfSymfony/FOSUserBundle.git

    56     target=bundles/FOS/UserBundle

    57 ```

    58 

    59 Now, run the vendors script to download the bundle:

    60 

    61 ``` bash

    62 $ php bin/vendors install

    63 ```

    64 

    65 **Using submodules**

    66 

    67 If you prefer instead to use git submodules, the run the following:

    68 

    69 ``` bash

    70 $ git submodule add git://github.com/FriendsOfSymfony/FOSUserBundle.git vendor/bundles/FOS/UserBundle

    71 $ git submodule update --init

    72 ```

    73 

    74 ### Step 2: Configure the Autoloader

    75 

    76 Add the `FOS` namespace to your autoloader:

    77 

    78 ``` php

    79 <?php

    80 // app/autoload.php

    81 

    82 $loader->registerNamespaces(array(

    83     // ...

    84     'FOS' => __DIR__.'/../vendor/bundles',

    85 ));

    86 ```

    87 

    88 ### Step 3: Enable the bundle

    89 

    90 Finally, enable the bundle in the kernel:

    91 

    92 ``` php

    93 <?php

    94 // app/AppKernel.php

    95 

    96 public function registerBundles()

    97 {

    98     $bundles = array(

    99         // ...

   100         new FOS\UserBundle\FOSUserBundle(),

   101     );

   102 }

   103 ```

   104 

   105 ### Step 4: Create your User class

   106 

   107 The goal of this bundle is to persist some `User` class to a database (MySql,

   108 MongoDB, CouchDB, etc). Your first job, then, is to create the `User` class

   109 for your application. This class can look and act however you want: add any

   110 properties or methods you find useful. This is *your* `User` class.

   111 

   112 This class has just two requirements, which allow it to take advantage of

   113 all of the functionality in the FOSUserBundle:

   114 

   115 1. It must extend one of the base `User` classes from the bundle

   116 2. It must have an `id` field

   117 

   118 In the following sections, you'll see examples of how your `User` class should

   119 look, depending on how you're storing your users (Doctrine ORM, MongoDB ODM,

   120 or CouchDB ODM).

   121 

   122 Your `User` class can live inside any bundle in your application. For example,

   123 if you work at "Acme" company, then you might create a bundle called `AcmeUserBundle`

   124 and place your `User` class in it.

   125 

   126 **Warning:**

   127 

   128 > If you override the __construct() method in your User class, be sure

   129 > to call parent::__construct(), as the base User class depends on

   130 > this to initialize some fields.

   131 

   132 **a) Doctrine ORM User class**

   133 

   134 If you're persisting your users via the Doctrine ORM, then your `User` class

   135 should live in the `Entity` namespace of your bundle and look like this to

   136 start:

   137 

   138 ``` php

   139 <?php

   140 // src/Acme/UserBundle/Entity/User.php

   141 

   142 namespace Acme\UserBundle\Entity;

   143 

   144 use FOS\UserBundle\Entity\User as BaseUser;

   145 use Doctrine\ORM\Mapping as ORM;

   146 

   147 /**

   148  * @ORM\Entity

   149  * @ORM\Table(name="fos_user")

   150  */

   151 class User extends BaseUser

   152 {

   153     /**

   154      * @ORM\Id

   155      * @ORM\Column(type="integer")

   156      * @ORM\GeneratedValue(strategy="AUTO")

   157      */

   158     protected $id;

   159 

   160     public function __construct()

   161     {

   162         parent::__construct();

   163         // your own logic

   164     }

   165 }

   166 ```

   167 

   168 **Note:**

   169 

   170 > `User` is a reserved keyword in SQL so you cannot use it as table name.

   171 

   172 **b) MongoDB User class**

   173 

   174 If you're persisting your users via the Doctrine MongoDB ODM, then your `User`

   175 class should live in the `Document` namespace of your bundle and look like

   176 this to start:

   177 

   178 ``` php

   179 <?php

   180 // src/Acme/UserBundle/Document/User.php

   181 

   182 namespace Acme\UserBundle\Document;

   183 

   184 use FOS\UserBundle\Document\User as BaseUser;

   185 use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;

   186 

   187 /**

   188  * @MongoDB\Document

   189  */

   190 class User extends BaseUser

   191 {

   192     /**

   193      * @MongoDB\Id(strategy="auto")

   194      */

   195     protected $id;

   196 

   197     public function __construct()

   198     {

   199         parent::__construct();

   200         // your own logic

   201     }

   202 }

   203 ```

   204 

   205 **c) CouchDB User class**

   206 

   207 If you're persisting your users via the Doctrine CouchDB ODM, then your `User`

   208 class should live in the `Document` namespace of your bundle and look like

   209 this to start:

   210 

   211 ``` php

   212 <?php

   213 // src/Acme/UserBundle/Document/User.php

   214 

   215 namespace Acme\UserBundle\Document;

   216 

   217 use FOS\UserBundle\Document\User as BaseUser;

   218 use Doctrine\ODM\CouchDB\Mapping as CouchDB;

   219 

   220 /**

   221  * @CouchDB\Document

   222  */

   223 class User extends BaseUser

   224 {

   225     /**

   226      * @CouchDB\Id

   227      */

   228     protected $id;

   229 

   230     public function __construct()

   231     {

   232         parent::__construct();

   233         // your own logic

   234     }

   235 }

   236 ```

   237 

   238 ### Step 5: Configure your application's security.yml

   239 

   240 In order for Symfony's security component to use the FOSUserBundle, you must

   241 tell it to do so in the `security.yml` file. The `security.yml` file is where the

   242 basic configuration for the security for your application is contained.

   243 

   244 Below is a minimal example of the configuration necessary to use the FOSUserBundle

   245 in your application:

   246 

   247 ``` yaml

   248 # app/config/security.yml

   249 security:

   250     providers:

   251         fos_userbundle:

   252             id: fos_user.user_manager

   253 

   254     firewalls:

   255         main:

   256             pattern: ^/

   257             form_login:

   258                 provider: fos_userbundle

   259             logout:       true

   260             anonymous:    true

   261 

   262     access_control:

   263         - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }

   264         - { path: ^/register, role: IS_AUTHENTICATED_ANONYMOUSLY }

   265         - { path: ^/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }

   266         - { path: ^/admin/, role: ROLE_ADMIN }

   267 

   268     role_hierarchy:

   269         ROLE_ADMIN:       ROLE_USER

   270         ROLE_SUPER_ADMIN: ROLE_ADMIN

   271 ```

   272 

   273 Under the `providers` section, you are making the bundle's packaged user provider

   274 service available via the alias `fos_userbundle`. The id of the bundle's user

   275 provider service is `fos_user.user_manager`.

   276 

   277 Next, take a look at examine the `firewalls` section. Here we have declared a

   278 firewall named `main`. By specifying `form_login`, you have told the Symfony2

   279 framework that any time a request is made to this firewall that leads to the

   280 user needing to authenticate himself, the user will be redirected to a form

   281 where he will be able to enter his credentials. It should come as no surprise

   282 then that you have specified the user provider we declared earlier as the

   283 provider for the firewall to use as part of the authentication process.

   284 

   285 **Note:**

   286 

   287 > Although we have used the form login mechanism in this example, the FOSUserBundle

   288 > user provider is compatible with many other authentication methods as well. Please

   289 > read the Symfony2 Security component documention for more information on the

   290 > other types of authentication methods.

   291 

   292 The `access_control` section is where you specify the credentials necessary for

   293 users trying to access specific parts of your application. The bundle requires

   294 that the login form and all the routes used to create a user and reset the password

   295 be available to unauthenticated users but use the same firewall as

   296 the pages you want to secure with the bundle. This is why you have specified that

   297 the any request matching the `/login` pattern or starting with `/register` or

   298 `/resetting` have been made available to anonymous users. You have also specified

   299 that any request beginning with `/admin` will require a user to have the

   300 `ROLE_ADMIN` role.

   301 

   302 For more information on configuring the `security.yml` file please read the Symfony2

   303 security component [documentation](http://symfony.com/doc/current/book/security.html).

   304 

   305 **Note:**

   306 

   307 > Pay close attention to the name, `main`, that we have given to the firewall which

   308 > the FOSUserBundle is configured in. You will use this in the next step when you

   309 > configure the FOSUserBundle.

   310 

   311 ### Step 6: Configure the FOSUserBundle

   312 

   313 Now that you have properly configured your application's `security.yml` to work

   314 with the FOSUserBundle, the next step is to configure the bundle to work with

   315 the specific needs of your application.

   316 

   317 Add the following configuration to your `config.yml` file according to which type

   318 of datastore you are using.

   319 

   320 ``` yaml

   321 # app/config/config.yml

   322 fos_user:

   323     db_driver: orm # other valid values are 'mongodb', 'couchdb'

   324     firewall_name: main

   325     user_class: Acme\UserBundle\Entity\User

   326 ```

   327 

   328 Or if you prefer XML:

   329 

   330 ``` xml

   331 # app/config/config.xml

   332 <!-- app/config/config.xml -->

   333 

   334 <!-- other valid 'db-driver' values are 'mongodb' and 'couchdb' -->

   335 <fos_user:config

   336     db-driver="orm"

   337     firewall-name="main"

   338     user-class="Acme\UserBundle\Entity\User"

   339 />

   340 ```

   341 

   342 Only three configuration values are required to use the bundle:

   343 

   344 * The type of datastore you are using (`orm`, `mongodb`, or `couchdb`).

   345 * The firewall name which you configured in Step 5.

   346 * The fully qualified class name (FQCN) of the `User` class which you created in Step 2

   347 

   348 ### Step 7: Import FOSUserBundle routing files

   349 

   350 Now that you have activated and configured the bundle, all that is left to do is

   351 import the FOSUserBundle routing files.

   352 

   353 By importing the routing files you will have ready made pages for things such as

   354 logging in, creating users, etc.

   355 

   356 In YAML:

   357 

   358 ``` yaml

   359 # app/config/routing.yml

   360 fos_user_security:

   361     resource: "@FOSUserBundle/Resources/config/routing/security.xml"

   362 

   363 fos_user_profile:

   364     resource: "@FOSUserBundle/Resources/config/routing/profile.xml"

   365     prefix: /profile

   366 

   367 fos_user_register:

   368     resource: "@FOSUserBundle/Resources/config/routing/registration.xml"

   369     prefix: /register

   370 

   371 fos_user_resetting:

   372     resource: "@FOSUserBundle/Resources/config/routing/resetting.xml"

   373     prefix: /resetting

   374 

   375 fos_user_change_password:

   376     resource: "@FOSUserBundle/Resources/config/routing/change_password.xml"

   377     prefix: /change-password

   378 ```

   379 

   380 Or if you prefer XML:

   381 

   382 ``` xml

   383 <!-- app/config/routing.xml -->

   384 <import resource="@FOSUserBundle/Resources/config/routing/security.xml"/>

   385 <import resource="@FOSUserBundle/Resources/config/routing/profile.xml" prefix="/profile" />

   386 <import resource="@FOSUserBundle/Resources/config/routing/registration.xml" prefix="/register" />

   387 <import resource="@FOSUserBundle/Resources/config/routing/resetting.xml" prefix="/resetting" />

   388 <import resource="@FOSUserBundle/Resources/config/routing/change_password.xml" prefix="/change-password" />

   389 ```

   390 

   391 **Note:**

   392 

   393 > In order to use the built-in email functionality (confirmation of the account,

   394 > resetting of the password), you must activate and configure the SwiftmailerBundle.

   395 

   396 ### Step 8: Update your database schema

   397 

   398 Now that the bundle is configured, the last thing you need to do is update your

   399 database schema because you have added a new entity, the `User` class which you

   400 created in Step 2.

   401 

   402 For ORM run the following command.

   403 

   404 ``` bash

   405 $ php app/console doctrine:schema:update --force

   406 ```

   407 

   408 For MongoDB users you can run the following command to create the indexes.

   409 

   410 ``` bash

   411 $ php app/console doctrine:mongodb:schema:create --index

   412 ```

   413 

   414 You now can login at `http://app.com/app_dev.php/login`!

   415 

   416 ### Next Steps

   417 

   418 Now that you have completed the basic installation and configuration of the

   419 FOSUserBundle, you are ready to learn about more advanced features and usages

   420 of the bundle.

   421 

   422 The following documents are available:

   423 

   424 1. [Overriding Templates](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/overriding_templates.md)

   425 2. [Overriding Controllers](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/overriding_controllers.md)

   426 3. [Overriding Forms](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/overriding_forms.md)

   427 4. [Command Line Tools](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/command_line_tools.md)

   428 5. [Supplemental Documenation](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/supplemental.md)

   429 6. [Configuration Reference](https://github.com/FriendsOfSymfony/FOSUserBundle/blob/master/Resources/doc/configuration_reference.md)