Skip to content

9. 分层架构与数据访问

前面的示例把数据存储在内存或缓存中。真实的应用程序会把数据存储在数据库中,并按层来组织(参见引言中的示意图):

  • Web 层(控制器、表单、视图):读取请求,调用业务层,选择视图;
  • 业务层:业务规则;
  • DAO 层(Data Access Object):数据库查询。

每一层只了解它下面的那一层,并且尽可能少地了解其细节:Web 层不了解 SQL,业务层不了解 HTML。这种分离使每一层更易于理解、测试和演进。示例 28 把这种做法应用到人员列表的管理上:这是案例研究中医生和客户管理的缩小版。

在 [PHP] 中,数据库访问分为几个层次:

  • PDO 扩展(PHP Data Objects)属于 [PHP] ,它为所有 DBMS 扩展定义了一个通用接口:打开连接、执行 SQL 命令以及读取行。每个 DBMS 都有自己的驱动:[pdo_mysql] 用于 [MySQL] (以及 [MariaDB]),随 [PHP] 一起提供;
  • DBAL 框架 (Database Abstraction Layer)增加了连接和事务管理、查询构建器、类型转换,并把各个 DBMS 的错误转换为通用异常(无论使用哪种 DBMS,违反唯一性约束都会变成 [UniqueConstraintViolationException]);
  • Doctrine ORM (Object-Relational Mapper)把类(实体)映射到数据库表,并把检索到的行转换为对象。它遵循所谓的数据映射器(Data Mapper)模型:实体是对数据库一无所知的普通对象;由一个独立的对象,即实体管理器,来读取和保存它们。这就是它与 [Eloquent] ORM(源自 [Laravel])的区别,后者遵循活动记录(Active Record)模型(每个对象都知道如何读取和保存自己,[$person->save()])。

[Doctrine] 不属于 [Symfony]:它是一个独立的项目,但 ORM 是 [Symfony] 推荐的,而 DoctrineBundle 把它集成到应用程序中。它相当于 [JDBC]、[JPA] 和 [Hibernate] 在 [Java] 中的角色([Doctrine] 就是以它为基础的),相当于 [Entity Framework Core] 在 [C#] 中的角色,或 [SQLAlchemy] 在 [Python] 中的角色。请注意 [PHP] 工作方式带来的一个后果:由于任何东西都不会在请求之后留存,每个请求都会打开自己的数据库连接(在第一次执行 SQL 请求时),并在结束时关闭它。这里没有像 连接池 那样存在于 [Java] 或 [Python] 中的机制;在同一台机器上打开到 [MySQL] 的连接只需不到一毫秒。

该示例需要一个正在运行的 [MySQL] (或 [MariaDB])服务器:附录说明了如何使用 [Laragon] 安装一个。

9.1. 示例 28:三层人员管理系统

28-layers/
├── .env
├── config/
│   ├── bundles.php
│   └── packages/
│       ├── doctrine.yaml
│       ├── framework.yaml
│       └── twig.yaml
├── database/
│   └── dbpersons.sql
├── public/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── src/
│   ├── Controller/
│   │   └── PersonsController.php
│   ├── Dao/
│   │   └── PersonsDao.php
│   ├── Entity/
│   │   └── Person.php
│   ├── Form/
│   │   ├── PersonInput.php
│   │   └── PersonType.php
│   └── Business/
│       ├── PersonData.php
│       ├── BusinessException.php
│       └── PersonsBusiness.php
├── templates/
│   ├── fragments/
│   │   └── confirmation.html.twig
│   ├── layout.html.twig
│   └── persons/
│       ├── form.html.twig
│       └── list.html.twig
└── ...

9.1.1. 数据库

[dbpersons] 数据库由 SQL 脚本创建。使用 [Laragon] 时,你可以运行它,例如在 [HeidiSQL] 工具中(“文件”菜单 / 运行 SQL 文件),或者在示例文件夹中通过命令行运行:

mysql -u root < database/dbpersons.sql

[database/dbpersons.sql] 文件:

-- database of example 28: a single table, [persons]
-- the script is written in UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- the version of the row, increased at each modification (see DAO layer)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- two persons cannot have the same first and last names
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • 第 3 行:脚本以 [UTF-8] 编写;这一点会告知服务器,以便数据中的重音符号([Pélissier])保持完好;
  • 第 5 行:字符集 [utf8mb4] 接受所有字符(重音符号、表情符号等)。排序规则 [utf8mb4_unicode_ci] 在比较字符串时不区分大小写和重音:对于 [MySQL],[pelissier], 和 [Pélissier] 是相等的;
  • 第 11 行:版本号,每次修改该行时递增(见下文“乐观锁”);
  • 第 17 行:一个具名的唯一性约束:数据库不允许存在名和姓都相同的两个人。

[Doctrine] 也可以根据实体自行创建表(命令 [bin/console doctrine:schema:create]),或通过迁移:[PHP] 类,逐步描述每张表的创建和修改(库 [DoctrineMigrationsBundle],命令 [bin/console doctrine:migrations:migrate])。我们维护一个 SQL 脚本,它为案例研究的所有版本所共用,并准确显示了数据库的内容。

9.1.2. 配置

DoctrineBundle 被添加到 Bundle 列表中:

1
2
3
4
5
6
7
8
<?php
// config/bundles.php:应用程序的 Bundle;DoctrineBundle 集成了
// Doctrine(DBAL 和 ORM),即数据库访问库
return [
    Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
    Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
    Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];

数据库连接通过一个 URL 描述在文件 [.env] 中:

1
2
3
4
5
6
# .env:示例 28 的配置(见示例 01)
APP_ENV=dev
APP_SECRET=fe7d5dd3bafdb5b7ffcab097dd4e1c0c
# 数据库连接:MySQL 数据库管理系统,位于本机(127.0.0.1),端口 3306,
# 数据库 dbpersons,root 用户,无密码(Laragon 的设置)
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbpersons?serverVersion=8.0.32&charset=utf8mb4"

URL [DATABASE_URL] 汇集了所有连接参数:DBMS([mysql])、用户名和密码([root],[:] 后面没有内容)、主机和端口,最后是数据库名。如果你的服务器设置了密码,请把它填在 [:] 之后([root:secret@...])。[?] 之后跟着两个参数:[serverVersion],即服务器版本([Doctrine] 会针对每个版本调整它生成的 SQL;例如,对于 [MariaDB],我们会写成 [serverVersion=10.11.2-MariaDB]),以及 [charset],即与服务器通信所用的字符集,它与数据库的字符集一致。DoctrineBundle 的配置:

# config/packages/doctrine.yaml:DoctrineBundle 的配置
doctrine:
    # DBAL:数据库连接,由 URL 描述(.env 文件)
    dbal:
        url: '%env(resolve:DATABASE_URL)%'
        # 在调试模式下,SQL 语句会写入日志(控制台)
        logging: '%kernel.debug%'
    # ORM:实体(ENTITIES),即与表关联的类,是
    # src/Entity 文件夹中的类;它们到表的映射由 PHP 属性描述
    orm:
        mappings:
            App:
                type: attribute
                dir: '%kernel.project_dir%/src/Entity'
                prefix: 'App\Entity'
  • 第 5 行:连接。前缀 [resolve:] 会替换变量值中对其他参数的所有引用([%...%])(如果存在的话);
  • 第 7 行:在调试模式下,每条 SQL 命令都会写入日志,我们可以在控制台中查看(示例 24)。这也是默认设置;
  • 第 10–15 行:实体是 [src/Entity] 文件夹中的类,其命名空间以 [App\Entity] 开头;它们与表的映射由 [PHP] 属性描述。

其他配置文件与示例 21 中的相同:会话、防 CSRF 保护,以及 PUT 和 DELETE 方法([framework.yaml]),还有表单主题 [Bootstrap]([twig.yaml])。没有其他需要配置的内容:三个层的类由 [Symfony] 容器创建,容器会把下一层注入到每个类中(控制器接收业务层,业务层接收 DAO 层),而 DoctrineBundle 会把实体管理器([EntityManagerInterface])注册到容器中。

9.1.3. Person 实体

<?php
// src/Entity/Person.php:[persons] 表的一行,一个 Doctrine 实体(ENTITY)

namespace App\Entity;

use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;

// #[ORM\Entity]:该类是一个实体;#[ORM\Table]:其对应的表
#[ORM\Entity]
#[ORM\Table(name: 'persons')]
class Person
{
    // 主键,由数据库生成(AUTO_INCREMENT);插入之前为 null
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    // 该行的版本(VERSION):Doctrine 在每次修改时都会增加它,并且只有
    // 在其版本自读取以来没有变化时才修改该行(乐观
    // 锁);列的类型必须显式给出
    #[ORM\Version]
    #[ORM\Column(type: Types::INTEGER)]
    private int $version = 0;

    // 列:其 SQL 类型由 PHP 类型推断(string:VARCHAR)
    #[ORM\Column(name: 'first_name', length: 30)]
    private string $firstName;

    #[ORM\Column(name: 'last_name', length: 30)]
    private string $lastName;

    #[ORM\Column]
    private int $age;

    public function __construct(string $firstName, string $lastName, int $age)
    {
        $this->edit($firstName, $lastName, $age);
    }

    public function edit(string $firstName, string $lastName, int $age): void
    {
        $this->firstName = $firstName;
        $this->lastName = $lastName;
        $this->age = $age;
    }

    public function getId(): ?int
    {
        return $this->id;
    }

    public function getVersion(): int
    {
        return $this->version;
    }

    public function getFirstName(): string
    {
        return $this->firstName;
    }

    public function getLastName(): string
    {
        return $this->lastName;
    }

    public function getAge(): int
    {
        return $this->age;
    }
}
  • 第 10–11 行:属性 [#[ORM\Entity]] 把该类指定为一个实体;[#[ORM\Table]] 指定其表的名称(否则,[Doctrine] 会采用类名 [person])。[ORM] 是命名空间 [Doctrine\ORM\Mapping] 的别名(第 7 行):[use ... as ORM] 使得属性可以用简写形式书写;
  • 第 15–18 行:主键([#[ORM\Id]]),由数据库生成([#[ORM\GeneratedValue]]:源自 [AUTO_INCREMENT],而后者源自 [MySQL])。在实体被插入之前,它是 [null] ;
  • 第 23–25 行:行版本。[#[ORM\Version]] 属性为 [Doctrine] 提供乐观锁,详见下文;
  • 第 28–35 行:列。每个标有 [#[ORM\Column]] 的属性对应同名的列;其 SQL 类型由 [PHP] 类型推导而来([string]:[VARCHAR],长度为 [length];[int]:[INT])。与 [Eloquent] 不同,这里的列是显式声明的:类准确指明了表中包含的内容;
  • 第 37–72 行:该实体是一个普通的类:一个构造函数、一个修改人员信息的方法,以及若干访问器。属性是私有的:只能通过方法来修改人员信息。另一方面,[Doctrine] 直接读写这些属性(通过反射),不经过构造函数或方法。

在标准项目中,来自 [bin/console make:entity] 的命令 [MakerBundle] 会写出实体,并就其属性提出几个问题。

9.1.4. DAO 层

<?php
// src/Dao/PersonsDao.php:DAO 层,查询,不含业务规则

namespace App\Dao;

use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;

class PersonsDao
{
    // Doctrine 的实体管理器(ENTITY MANAGER):它读取和写入实体
    public function __construct(private EntityManagerInterface $em)
    {
    }

    // SELECT ... FROM persons ORDER BY last_name, first_name
    /** @return list<Person> */
    public function list(): array
    {
        return $this->em->getRepository(Person::class)->findBy([], ['lastName' => 'ASC', 'firstName' => 'ASC']);
    }

    // SELECT ... FROM persons WHERE id = ?;如果该人员不存在则为 null
    public function read(int $id): ?Person
    {
        return $this->em->find(Person::class, $id);
    }

    // 名和姓相同的人员([$exceptId] 除外),用 DQL 编写,
    // 即 Doctrine 的查询语言:它谈论的是实体和属性,而不是
    // 表和列
    public function namesake(string $firstName, string $lastName, int $exceptId = 0): ?Person
    {
        return $this->em->createQuery(
            'SELECT p FROM App\Entity\Person p WHERE p.firstName = :firstName AND p.lastName = :lastName AND p.id <> :id')
            ->setParameters(['firstName' => $firstName, 'lastName' => $lastName, 'id' => $exceptId])
            ->setMaxResults(1)
            ->getOneOrNullResult();
    }

    // INSERT(新实体)或 UPDATE(读取后被修改的实体):persist 将
    // 实体交给管理器,flush 将必要的 SQL 语句发送到数据库
    public function save(Person $person): void
    {
        $this->em->persist($person);
        $this->em->flush();
    }

    // DELETE FROM persons WHERE id = ?
    public function delete(Person $person): void
    {
        $this->em->remove($person);
        $this->em->flush();
    }
}

DAO 层只包含查询,不含业务逻辑。它接收实体管理器(第 12 行),该管理器使用当前查询的连接,并参与由业务层发起的已打开的事务(如果有的话)。

  • 第 18–21 行:每个实体都有一个仓库 (repository),即从数据库中检索它的对象:[getRepository]。其方法 [findBy(criteria, orderBy)] 按所要求的顺序返回符合条件的实体列表(在本例中没有条件:返回全部)。(仓库还有 [findAll]、[findOneBy]、[count] 等;应用程序可以编写自己的仓库类,包含自己的查询:这正是 [make:entity] 所生成的。);
  • 第 24–27 行:[find]:按主键检索,或返回 [null];
  • 第 32–39 行:用 DQL (Doctrine Query Language)编写的查询,这是 [Doctrine] 的查询语言。它类似于 SQL,但引用的是实体和属性([App\Entity\Person p], [p.firstName]),[Doctrine] 会把它们转换为表和列。值使用具名参数 ([:firstName]),由 [setParameters] 提供:它们与 SQL 命令的文本分开传送给数据库,绝不会被复制到 SQL 命令的文本中,这就使得 SQL 注入不可能发生。[setMaxResults(1)] 把结果限制为一行([LIMIT 1]);[getOneOrNullResult] 返回找到的实体,或 [null];
  • 第 43–47 行:保存。[persist] 把新实体交给管理器管理(由管理器读取的实体已经归它管理);[flush] 把所有必要的 SQL 命令发送到数据库:对新实体执行 [INSERT] ,对读取后被修改的实体执行只包含被修改列的 [UPDATE] 。管理器会把它读取的每个实体与其原始状态进行比较:这就是变更跟踪。在执行 [INSERT] 之后,[Doctrine] 会把数据库生成的 ID 存储到实体中;
  • 第 50–54 行:删除:[remove],随后是 [flush],由它触发 [DELETE]。

9.1.5. 业务层

<?php
// src/Business/PersonData.php:一个人员的数据,由 Web 层传递过来

namespace App\Business;

readonly class PersonData
{
    public function __construct(
        public string $firstName,
        public string $lastName,
        public int $age,
    ) {
    }
}

一个人员的数据,由 Web 层传递给业务层:一个与 [Symfony] 无关的简单对象。

<?php
// src/Business/BusinessException.php:业务规则拒绝该操作;其
// 消息是给用户看的

namespace App\Business;

use RuntimeException;

class BusinessException extends RuntimeException
{
}

业务层专用的异常类:某条业务规则拒绝了该操作,异常消息是给用户看的。它继承自 [RuntimeException] ,没有添加任何内容——只有它的名称才重要。

<?php
// src/Business/PersonsBusiness.php:业务层,只包含业务规则。
// 每个写入操作都是一个事务:如果函数正常结束则提交(COMMIT),
// 如果函数抛出异常则回滚(ROLLBACK)

namespace App\Business;

use App\Dao\PersonsDao;
use App\Entity\Person;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;

class PersonsBusiness
{
    private const NAMESAKE = 'A person already has these first and last names.';

    private const MODIFIED = 'This record has been modified meanwhile: reload it.';

    private const UNKNOWN = 'This person does not exist (anymore).';

    public function __construct(private PersonsDao $dao, private EntityManagerInterface $em)
    {
    }

    /** @return list<Person> */
    public function list(): array
    {
        return $this->dao->list();
    }

    public function read(int $id): Person
    {
        return $this->dao->read($id) ?? throw new BusinessException(self::UNKNOWN);
    }

    public function add(PersonData $data): Person
    {
        // wrapInTransaction:函数在事务中执行
        return $this->transaction(function () use ($data) {
            // 规则 1:不允许两个人员的名和姓都相同
            if ($this->dao->namesake($data->firstName, $data->lastName)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person = new Person($data->firstName, $data->lastName, $data->age);
            $this->dao->save($person);
            return $person;
        });
    }

    public function edit(int $id, int $version, PersonData $data): Person
    {
        return $this->transaction(function () use ($id, $version, $data) {
            $person = $this->read($id);
            // 规则 2:不修改在此期间已被他人修改的记录
            if ($person->getVersion() !== $version) {
                throw new BusinessException(self::MODIFIED);
            }
            if ($this->dao->namesake($data->firstName, $data->lastName, $id)) {
                throw new BusinessException(self::NAMESAKE);
            }
            $person->edit($data->firstName, $data->lastName, $data->age);
            // 如果没有修改任何行,Doctrine 的 UPDATE "WHERE id = ... AND version = ..." 会引发
            // OptimisticLockException(见事务)
            $this->dao->save($person);
            return $person;
        });
    }

    public function delete(int $id): Person
    {
        return $this->transaction(function () use ($id) {
            $person = $this->read($id);
            $this->dao->delete($person);
            return $person;
        });
    }

    // [$operation] 函数,在事务中执行。数据库的两种错误
    // 属于业务错误:唯一性约束(两次同时添加),
    // 以及乐观锁(两次同时编辑)
    private function transaction(callable $operation): Person
    {
        try {
            return $this->em->wrapInTransaction($operation);
        } catch (UniqueConstraintViolationException $e) {
            throw new BusinessException(self::NAMESAKE, previous: $e);
        } catch (OptimisticLockException $e) {
            throw new BusinessException(self::MODIFIED, previous: $e);
        }
    }
}
  • 第 16–20 行:业务规则消息;
  • 第 32–35 行:不存在的人员属于业务错误。运算符 [??] 在右侧接受一个表达式 [throw]:如果人员为 [null],就抛出异常;
  • 第 37–49 行:规则 1:任何两个人的名和姓不得完全相同。该规则在写入数据库之前检查,如果不满足,就会抛出 [BusinessException] 异常 。但这个检查并不充分:两个同时到达的请求可能都验证到没有重名者,然后都继续执行插入。此时,数据库的唯一性约束会拒绝第二个 [INSERT],而 [Doctrine] 会触发 [UniqueConstraintViolationException],[transaction] 方法会把它转换为同样的 [BusinessException]。数据库是最后一道防线;
  • 第 51–68 行:规则 2:不要修改在此期间已被他人修改过的记录。更新表单会携带所读取记录的版本(在隐藏字段中);如果它与当前版本不同,就说明该记录在显示之后已被更改。还有一种情况是并发修改发生在第 54 行的读取与第 65 行的保存之间:这由 [Doctrine] 中的乐观锁检测到。对于带有版本的实体,[UPDATE] 会检查两个条件——ID 和所读取的版本——并把版本加 1;如果在此期间另一个查询修改了该行——其版本已发生变化——该 [UPDATE] 锁不会修改任何行,于是 [Doctrine] 会抛出 [OptimisticLockException] 异常。这就是乐观锁的原理:不阻塞任何操作,但会检测并发修改。([Doctrine] 自行完成这一工作,[Hibernate] 和 [SQLAlchemy] 也是如此;本课程的 [Laravel] 版本则必须手工编写这个条件。);
  • 第 70–77 行:删除操作会把该人员标记为已删除,以便生成确认消息;
  • 第 82–91 行:每个写入数据的操作都在一个事务中执行:[wrapInTransaction] 打开事务,执行函数,提交待处理的更改([flush]),然后提交事务([COMMIT])并返回函数的值;如果函数抛出异常,事务会被回滚([ROLLBACK]):在函数内所做的所有更改都不会保留,异常会继续向上传播。因此,业务层决定了事务的范围:一个业务操作,一个事务。属于业务错误的两种数据库错误会变成 [BusinessException];名为 [previous] 的参数会把原始异常附加到新异常上,以便记录日志。其他错误则原样抛出:它不是业务错误,而是编程错误(或系统故障)。出现异常后,[Doctrine] 会关闭实体管理器,因为其状态已不可靠:在该请求期间不能再使用它,这里并不成问题,因为请求即将结束。

方法 [callable] 的参数 [transaction] 可以指向任意函数;第 40、53 和 72 行的匿名函数通过 [use] 捕获它们所需的变量。

9.1.6. Web 层

表单输入由一个类描述,其约束由属性描述(示例 19):

<?php
// src/Form/PersonInput.php:表单的字段及其约束(见示例 19)

namespace App\Form;

use App\Entity\Person;
use App\Business\PersonData;
use Symfony\Component\Validator\Constraints as Assert;

class PersonInput
{
    #[Assert\NotBlank(message: 'The first name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $firstName = null;

    #[Assert\NotBlank(message: 'The last name is required.')]
    #[Assert\Length(max: 30, maxMessage: '30 characters at most.')]
    public ?string $lastName = null;

    #[Assert\NotNull(message: 'The age is required.')]
    #[Assert\Range(notInRangeMessage: 'The age must be between 0 and 150.', min: 0, max: 150)]
    public ?int $age = null;

    // 记录的版本,由隐藏字段携带(仅在编辑时)
    public ?int $version = null;

    // 输入,预先填充了已有的人员
    public static function from(Person $p): self
    {
        $input = new self();
        $input->firstName = $p->getFirstName();
        $input->lastName = $p->getLastName();
        $input->age = $p->getAge();
        $input->version = $p->getVersion();
        return $input;
    }

    // 经过验证的数据,供业务层使用
    public function data(): PersonData
    {
        return new PersonData(trim($this->firstName), trim($this->lastName), $this->age);
    }
}
  • 第 12–22 行:约束,消息为英文;
  • 第 25 行:记录版本,由隐藏字段携带(仅限编辑模式);
  • 第 28–36 行:用现有人员预填的输入,用于更新表单;
  • 第 39–42 行:已验证的数据,采用业务层所期望的格式。

我们本可以把表单直接与 [Person] 实体关联起来(选项 [data_class],示例 19),并把约束放在实体上:这在 [Symfony] 中很常见。但是,这样一来,表单会在业务层验证其规则之前就修改实体,并且会把无效的实体传给实体管理器。单独的输入类可以让各层保持分离:Web 层只把已验证的数据传递给业务层。

<?php
// src/Form/PersonType.php:人员的表单(见示例 18)

namespace App\Form;

use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\IntegerType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;

class PersonType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options): void
    {
        $builder
            ->add('firstName', TextType::class, ['label' => 'First name', 'attr' => ['maxlength' => 30]])
            ->add('lastName', TextType::class, ['label' => 'Last name', 'attr' => ['maxlength' => 30]])
            ->add('age', IntegerType::class, ['label' => 'Age', 'attr' => ['min' => 0, 'max' => 150],
                'invalid_message' => 'The age must be an integer.']);
        // 版本:隐藏字段,仅出现在编辑表单中
        if ($options['edit']) {
            $builder->add('version', HiddenType::class);
        }
    }

    // 表单的选项:数据的类,以及我们自己的一个选项
    public function configureOptions(OptionsResolver $resolver): void
    {
        $resolver->setDefaults(['data_class' => PersonInput::class, 'edit' => false]);
    }
}
  • 第 20–21 行:一个整数字段;[invalid_message] 是当输入无法转换为整数时显示的消息;
  • 第 23–25 行:隐藏的版本字段,仅在更新表单中出现,取决于选项 [edit];
  • 第 29–32 行:[configureOptions] 声明表单选项及其默认值:数据类,以及一个自定义选项 [edit]。
<?php
// src/Controller/PersonsController.php:Web 层;它只知道业务层

namespace App\Controller;

use App\Form\PersonInput;
use App\Form\PersonType;
use App\Business\BusinessException;
use App\Business\PersonsBusiness;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\AccessDeniedHttpException;
use Symfony\Component\Routing\Attribute\Route;

// name:该类所有路由名称的前缀(persons_list...)
#[Route(name: 'persons_')]
class PersonsController extends AbstractController
{
    public function __construct(private PersonsBusiness $business)
    {
    }

    #[Route('/', name: 'home', methods: ['GET'])]
    public function home(): Response
    {
        return $this->redirectToRoute('persons_list');
    }

    #[Route('/persons', name: 'list', methods: ['GET'])]
    public function list(): Response
    {
        return $this->render('persons/list.html.twig', ['persons' => $this->business->list()]);
    }

    // GET:空表单;POST:发送的表单
    #[Route('/persons/add', name: 'add', methods: ['GET', 'POST'])]
    public function add(Request $request): Response
    {
        $input = new PersonInput();
        $form = $this->createForm(PersonType::class, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->add($input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been added.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                // 业务规则拒绝:表单会再次显示,带有
                // 输入内容,并在页面底部显示消息
                return $this->formPage('Add a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Add a person', $form);
    }

    // GET:编辑表单,已预先填充
    #[Route('/persons/{id<\d+>}/edit', name: 'edit_form', methods: ['GET'])]
    public function editForm(int $id): Response
    {
        try {
            $p = $this->business->read($id);
        } catch (BusinessException $e) {
            $this->addFlash('error', $e->getMessage());
            return $this->redirectToRoute('persons_list');
        }
        return $this->formPage('Edit a person', $this->editFormFor($id, PersonInput::from($p)));
    }

    // PUT:发送的编辑表单
    #[Route('/persons/{id<\d+>}', name: 'edit', methods: ['PUT'])]
    public function edit(Request $request, int $id): Response
    {
        $input = new PersonInput();
        $form = $this->editFormFor($id, $input);
        $form->handleRequest($request);
        if ($form->isSubmitted() && $form->isValid()) {
            try {
                $p = $this->business->edit($id, (int) $input->version, $input->data());
                $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been edited.");
                return $this->redirectToRoute('persons_list');
            } catch (BusinessException $e) {
                return $this->formPage('Edit a person', $form, $e->getMessage());
            }
        }
        return $this->formPage('Edit a person', $form);
    }

    #[Route('/persons/{id<\d+>}', name: 'delete', methods: ['DELETE'])]
    public function delete(Request $request, int $id): Response
    {
        if (! $this->isCsrfTokenValid("delete-person-$id", $request->request->getString('_token'))) {
            throw new AccessDeniedHttpException('invalid anti-CSRF token');
        }
        try {
            $p = $this->business->delete($id);
            $this->addFlash('success', "{$p->getFirstName()} {$p->getLastName()} has been deleted.");
        } catch (BusinessException $e) {
            // 没有要再次显示的表单:错误也会作为闪现消息传递
            $this->addFlash('error', $e->getMessage());
        }
        return $this->redirectToRoute('persons_list');
    }

    // 编辑表单:通过 PUT 方法发送到 /persons/{id} URL
    private function editFormFor(int $id, PersonInput $input): FormInterface
    {
        return $this->createForm(PersonType::class, $input, ['edit' => true,
            'method' => 'PUT', 'action' => $this->generateUrl('persons_edit', ['id' => $id])]);
    }

    private function formPage(string $title, FormInterface $form, ?string $error = null): Response
    {
        // 业务错误:422 状态码,与无效表单相同(见示例 19)
        return $this->render('persons/form.html.twig',
            ['title' => $title, 'form' => $form, 'error' => $error],
            new Response(status: $error ? 422 : 200));
    }
}
  • 第 18 行:类属性 [#[Route]] 在这里只为路由名称添加前缀:名为 [list] 的路由实际上叫作 [persons_list];
  • 第 21 行:业务层,控制器唯一了解的层;
  • 第 38–56 行:流程分为三个步骤:表单验证(输入错误,示例 19);调用业务层(业务规则);然后是 PRG 模式,并附带成功的闪现消息(示例 20)。[BusinessException] 会重新显示表单,连同输入的数据和异常消息,模板会把异常消息显示在页面底部。这样,输入错误和业务逻辑错误以相同的方式处理;
  • 第 59–69 行:编辑表单,用检索到的人员信息预填。如果该人员不存在,用户会被重定向到列表页,并显示一条错误闪现消息;
  • 第 72–88 行:更新,遵循与添加操作相同的模式;
  • 第 90–104 行:删除,由每个人员独有的 CSRF 令牌保护(示例 21)。没有需要重新显示的表单:任何错误同样通过闪现消息传达,即 [error];
  • 第 107–111 行:编辑表单使用 PUT 方法提交(选项 [method]:[form_start] 随后会添加隐藏字段 [_method],示例 21),提交到 URL [/persons/{id}](选项 [action]);
  • 第 113–119 行:表单页面。业务错误会以代码 422 返回,表示表单无效。

Web 层既不包含 SQL,也不包含任何业务规则:它把请求转换为对业务层的调用,并把结果转换为页面。

视图:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Persons</title>
  <link rel="stylesheet" href="{{ path('bootstrap', {file: 'css/bootstrap.min.css'}) }}">
  <link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {# 成功消息([success] 闪现消息):位于顶部 #}
    {% for message in app.flashes('success') %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {# 错误:位于底部;一个 [error] 闪现消息,或视图的 [error] 变量 #}
    {% for message in app.flashes('error') %}
      <div class="error-area" role="alert">{{ message }}</div>
    {% endfor %}
    {% if error is defined and error %}
      <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
  {% include 'fragments/confirmation.html.twig' %}
  <script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
  • 第 13–15 行:页面顶部的成功消息(示例 20);
  • 第 20–25 行:错误;位于页面底部:一条闪现消息(重定向之后),或视图变量 [error] (表单重新显示时)。测试 [is defined] 可避免在没有此变量的页面上出错。
{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">Persons</h1>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      {% for p in persons %}
        <tr>
          <td>{{ p.firstName }}</td>
          <td>{{ p.lastName }}</td>
          <td>{{ p.age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{{ path('persons_edit_form', {id: p.id}) }}">Edit</a>
            <form method="post" class="d-inline" action="{{ path('persons_delete', {id: p.id}) }}"
                  data-confirmation="Delete {{ p.firstName }} {{ p.lastName }}?">
              <input type="hidden" name="_method" value="DELETE">
              <input type="hidden" name="_token" value="{{ csrf_token('delete-person-' ~ p.id) }}">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  <a class="btn btn-primary" href="{{ path('persons_add') }}">Add a person</a>
{% endblock %}

该列表包含示例 21 中的链接和按钮及其确认窗口(文件 [fragments/confirmation.html.twig] 和 [public/js/app.js] 与示例 21 中的相同)。属性 [p.firstName], [p.lastName]等是通过访问器 [getFirstName()], [getLastName()]等读取的:[Twig] 会自行找到它们(示例 13)。

{% extends 'layout.html.twig' %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  {# novalidate:验证由服务器进行(见示例 19);form_start
     还会写出 PUT 表单的隐藏 _method 字段 #}
  {{ form_start(form, {attr: {novalidate: 'novalidate'}}) }}
    {{ form_widget(form) }}
    <button class="btn btn-primary" type="submit">Save</button>
    <a class="btn btn-link" href="{{ path('persons_list') }}">Cancel</a>
  {{ form_end(form) }}
{% endblock %}

一个同时用于添加和修改记录的视图。[form_widget] 渲染所有表单字段,包括隐藏的版本字段和防 CSRF 令牌。

9.1.7. 执行

人员列表:

Image

填写有误的添加表单:输入错误由 Web 层检测到。

Image

重名:输入本身正确,但业务层拒绝了这次添加。由于比较是由数据库执行的,因此它既忽略大写字母,也忽略重音:[marie pelissier] 与 [Marie Pélissier] 是重名。

Image

添加成功:

Image

为了测试规则 2,我们在两个标签页中打开同一条记录。在第一个标签页中,修改年龄并保存。在仍然显示旧版本的第二个标签页中,也修改该记录:

Image

删除操作及其确认:

Image

Image

9.1.8. SQL 命令

让我们在控制台中跟踪一次修改所产生的 SQL 命令(已去掉开发服务器的日期和行)。显示 1 号人员的修改表单:

1
2
3
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[info] Disconnecting

一次连接,一次按主键读取(其值作为参数传递——[?]),然后在请求结束时断开连接。没有事务:单独的一次读取不需要事务。[Doctrine] 为每张表([t0])和每一列([id_1])分配一个别名。参数值是一个数组,[Symfony] 的精简日志不会显示它([[array]]);[Monolog],或 [Symfony] 的调试工具栏([WebProfilerBundle],通过 [composer require --dev profiler] 安装)则会显示它们。主记录更新,使用新的年龄:

1
2
3
4
5
6
7
8
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT p0_.id AS id_0, p0_.version AS version_1, p0_.first_name AS first_name_2, p0_.last_name AS last_name_3, p0_.age AS age_4 FROM persons p0_ WHERE p0_.first_name = ? AND p0_.last_name = ? AND p0_.id <> ? LIMIT 1 (parameters: [array], types: [array])
[debug] Executing statement: SAVEPOINT DOCTRINE_2
[debug] Executing statement: UPDATE persons SET age = ?, version = version + 1 WHERE id = ? AND version = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT version FROM persons WHERE id = ? (parameters: [array], types: [array])
[debug] Executing statement: RELEASE SAVEPOINT DOCTRINE_2
[debug] Committing transaction

在单个事务中,我们可以看到:读取记录、查找重名者(DQL 查询,已转换为 SQL),然后是 [UPDATE]。该事务只修改发生变化的列([age]),递增版本号,并设置乐观锁条件([AND version = ?])。[Doctrine] 随后再次读取新版本,以便将其保存到实体中。[flush] 自己会打开一个事务;由于已经存在一个事务——业务层事务——它只是创建一个保存点 ([SAVEPOINT]),即一个嵌套事务,并在 [RELEASE] 时于 [flush] 结束时提交。现在让我们第二次提交同一个表单,仍然使用旧版本:

1
2
3
[debug] Beginning transaction
[debug] Executing statement: SELECT t0.id AS id_1, t0.version AS version_2, t0.first_name AS first_name_3, t0.last_name AS last_name_4, t0.age AS age_5 FROM persons t0 WHERE t0.id = ? (parameters: [array], types: [array])
[debug] Rolling back transaction

所读取的版本不是表单中的版本:业务层触发了 [BusinessException],它回滚了事务([ROLLBACK]),页面显示“该记录在此期间已被修改:请重新加载。”同样,添加重名者会在查找重名者之后停止,不会执行 [INSERT]。