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 列表中:
| <?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] 中:
| # .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. 执行
人员列表:

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

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

添加成功:

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

删除操作及其确认:


9.1.8. SQL 命令
让我们在控制台中跟踪一次修改所产生的 SQL 命令(已去掉开发服务器的日期和行)。显示 1 号人员的修改表单:
| [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] 安装)则会显示它们。主记录更新,使用新的年龄:
| [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] 结束时提交。现在让我们第二次提交同一个表单,仍然使用旧版本:
| [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]。