The doctrineuserbundle from dunglas

Provides authentication and User persistence for your Symfony2 Project.

Features

Compatible with Doctrine ORM and ODM thanks to a generic repository.
Model is extensible at will
RESTful authentication
Current user available in your controllers and views
Unit tested and functionaly tested

Installation

Add DoctrineUserBundle to your src/Bundle dir

git submodule add git://github.com/knplabs/DoctrineUserBundle.git src/Bundle/DoctrineUserBundle

Add DoctrineUserBundle to your application kernel

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Bundle\DoctrineUserBundle\DoctrineUserBundle(),
        // ...
    );
}

Create your own user class

You must create a User class that extends the default one. Then you will be able to add logic and mapping in it.

ORM User class:

// src/Application/MyBundle/Entity/User.php

namespace Application\DoctrineUserBundle\Entity;
use Bundle\DoctrineUserBundle\Entity\User as BaseUser;

class User extends BaseUser {}

MongoDB User class:

// src/Application/MyBundle/Document/User.php

namespace Application\DoctrineUserBundle\Document;
use Bundle\DoctrineUserBundle\Document\User as BaseUser;

class User extends BaseUser {}

Choose ORM or ODM database driver

# app/config/config.yml
doctrine_user.config:
    db_driver: orm # can be orm or odm
    user_class: Application\DoctrineUserBundle\Entity\User # you must define your own user class

or if you prefer xml

# app/config/config.xml
<doctrine_user:config db_driver="orm" user_class="DoctrineUserBundle" />

Add authentication routes

If you want ready to use login and logout pages, include the builtin routes:

# app/config/routing.xml
<import resource="DoctrineUserBundle/Resources/config/routing/session.xml"/>

You now can login at http://app.com/session/new

Command line

DoctrineUserBundle provides command line utilities to help manage your application users.

Create user

This command creates a new user

php app/console doctrine:user:create username email password

If you don't provide the required arguments, a interactive prompt will ask them to you

php app/console doctrine:user:create

Promote user as a super administrator

This command promotes a user as a super administrator

php app/console doctrine:user:promote

Get the current authenticated user in your code

From controllers

$this['doctrine_user.auth']->getUser() // return a User instance, or null

$this['doctrine_user.auth']->isAuthenticated() // return true if a user is authenticated

From templates

PHP templates

$view['auth']->getUser() // return a User instance, or null

$view['auth']->isAuthenticated() // return true if a user is authenticated

Twig templates

{% _view.auth.user %} // get a User instance, or null

{% _view.auth.isAuthenticated %} // get true if a user is authenticated

Customize authentication urls

Instead of including built-in routes, you can define them in your application routing. For example, to get more traditional "login" and "logout" urls, write:

# app/config/routing.yml
doctrine_user_session_new:
    pattern:        /login
    defaults:       { _controller: DoctrineUserBundle:Session:new }
    requirements:   { _method: "GET" }

doctrine_user_session_create:
    pattern:        /login
    defaults:       { _controller: DoctrineUserBundle:Session:create }
    requirements:   { _method: "POST" }

doctrine_user_session_delete:
    pattern:        /logout
    defaults:       { _controller: DoctrineUserBundle:Session:delete }
    requirements:   { _method: "GET" }

doctrine_user_session_success:
    pattern:        /welcome
    defaults:       { _controller: DoctrineUserBundle:Session:success }
    requirements:   { _method: "GET" }

using xml

# app/config/routing.xml
<route id="doctrine_user_session_new" pattern="/login">
    <default key="_controller">DoctrineUserBundle:Session:new</default>
    <requirement key="_method">GET</requirement>
</route>

<route id="doctrine_user_session_create" pattern="/login">
    <default key="_controller">DoctrineUserBundle:Session:create</default>
    <requirement key="_method">POST</requirement>
</route>

<route id="doctrine_user_session_delete" pattern="/logout">
    <default key="_controller">DoctrineUserBundle:Session:delete</default>
     <requirement key="_method">GET</requirement>

<route id="doctrine_user_session_success" pattern="/welcome">
    <default key="_controller">DoctrineUserBundle:Session:success</default>
     <requirement key="_method">GET</requirement>

Change the route used when user successfully logs in

By default, when a user logs in through SessionController::create, he gets redirected to the route doctrine_user_session_success. You can change the route used in configuration:

# app/config/config.yml
doctrine_user.config:
    db_driver: orm # can be orm or odm
    session_create_success_route: my_custom_route_name

with xml

# app/config/config.xml
<doctrine_user:config
    db_driver="orm"
    session_create_success_route="my_custom_route_name"
/>

User repository service

DoctrineUserBundle works with both ORM and ODM. To make it possible, the user repository is a service of the container. If you configure the db_driver to orm, this service is an instance of Bundle\DoctrineUserBundle\Entity\UserRepository. If you configure the db_driver to odm, this service is an instance of Bundle\DoctrineUserBundle\Document\UserRepository. Both these classes implement Bundle\DoctrineUserBundle\Model\UserRepositoryInterface.

Access the repository service

If you want to manipulate users in a way that will work as well with ORM and ODM, use the doctrine_user.user_repository service:

$userRepository = $container->get('doctrine_user.user_repository');

That's the way DoctrineUserBundle internal controllers are built.

Access the current user class

When using Doctrine ORM, the default user class is Bundle\DoctrineUserBundle\Entity\User. When using Doctrine ODM, the default user class is Bundle\DoctrineUserBundle\Document\User. To get the current user class, you can ask it to the user repository:

$userClass = $userRepository->getObjectClass();
$user = new $userClass();

$user is now an Entity or a Document, depending on the configuration.

Extend the User

You will probably want to extend the user to add it new properties and methods. You can change the User class DoctrineUserBundle will use in configuration:

# app/config/config.yml
doctrine_user.config:
    db_driver: orm
    user_class: Bundle\MyBundle\Entity\User

with xml

# app/config/config.xml
<doctrine_user:config
    db_driver="orm"
    user_class="Bundle\MyBundle\Entity\User"
/>

Then create your own User class:

# Bundle\MyBundle\Document\User.php
<?php
namespace Bundle\MyBundle\Entity;
use Bundle\DoctrineUserBundle\Entity\User as BaseUser;

class User extends BaseUser
{
    // add your stuff here
}

Once you extended the User class, you can easily replace and extend the User repository, too. Declare your custom repository from your User class annotations:

/**
* @Entity(repositoryClass="Bundle\MyBundle\Entity\UserRepository")
*/
class User extends BaseUser
{
}

Then create your custom repository:

# Bundle\MyBundle\Document\UserRepository.php
<?php
namespace Bundle\MyBundle\Entity;
use Bundle\DoctrineUserBundle\Entity\UserRepository as BaseUserRepository

class UserRepository extends BaseUserRepository
{
    // add your stuff here
}

Of course, to do the same with Doctrine ODM, just replace Entity with Document in the previous exemples.

Configuration example:

All configuration options are listed below:

db_driver: odm
class:
    model:
        user: Bundle\ExerciseUserBundle\Document\User
        group: ~
        permission: ~
    form:
        user: ~
        group: ~
        permission: ~
        session: ~
        change_password: ~
    controller:
        user: ~
        group: ~
        permission: ~
        session: ~
auth:
    class: ~
    session_path: ~
remember_me:
    cookie_name: ~
    lifetime: ~
form_name:
    user: ~
    group: ~
    permission: ~
    session: ~
    change_password: ~
confirmation_email:
    enabled: ~
    from_email: ~
    template: ~
session_create_success_route: ~
template:
    renderer: ~
    theme: ~

CREDITS

Non-exhaustive list of developers who contributed:

Thibault Duplessis
Matthieu Bontemps
Gordon Franke
Henrik Bjornskov
David Ashwood
Antoine Hérault

dunglas / doctrineuserbundle Goto Github PK

doctrineuserbundle's Introduction