Symfony框架之FOSUserBundle入门教程

发表于 | 分类于

原文地址: http://symfony.com/doc/current/bundles/FOSUserBundle/index.html

Symfony的安全组件为你提供了一个灵活的框架, 它允许你从配置文件, 数据库, 或者其他任何你想象的到的地方来加载用户. FOSUserBundle则建立在此基础上, 更方便快速的将用户信息存储到数据库之中.

准备工作
1.3.x版本的FOSUserBundle依赖于Symfony2.1+. 如果你使用的是Symfony2.0.x, 请使用1.2.x系列的版本.

翻译
如果你要使用此bundle提供的默认文本, 你必须保证你的配置文件中已经开启了翻译功能.

1
2
3
4
# app/config/config.yml

framework:
    translator: ~

更多关于翻译的信息, 请点击Symfonydocumentation

安装
整个安装过程有7个步骤:

  1. 使用composer下载FOSUserBundle
  2. 启用Bundle
  3. 创建你的User类
  4. 配置应用中的security.yml文件
  5. 配置FOSUserBundle
  6. 导入FOSUserBundle的路由文件
  7. 更新数据库的Schema

步骤1:使用Composer下载FOSUserBundle

使用composer安装bundle:

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

Composer会将bundle安装到你项目中的vendor/friendsofsymfony/user-bundle文件夹内.
如果你遇到了缺少配置参数的错误, 例如 The child node "db_driver" at path "fos_user" must be configured, 你应该先完成步骤5, 然后再重新执行这一步.

步骤2: 启用Bundle

在kernel中启用此bundle:

1
2
3
4
5
6
7
8
9
10
11
<?php
// app/AppKernel.php

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

步骤3:创建你的用户类

FOSUserBundle自始至终是使用一些User类来操作数据库的 (MySql, MongoDB, CouchDB, 等等). 你首先应该为你的应用创建一个User类.这个类可以包含任何你觉得有用的方法和属性. 因为这是你的User类.
FOSUserBundle提供了一些已经映射了大多数字段的基类, 这个类能让你更简单的创建entity. 你可以这么使用:

  1. 继承User的基类.
  2. 映射id字段. 它必须被设为protected, 因为在父类中他已经被定义过了.

当你继承了FOSUserBundle提供的已经做过映射的超类时, 不要定义其他已经定义好的映射.

接下来你将看到根据你存储方式的不同如何来定义你的User类(Doctrine ORM, MongoDB ODM, 或 CouchDB ODM).

如果在你的 User 类中重写了__construct()方法, 请务必执行 parent::__construct(), 因为User基类通过这个方法初始化了一些字段.

a)Doctrine ORM User class

如果你通过Doctrine ORM来管理用户, 你的User类应该存在Entity命名空间之内, 就像这样.

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
<?php
// src/AppBundle/Entity/User.php

namespace AppBundle\Entity;

use FOS\UserBundle\Model\User as BaseUser;
use Doctrine\ORM\Mapping as ORM;

/**
 * @ORM\Entity
 * @ORM\Table(name="fos_user")
 */
class User extends BaseUser
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

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

user在标准SQL中是一个保留字, 如果你需要使用这个保留字, 那就要用反引号把它包围起来.就像这样 @ORM\Table(name=”`user`“)

b)MongoDB User class

假如你使用 Doctrine MongoDB ODM来操作你的用户, 那你的User类应该在你的bundle中的Document命名空间之内, 就像下面这样:

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
    }
}

c) CouchDB User class
如果你通过Doctrine CouchDB ODM来错做用户, 你的User类应该在CouchDocument命名空间中, 就像这样:

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
    }
}

步骤4:配置应用中的security.yml文件

为了让Symfony的安全组件能够使用FOSUserBundle, 你需要配置security.yml文件. security.yml包含了应用安全组件的基本配置.
下面是能够使用FOSUserBundle的必须配置.

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 }

在providers部分, 你通过fos_userbundle别名来使用FOSUserBundle中可用的的用户服务提供者.它的id是fos_user.user_provider.username.

下面我们来看firewalls部分. 这里我们申明了一个防火墙名为main. 通过指定form_login, 你需要告诉Symfony框架在任何时候的请求发送到这个防火墙时
都将引导用户进行认证, 不然用户将被重定向到一个表单页来输入他的凭证.

在access_control部分你可以指定用户在访问你应用中特殊的地址时所需要的凭证.bundle指定未认证用户能够在登录表单以及所有的路由中创建用户和重置密码.
这就是为什么你指定任何请求去匹配/login或者以/register 和 /resetting开头的地址时,将用户类型指定为匿名用户了.你肯定也注意到了, 任何以/admin开头的请求地址都需要用户为ROLE_ADMIN的身份.

更多关于security.yml文件的配置, 请查阅Symfony安全组件文档

请注意我们在防火墙中配置的名称main, 你将在下一个步骤中使用它来配置FOSUserBundle.

步骤5:配置FOSUserBundle

现在我们配置的security.yml已经能够让FOSUserBundle正确的运行了, 接下来我们来为应用配置一些特定的需求.
根据你使用的数据库类型, 添加下面的配置信息到你的config.yml文件中.

1
2
3
4
5
# app/config/config.yml
fos_user:
    db_driver: orm # other valid values are 'mongodb', 'couchdb' and 'propel'
    firewall_name: main
    user_class: AppBundle\Entity\User

仅需配置三个必须的配置项:

  • 你使用的数据库类型.(orm, mongodb, couchdb)
  • 你在步骤4中配置的防火墙名字.
  • 在步骤3中创建的User类的全路径名.

步骤6:导入FOSUserBundle的路由文件

现在你已经配置并且启用了整个bundle, 剩下的就是要导入所有的FOSUserBundle路由文件.
通过导入路由文件, 你将会生成一些现成的页面, 比如登录, 创建用户等等.

1
2
3
# app/config/routing.yml
fos_user:
    resource: "@FOSUserBundle/Resources/config/routing/all.xml"

为了正常的使用内部的邮件功能(用于用户激活以及重置密码功能), 你必须配置并且启用了SwiftmailerBundle

步骤7:更新数据库的Schema

至此, 整个bundle已经配置完毕, 因为在步骤4中你创建了User类并且添加了新的entity, 所以现在你要做的就是更新你的数据库Schema.
如果使用ORM,请执行下面命令.

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

若使用的是MongoDB, 你则需要执行下面命令来创建索引.

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

现在你可以在http://app.com/app_dev.php/login地址中登录了.

下一步
现在你已经完成了FOSUserBundle的基本安装与配置, 可以了解一些更高级的特性.
比如下面这些可用的文档:
重写FOSUserBundle的默认模板
挂载到控制器
重写FOSUserBundle的默认控制器
重写FOSUserBundle的默认表单
关于FOSUserBundle的用户管理服务
FOSUserBundle命令行管理工具
FOSUserBundle之使用用户名或密码登录
FOSUserBundle用户名表单字段
FOSUserBundle的邮件服务
使用FOSUserBundle进行分组(待翻译)