Translations¶

If you wish to use default texts provided in this bundle, you have to make sure you have translator enabled in your config.

1
2
3
4

# app/config/config.yml

framework:
    translator: ~

For more information about translations, check Symfony documentation.

Step 1: Download FOSUserBundle using composer¶

Require the bundle with composer:

1

$ composer require friendsofsymfony/user-bundle "~2.0@dev"

Composer will install the bundle to your project's vendor/friendsofsymfony/user-bundle directory. If you encounter installation errors pointing at a lack of configuration parameters, such as The child node "db_driver" at path "fos_user" must be configured, you should complete the configuration in Step 5 first and then re-run this step.

Step 2: Enable the bundle¶

Enable the bundle in the kernel:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new FOS\UserBundle\FOSUserBundle(),
        // ...
    );
}

Step 3: Create your User class¶

The goal of this bundle is to persist some User class to a database (MySql, MongoDB, CouchDB, etc). Your first job, then, is to create the User class for your application. This class can look and act however you want: add any properties or methods you find useful. This is your User class.

The bundle provides base classes which are already mapped for most fields to make it easier to create your entity. Here is how you use it:

1. Extend the base User class (from the Model folder if you are using any of the doctrine variants, or Propel for propel 1.x)
2. Map the id field. It must be protected as it is inherited from the parent class.

In the following sections, you'll see examples of how your User class should look, depending on how you're storing your users (Doctrine ORM, MongoDB ODM, or CouchDB ODM).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<?php
// src/AppBundle/Document/User.php

namespace AppBundle\Document;

use FOS\UserBundle\Model\User as BaseUser;
use Doctrine\ODM\MongoDB\Mapping\Annotations as MongoDB;

/**
 * @MongoDB\Document
 */
class User extends BaseUser
{
    /**
     * @MongoDB\Id(strategy="auto")
     */
    protected $id;

    public function __construct()
    {
        parent::__construct();
        // your own logic
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

<?php
// src/AppBundle/CouchDocument/User.php

namespace AppBundle\CouchDocument;

use FOS\UserBundle\Model\User as BaseUser;
use Doctrine\ODM\CouchDB\Mapping\Annotations as CouchDB;

/**
 * @CouchDB\Document
 */
class User extends BaseUser
{
    /**
     * @CouchDB\Id
     */
    protected $id;

    public function __construct()
    {
        parent::__construct();
        // your own logic
    }
}

Step 4: Configure your application's security.yml¶

In order for Symfony's security component to use the FOSUserBundle, you must tell it to do so in the security.yml file. The security.yml file is where the basic security configuration for your application is contained.

Below is a minimal example of the configuration necessary to use the FOSUserBundle in your application:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# app/config/security.yml
security:
    encoders:
        FOS\UserBundle\Model\UserInterface: bcrypt

    role_hierarchy:
        ROLE_ADMIN:       ROLE_USER
        ROLE_SUPER_ADMIN: ROLE_ADMIN

    providers:
        fos_userbundle:
            id: fos_user.user_provider.username

    firewalls:
        main:
            pattern: ^/
            form_login:
                provider: fos_userbundle
                csrf_token_generator: security.csrf.token_manager
                # if you are using Symfony < 2.8, use the following config instead:
                # csrf_provider: form.csrf_provider

            logout:       true
            anonymous:    true

    access_control:
        - { path: ^/login$, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/register, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/resetting, role: IS_AUTHENTICATED_ANONYMOUSLY }
        - { path: ^/admin/, role: ROLE_ADMIN }

Under the providers section, you are making the bundle's packaged user provider service available via the alias fos_userbundle. The id of the bundle's user provider service is fos_user.user_provider.username.

Next, take a look at and examine the firewalls section. Here we have declared a firewall named main. By specifying form_login, you have told the Symfony Framework that any time a request is made to this firewall that leads to the user needing to authenticate himself, the user will be redirected to a form where he will be able to enter his credentials. It should come as no surprise then that you have specified the user provider service we declared earlier as the provider for the firewall to use as part of the authentication process.

The access_control section is where you specify the credentials necessary for users trying to access specific parts of your application. The bundle requires that the login form and all the routes used to create a user and reset the password be available to unauthenticated users but use the same firewall as the pages you want to secure with the bundle. This is why you have specified that any request matching the /login pattern or starting with /register or /resetting have been made available to anonymous users. You have also specified that any request beginning with /admin will require a user to have the ROLE_ADMIN role.

For more information on configuring the security.yml file please read the Symfony security component documentation.

Step 5: Configure the FOSUserBundle¶

Now that you have properly configured your application's security.yml to work with the FOSUserBundle, the next step is to configure the bundle to work with the specific needs of your application.

Add the following configuration to your config.yml file according to which type of datastore you are using.

Only three configuration values are required to use the bundle:

• The type of datastore you are using (orm, mongodb, couchdb or propel).
• The firewall name which you configured in Step 4.
• The fully qualified class name (FQCN) of the User class which you created in Step 3.

Step 6: Import FOSUserBundle routing files¶

Now that you have activated and configured the bundle, all that is left to do is import the FOSUserBundle routing files.

By importing the routing files you will have ready made pages for things such as logging in, creating users, etc.

Step 7: Update your database schema¶

Now that the bundle is configured, the last thing you need to do is update your database schema because you have added a new entity, the User class which you created in Step 4.

For ORM run the following command.

1

$ php bin/console doctrine:schema:update --force

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

1

$ php bin/console doctrine:mongodb:schema:create --index

For Propel 1 users you have to install the TypehintableBehavior before to build your model. First, install it:

1

$ composer require willdurand/propel-typehintable-behavior

You now can run the following command to create the model:

1

$ php bin/console propel:build

You now can log in at http://app.com/app_dev.php/login!

Next Steps¶

Now that you have completed the basic installation and configuration of the FOSUserBundle, you are ready to learn about more advanced features and usages of the bundle.

The following documents are available: