11. 案例研究:RdvMedecins 应用程序
11.1. 问题描述
RdvMedecins 应用程序用于管理一家医疗诊所的预约。每位医生都有若干时间段(例如从上午 8:00 到中午 12:00,每 20 分钟一个);一次预约由一个日期、一个时间段和一位客户(患者)组成。这是把上一课中的 [Laravel] 应用程序原样移植到 [Symfony] 上(而它本身又是从 [Flask]、[Spring MVC] 和 [ASP.NET Core MVC] 版本移植而来):同样的数据库、同样的业务规则、同样的页面、同样的 URL、同样的文本。HTML 页面由服务器使用 [Twig] 视图生成;数据库访问由 [Doctrine] 处理。
三种用户角色共用该应用程序:
ADMIN | 管理员([admin]) | 查看日程,为任何患者预约和取消预约;管理(列出、添加、编辑、删除)医生和客户 |
DOCTOR | 医生 | 查看日程,为任何患者预约和取消预约 |
USER | 客户(患者) | 查看日程但看不到其他患者的姓名;为自己预约;取消自己的预约;管理自己的账户;创建账户 |
主要管理规则:
- 不得预约过去的时间;
- 每个时间段在一天中只能被预约一次;
- 一位患者同一时间只能有一个即将到来的预约;
- 两位医生(或两位客户)不能有相同的名和姓,一个登录名只属于一个账户;
- 有预约的医生不能被删除;客户被删除时,其预约一并删除;
- 登录页面受到防机器人保护(验证码、限制尝试次数),创建患者账户需要先在该页面上完成验证码。
11.2. 使用应用程序
11.2.1. 登录页面

页面上有两个按钮:登录和创建患者账户。两者都要求输入图片中显示的字符。FR / EN 按钮用于切换语言:

错误(在本例中是验证码输入错误)显示在页面底部,背景为浅粉色:

11.2.2. 日历,管理员和医生所见的界面
登录后,管理员会进入日历页面。他们选择一位医生和一个日期:


每个时间段要么可预约(“预约”按钮),要么已被占用(显示患者姓名和“取消”按钮)。点击“预约”会打开一个窗口,要求填写患者信息。该窗口与页面的其余部分一样由服务器生成:此时 URL 中包含参数 [book=4],即所选时间段的编号:

预约之后,会有一条消息确认该预约:

点击“取消”会提示确认(此处是由 Pélissier 医生操作,其导航栏中不包含管理菜单):

11.2.3. 患者门户
患者(角色为 USER)进入“我的空间”:显示其即将到来的预约(可以取消),以及用于管理账户和查看日历的链接。此处,他们尚无预约:

在日历中,他们看不到其他患者的姓名;这些姓名被替换为“已预约”:这个名字甚至不会出现在页面的源代码中。他们可以预约一个可用的时间段:

预约窗口不会提示他选择患者:他是为自己预约。


他的仪表盘现在显示其即将到来的预约,他可以取消该预约:

由于他已有一个即将到来的预约,因此不能再预约另一个:“预约”按钮不会显示,而在另一天或另一位医生的日历上,会有一条消息说明原因:

账户管理:编辑个人信息、更改密码,或删除账户(及预约)。任何更改都需要输入当前密码:

患者如果试图打开仅限管理员访问的页面(此处是手动输入的 [/doctors]),会收到一个错误页面:

11.2.4. 管理医生和患者
管理员有两个额外的菜单:医生和患者:


添加医生的表单,提交时带有错误:

与现有医生同名的姓名会被拒绝,即使是以小写形式并带有重音书写的(数据库本身在比较姓名时不区分大小写和重音;参见示例 28):

删除患者需要确认:

11.2.5. 创建患者账户
在登录页面上,只有当验证码输入正确时,“创建患者账户”按钮才会打开表单:

账户创建完成后,用户会被重定向到登录页面,并已填入其用户名:

11.2.6. 注销
登录令牌的有效期为两小时。超过这段时间后(或令牌被篡改时),请求的页面会重定向到登录页面,并显示以下消息:

11.3. 安装与运行
该应用程序位于 [rdvmedecins2-symfony] 文件夹中,与 [examples] 文件夹相邻。它是一个独立的项目,有自己的 [composer.json] 和 [.env] 文件,以及自己的 [vendor] 文件夹。该文件夹中的 [README.md] 文件包含以下全部内容。本文档的引言部分已经介绍了 [PHP] 和 [Composer] 的安装;这里我们将进一步展开。
11.3.1. 所需软件
只需要三个软件:
- [PHP] 8.4 或更高版本,带有扩展 [pdo_mysql] 和 [intl]([Symfony] 8 需要 [PHP] 8.4,并且应用程序使用了该版本引入的特性,例如 [array_find])。在终端中验证安装:
第二条命令列出扩展:[pdo_mysql] 和 [intl] 应该出现在其中;
- [Composer],[PHP] 的库管理器(见附录);
- 一个 [MySQL] 8 服务器,例如 [Laragon] 在 [Windows] 下提供的那个(见附录)。[MariaDB] 同样适用。
推荐的编辑器是 [Visual Studio Code],带有扩展 [PHP Intelephense] 和 [Twig Language 2] (见附录);不过,所有操作都可以通过命令行完成。
11.3.2. 安装库
未提供 [vendor] 文件夹:请在 [rdvmedecins2-symfony] 文件夹中打开的终端窗口里一次性创建它(必须连接到互联网):
[Composer] 读取文件 [composer.json] (稍后讨论),下载 [Symfony]、[Doctrine]、[Twig]、[firebase/php-jwt] 以及它们所依赖的库,并生成类加载器 [vendor/autoload.php],以及用于组件 [vendor/autoload_runtime.php] 的文件 [Runtime] (下文讨论)。
11.3.3. 创建数据库
[dbrdvmedecins2] 数据库由 [database/dbrdvmedecins2.sql] 脚本创建。使用 [Laragon] 时,打开 [HeidiSQL] 工具(“数据库”按钮),然后通过“文件 / 运行 SQL 文件”菜单运行该脚本。在命令行中,在应用程序文件夹内:
| mysql -u root -p < database/dbrdvmedecins2.sql
|
[-p] 选项会提示输入 [root] 的密码;如果该账户没有密码(如 [Laragon] 的情况),则省略它。这与应用程序其他版本使用的是同一个数据库:如果它已经存在,此步骤可以跳过。该脚本可以随时运行,以恢复到原始数据。
11.3.4. 配置数据库访问
所有安装配置都包含在文件 [.env] 中(下文讨论)。默认情况下,应用程序连接到 [MySQL] ,位于 [127.0.0.1],端口 3306,使用用户 [root] ,无密码:这些是 [Laragon] 的默认设置。如果你的 [root] 账户有密码,请把它填入此文件中的 URL [DATABASE_URL] 行,放在 [root:] 之后。系统环境变量优先于该文件(示例 25):这样你就可以指定数据库的 URL,而无需把它写入项目文件。
11.3.5. 启动应用程序
在 [rdvmedecins2-symfony] 文件夹中打开的终端窗口里:
| php -S localhost:8081 -t public
|
| [Sun Sep 27 18:40:12 2026] PHP 8.4.21 Development Server (http://localhost:8081) started
|
接着,在浏览器中打开 URL [http://localhost:8081] ,并使用 [Ctrl-C] 停止应用程序。端口 8081 使你可以同时运行课程中的某个示例(端口 8000)。命令行工具 [symfony] (见附录)提供功能更全面的服务器,它还可以通过 HTTPS 提供应用程序服务:[symfony server:start --port=8081]。
11.3.6. 演示账户
每个账户的密码就是它的用户名;你还必须输入图片中的字符,大写或小写均可:
[admin] | ADMIN(管理员) |
[pelissier],[tatou],[dupont] | DOCTOR(医生) |
[martin],[durand],[bistrou],[german] | USER(患者) |
探索应用程序的指南:
- [admin]:日程,Marie PELISSIER 女士;今天:已有一个时间段被 Brigitte BISTROU 女士预约。为 Jean MARTIN 先生预约一个时间段,然后尝试为他预约第二个预约(会被拒绝)。医生和患者菜单:添加、编辑、删除(有预约的 PELISSIER 医生无法删除);
- [pelissier]:他的每日日程会直接显示;手动输入的地址 [/doctors]会返回 403 错误页面;
- [martin]:我的空间、其预约、其他患者显示为“已预约”的日历;管理我的账户;
- 登录页面:创建患者账户,然后用新账户登录;
- FR / EN 按钮:整个界面切换语言,包括日期。
11.3.7. 开发模式
随附的文件 [.env] 把应用程序配置为开发模式([APP_ENV=dev]):
- 服务器控制台会显示 日志 ,来自 [Symfony] (示例 24):所选路由、安全步骤,以及发送到数据库的每条 SQL 命令(示例 28)。例如,显示日历时(日志行已缩略):
| [info] Matched route "schedule".
[debug] Checking for authenticator support.
[debug] Checking support on authenticator.
[info] Authenticator successful!
[debug] Authenticator set no success response: request continues.
[info] Connecting with parameters [array]
[debug] Executing statement: SELECT d0_.id AS id_0, ..., u1_.login AS login_7, ... FROM doctors d0_ INNER JOIN users u1_ ON d0_.`user` = u1_.`id` WHERE d0_.id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT a0_.id AS id_0, ... FROM appointments a0_ INNER JOIN clients c1_ ON a0_.client_id = c1_.id INNER JOIN slots s2_ ON a0_.slot_id = s2_.id WHERE a0_.day = ? AND s2_.doctor_id = ? (parameters: [array], types: [array])
[debug] Executing statement: SELECT s0_.id AS id_0, ... FROM slots s0_ WHERE s0_.doctor_id = ? ORDER BY s0_.start_hour ASC, s0_.start_minute ASC (parameters: [array], types: [array])
127.0.0.1:55220 [200]: GET /schedule?doctorId=1&day=2026-09-27
[info] Disconnecting
|
在这里我们可以看到路由、认证器,然后是三个请求:医生及其账户、今天的预约及其患者,以及该医生可用的时间段。不过,下拉菜单中的医生列表并没有被读取;它来自缓存(稍后讨论);
- 发生意外异常时,会显示 [Symfony] 调试页面 (示例 03),其中包含异常消息和调用栈。在生产环境中,应用程序会改为显示它自己的 500 错误页面;
- 修改之后无需重启任何东西:每个请求都会重新读取 [PHP] 文件(示例 01),并且在 [dev] 模式下,当文件发生变化时,[Symfony] 会重建自己的缓存(容器、路由和已编译的视图)。
[Xdebug] 调试器 还允许你在 [Visual Studio Code] ([PHP Debug] 扩展)中单步执行应用程序:这是 [PHP] 的一个扩展,必须单独安装(参见 xdebug.org)。[Symfony] 的调试工具栏([WebProfilerBundle],[composer require --dev symfony/web-profiler-bundle])会在每个页面底部显示请求的详细信息:路由、用户、SQL 命令及其参数、翻译、执行时间等。
11.3.8. 生产服务器
[PHP] 开发服务器不适用于生产环境。在生产环境中,应用程序由 Web 服务器([nginx]、[Apache])提供服务,它把请求转发给 [PHP-FPM],一个进程管理器([PHP])。站点根目录是 [public] 文件夹:只有其中的文件可以从浏览器访问;[var] 文件夹必须可由服务器写入。在 [.env] 文件中,必须指定生产模式、更改密钥,并声明站点通过 HTTPS 提供服务:
| APP_ENV=prod
APP_SECRET=<a long random string>
JWT_SECRET=<another long random string>
COOKIE_SECURE=1
|
可以从 [PHP] 本身获得合适的随机字符串:[php -r "echo bin2hex(random_bytes(32));"]。然后用两条命令准备应用程序:
| composer install --no-dev --optimize-autoloader
php bin/console cache:clear
|
第二条命令生成生产缓存(已编译的容器、路由、已编译的视图等):在 [prod] 模式下,[Symfony] 不再检查文件是否发生变化,这样更快;因此,每次修改之后都必须重新运行它。[composer dump-env prod] 命令还会把 [.env] 文件转换为一个 [PHP] ([.env.local.php])文件,读取速度更快。
11.3.9. 常见问题
[PHP] 应用程序不会“启动”:每个请求都会重新构建应用程序(示例 01)。因此,无法访问的数据库不会阻止服务器启动:错误会出现在第一个查询数据库的页面上(登录页面不查询数据库;连接过程才会)。在 [dev] 模式下,错误会显示在 [Symfony] 调试页面上;无论如何,它都会记录在日志文件中,开发服务器会在控制台中显示该日志。例如,数据库不存在时:
| [critical] Uncaught PHP Exception Doctrine\DBAL\Exception\ConnectionException: "An exception occurred in the driver: SQLSTATE[HY000] [1049] Unknown database 'dbunknown'" at ExceptionConverter.php line 91
|
最常见的消息:
[Failed opening required '.../vendor/autoload_runtime.php'] | 未执行命令 [composer install] |
[Your Composer dependencies require a PHP version ">= 8.4.0"] | [PHP] 的版本低于 8.4 |
[could not find driver] | [PHP] 的扩展 [pdo_mysql] 未启用(文件 [php.ini],或 [Laragon] 中的“PHP / 扩展”菜单) |
[SQLSTATE[HY000] [2002] Connection refused] | [MySQL] 尚未启动,或没有在 [127.0.0.1:3306] 上监听 |
[SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost'] | 必须在 [DATABASE_URL] 中填写 [MySQL] 的密码(参见“配置数据库访问”) |
[SQLSTATE[HY000] [1049] Unknown database 'dbrdvmedecins2'] | 未执行脚本 [database/dbrdvmedecins2.sql] |
[JWT_SECRET must be at least 32 characters long (see .env).] | 令牌的密钥在 [.env] 中太短 |
[Failed to listen on localhost:8081 (reason: Address already in use)] | 端口 8081 已被占用(是否正在运行应用程序的另一个版本?):请停止它,或选择另一个端口 |
11.4. 应用程序架构

- 浏览器把请求发送给服务器([php -S],或 [nginx] + [PHP-FPM]),服务器通过文件 [public/index.php] 把请求转发给 [Symfony]。[Symfony] 的内核会发布与请求处理相关的事件(参见生命周期一章),监听器会对这些事件作出响应:请求语言([SetLanguage])、路由、会话,然后是安全组件的防火墙:根据其 Cookie 中的 JWT 令牌识别用户([TokenAuthenticator]),而 [access_control] 规则会拒绝未获授权的访问者访问受保护页面。错误会生成 HTML 页面([ErrorPage]);
- [Controller]:Web 层控制器。它们都通过唯一的一个对象 [ApplicationModel] (文件夹 [Web])来工作,该对象缓存医生和客户的列表,并把其他请求转发给业务层;[Form]:表单及其约束;[Views]:视图模板;
- [Security]:令牌、JWT、认证器、验证码、尝试次数限制,以及账户创建通行证;
- [Web]:控制器的共同部分:缓存和外观 [ApplicationModel]、控制器的父类、闪现消息以及一些工具函数;
- [Business]:业务规则和事务;
- [Dao]:DAO 层,每张表一个类;
- [Entity]:[Doctrine] 实体,DAO 层通过它们从数据库读取和向数据库写入;[Domain]:日历对象,由业务层计算得出;
- [templates]:[Twig] 视图,用于生成 HTML 页面;[translations]:词典;[public]:样式表、页面脚本和 [Bootstrap];
- [config] 文件夹和 [.env] 文件:配置,它把一切整合在一起。
应用程序文件夹(不含 [vendor] 和 [var]):
| rdvmedecins2-symfony/
├── bin/
│ └── console
├── composer.json
├── config/
│ ├── bundles.php
│ ├── packages/
│ │ ├── doctrine.yaml
│ │ ├── framework.yaml
│ │ ├── security.yaml
│ │ └── twig.yaml
│ ├── routes.yaml
│ └── services.yaml
├── database/
│ ├── dbrdvmedecins2.sql
│ └── README.md
├── .env
├── public/
│ ├── css/
│ │ └── styles.css
│ ├── index.php
│ ├── js/
│ │ └── app.js
│ └── lib/
│ └── bootstrap/
├── README.md
├── src/
│ ├── Controller/
│ │ ├── ScheduleController.php
│ │ ├── AuthController.php
│ │ ├── ClientsController.php
│ │ ├── PatientAreaController.php
│ │ ├── RegistrationController.php
│ │ ├── LanguageController.php
│ │ ├── DoctorsController.php
│ │ ├── PersonsController.php
│ │ └── README.md
│ ├── Dao/
│ │ ├── ClientDao.php
│ │ ├── SlotDao.php
│ │ ├── DoctorDao.php
│ │ ├── PersonDao.php
│ │ ├── README.md
│ │ ├── AppointmentDao.php
│ │ └── UserDao.php
│ ├── Domain/
│ │ ├── DoctorDaySchedule.php
│ │ ├── DoctorDaySlot.php
│ │ └── README.md
│ ├── Entity/
│ │ ├── Client.php
│ │ ├── Slot.php
│ │ ├── Doctor.php
│ │ ├── Person.php
│ │ ├── README.md
│ │ ├── Role.php
│ │ ├── Appointment.php
│ │ └── User.php
│ ├── EventListener/
│ │ ├── SetLanguage.php
│ │ ├── ErrorPage.php
│ │ ├── README.md
│ │ └── CheckRegistrationPass.php
│ ├── Form/
│ │ ├── PersonFieldsType.php
│ │ ├── RegistrationType.php
│ │ ├── MyAccountType.php
│ │ ├── PersonType.php
│ │ └── README.md
│ ├── Kernel.php
│ ├── Business/
│ │ ├── Dates.php
│ │ ├── Descriptor.php
│ │ ├── PersonData.php
│ │ ├── Business.php
│ │ ├── BusinessException.php
│ │ ├── BusinessService.php
│ │ └── README.md
│ ├── Security/
│ │ ├── AuthService.php
│ │ ├── Captcha.php
│ │ ├── CaptchaService.php
│ │ ├── CaptchaDrawing.php
│ │ ├── TokenAuthenticator.php
│ │ ├── AttemptLimiter.php
│ │ ├── RegistrationPass.php
│ │ ├── RegistrationPassRequired.php
│ │ ├── README.md
│ │ ├── InvalidSession.php
│ │ └── ConnectedUser.php
│ ├── Twig/
│ │ └── ViewsExtension.php
│ ├── Views/
│ │ ├── ScheduleView.php
│ │ ├── PersonKeys.php
│ │ ├── ScheduleRow.php
│ │ ├── OptionView.php
│ │ ├── README.md
│ │ ├── AppointmentView.php
│ │ └── BookingView.php
│ └── Web/
│ ├── ApplicationModel.php
│ ├── BaseController.php
│ ├── Flash.php
│ ├── Message.php
│ ├── Utils.php
│ └── README.md
├── templates/
│ ├── schedule.html.twig
│ ├── account.html.twig
│ ├── error.html.twig
│ ├── area.html.twig
│ ├── fragments/
│ │ ├── captcha.html.twig
│ │ ├── confirmation.html.twig
│ │ ├── errors.html.twig
│ │ ├── navbar.html.twig
│ │ ├── booking.html.twig
│ │ └── success.html.twig
│ ├── registration.html.twig
│ ├── layout.html.twig
│ ├── login.html.twig
│ ├── macros.html.twig
│ ├── persons/
│ │ ├── form.html.twig
│ │ └── list.html.twig
│ └── README.md
└── translations/
├── messages+intl-icu.en.yaml
└── messages+intl-icu.fr.yaml
|
这是标准 [Symfony] 应用程序的结构——由 [composer create-project symfony/skeleton] 命令创建的结构(示例 01)——并补充了应用程序所需的 Bundle。与示例相比有两点不同:应用程序有自己的 [vendor] 文件夹(示例共用 [examples] 文件夹中的那个),并且其入口点使用 [Runtime] 组件,来自 [Symfony] (稍后讨论)。应用程序的类按照 PSR-4 规则(示例 01)组织在 [src] 文件夹中:[App\Business\BusinessService] 类位于 [src/Business/BusinessService.php] 文件中。[Symfony] 并不要求使用其中任何一个文件夹:[Controller]、[Entity]、[EventListener]、[Form] 和 [Twig] 是约定俗成的(即 [MakerBundle] 所使用的那些),而其他文件夹([Dao]、[Business]、[Security] 等)属于示例 28 中的分层架构。[Bootstrap] 这次是应用程序的一部分(文件夹 [public/lib/bootstrap]):案例研究是自包含的。
11.5. 数据库
[dbrdvmedecins2] 数据库有五张表:
- [users]:获准登录的用户;
- [doctors] 和 [clients]:医生和患者,各自关联到其用户账户;
- [slots]:每位医生的可用时间段;
- [appointments]:预约,每个时间段在某一天对应一位客户。
11.5.1. database/dbrdvmedecins2.sql
| -- =========================================================================
-- Database [dbrdvmedecins2] - MySQL 8
--
-- Evolution of [dbrdvmedecins]:
-- 1. the [doctors] and [clients] tables get a [user] column,
-- foreign key to users(id): every doctor and every client is
-- now also a user able to log in;
-- 2. a third role appears: DOCTOR (in addition to ADMIN and USER);
-- 3. the script creates a [users] row for each doctor (role DOCTOR)
-- and for each client (role USER):
-- - login = last name in lower case
-- - password = last name in lower case, hashed with bcrypt (10 rounds)
-- - display name = first name + last name
--
-- 4. uniqueness constraints, all NAMED (the application recognizes
-- the name of the violated constraint in the MySQL error message):
-- - unq_users_login : a login belongs to one account only;
-- - unq_doctors_first_name_last_name : two doctors cannot have the
-- same first and last names;
-- - unq_clients_first_name_last_name : same for the clients.
-- Beware: the utf8mb4_unicode_ci collation compares regardless of
-- case and accents - "Hélène DUPONT" and "helene dupont"
-- are therefore considered identical.
--
-- The [users] table must now be created BEFORE [doctors] and [clients]
-- (they reference it), and dropped AFTER them.
-- =========================================================================
-- the script is written in UTF-8
SET NAMES utf8mb4;
-- we start again from an empty database on each run of the script (handy in development)
CREATE DATABASE IF NOT EXISTS dbrdvmedecins2 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbrdvmedecins2;
-- drop order: from the "child" tables to the "parent" tables
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS slots;
DROP TABLE IF EXISTS clients;
DROP TABLE IF EXISTS doctors;
DROP TABLE IF EXISTS users;
-- -------------------------------------------------------------------------
-- table [users]: the users allowed to log in to the application
-- -------------------------------------------------------------------------
CREATE TABLE users (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
login VARCHAR(30) NOT NULL, -- login identifier
password VARCHAR(100) NOT NULL, -- HASHED password (bcrypt) - never in clear
name VARCHAR(40) NOT NULL, -- name displayed once logged in
role VARCHAR(10) NOT NULL, -- 'ADMIN', 'DOCTOR' or 'USER'
-- a login can belong to one account only
CONSTRAINT unq_users_login UNIQUE (login)
);
-- -------------------------------------------------------------------------
-- table [doctors]: the doctors of the practice
-- -------------------------------------------------------------------------
CREATE TABLE doctors (
id INT AUTO_INCREMENT PRIMARY KEY, -- primary key (technical identifier)
version INT NOT NULL DEFAULT 0, -- row version number (optimistic lock)
title VARCHAR(5) NOT NULL, -- Melle, Mme, Mr
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_doctors_user FOREIGN KEY (`user`) REFERENCES users(id),
-- one account per doctor, and one doctor per account
CONSTRAINT unq_doctors_user UNIQUE (`user`),
-- two doctors cannot have the same first and last names
CONSTRAINT unq_doctors_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- table [clients]: the doctors' patients
-- -------------------------------------------------------------------------
CREATE TABLE clients (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
title VARCHAR(5) NOT NULL,
last_name VARCHAR(20) NOT NULL,
first_name VARCHAR(20) NOT NULL,
`user` INT NOT NULL, -- foreign key -> users(id)
CONSTRAINT fk_clients_user FOREIGN KEY (`user`) REFERENCES users(id),
-- one account per client, and one client per account
CONSTRAINT unq_clients_user UNIQUE (`user`),
-- two clients cannot have the same first and last names
CONSTRAINT unq_clients_first_name_last_name UNIQUE (first_name, last_name)
);
-- -------------------------------------------------------------------------
-- table [slots]: the time slots of each doctor
-- -------------------------------------------------------------------------
CREATE TABLE slots (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
doctor_id INT NOT NULL, -- foreign key -> doctors(id)
start_hour INT NOT NULL, -- start hour of the slot
start_minute INT NOT NULL, -- start minute of the slot
end_hour INT NOT NULL, -- end hour of the slot
end_minute INT NOT NULL, -- end minute of the slot
CONSTRAINT fk_slots_doctor FOREIGN KEY (doctor_id) REFERENCES doctors(id)
);
-- -------------------------------------------------------------------------
-- table [appointments]: the appointments booked by the clients
-- -------------------------------------------------------------------------
CREATE TABLE appointments (
id INT AUTO_INCREMENT PRIMARY KEY,
version INT NOT NULL DEFAULT 0,
day DATE NOT NULL, -- day of the appointment
slot_id INT NOT NULL, -- foreign key -> slots(id)
client_id INT NOT NULL, -- foreign key -> clients(id)
CONSTRAINT fk_appointments_slot FOREIGN KEY (slot_id) REFERENCES slots(id),
CONSTRAINT fk_appointments_client FOREIGN KEY (client_id) REFERENCES clients(id),
-- the same slot, on the same day, can be booked only once
CONSTRAINT unq1_appointments UNIQUE (day, slot_id)
);
-- =========================================================================
-- Demo data
-- =========================================================================
-- the users: passwords hashed with bcrypt (10 salt rounds)
-- admin/admin (ADMIN)
-- one DOCTOR account per doctor, one USER account per client
-- (the user/user demo account is gone: a USER account is
-- now ALWAYS a client's account, who can book and manage the account)
-- (login = password = last name in lower case)
INSERT INTO users (login, password, name, role) VALUES
('admin', '$2b$10$YSNBJXXHX9mp13nPZb6YGu8M1jR6uvPwO1s2X73z0QAqBR7TOQjoq', 'Administrator', 'ADMIN'),
-- doctors
('pelissier', '$2b$10$DnSDOK5ONrdMxTTr1NKCHOphR3WSp5QAyG9S9ueruw9HwlxI.16ba', 'Marie PELISSIER', 'DOCTOR'),
('tatou', '$2b$10$PeovBO.gmJUKP4PglI/fwu4xtWOYSxoM5VTWjTj7uQ4wcd9P9.htS', 'Paul TATOU', 'DOCTOR'),
('dupont', '$2b$10$az7wvPKC1h0EiAxXwu/PU.vYjzmB04rd5B7QnK0mvxp4niYIHVoc.', 'Sophie DUPONT', 'DOCTOR'),
-- clients
('martin', '$2b$10$GT6S5pp.WdGapFw/UmocXesbC6LEjJfZzgatCUyG9Sf4o1iBNlqZW', 'Jean MARTIN', 'USER'),
('durand', '$2b$10$l2gl/zCder8E7Nh4VxGRX.0.SsO3FDiXt6YwqYq3v9nFzgC/jQCy6', 'Alice DURAND', 'USER'),
('bistrou', '$2b$10$naeRp2YUU6c.QDl5itJMAum3Y5aHdUV6jwIcsbp0D.64jPG4F6E9m', 'Brigitte BISTROU', 'USER'),
('german', '$2b$10$tTWxh3ROWF7NjhZOMnWDMOsZcnSWUiwwfy5C3G0.xhccTXALKyLeW', 'Luc GERMAN', 'USER');
-- the doctors: the [user] column is looked up from the login,
-- rather than assuming the values of the primary keys of [users]
INSERT INTO doctors (title, last_name, first_name, `user`) VALUES
('Mme', 'PELISSIER', 'Marie', (SELECT id FROM users WHERE login = 'pelissier')),
('Mr', 'TATOU', 'Paul', (SELECT id FROM users WHERE login = 'tatou')),
('Melle','DUPONT', 'Sophie', (SELECT id FROM users WHERE login = 'dupont'));
INSERT INTO clients (title, last_name, first_name, `user`) VALUES
('Mr', 'MARTIN', 'Jean', (SELECT id FROM users WHERE login = 'martin')),
('Mme', 'DURAND', 'Alice', (SELECT id FROM users WHERE login = 'durand')),
('Melle','BISTROU', 'Brigitte', (SELECT id FROM users WHERE login = 'bistrou')),
('Mr', 'GERMAN', 'Luc', (SELECT id FROM users WHERE login = 'german'));
-- slots of doctor PELISSIER (doctor_id = 1): from 8:00 to 12:00 in 20-minute steps
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(1, 8, 0, 8, 20), (1, 8, 20, 8, 40), (1, 8, 40, 9, 0),
(1, 9, 0, 9, 20), (1, 9, 20, 9, 40), (1, 9, 40, 10, 0),
(1, 10, 0, 10, 20), (1, 10, 20, 10, 40), (1, 10, 40, 11, 0),
(1, 11, 0, 11, 20), (1, 11, 20, 11, 40), (1, 11, 40, 12, 0);
-- slots of doctor TATOU (doctor_id = 2): from 14:00 to 18:00 in 20-minute steps
INSERT INTO slots (doctor_id, start_hour, start_minute, end_hour, end_minute) VALUES
(2, 14, 0, 14, 20), (2, 14, 20, 14, 40), (2, 14, 40, 15, 0),
(2, 15, 0, 15, 20), (2, 15, 20, 15, 40), (2, 15, 40, 16, 0),
(2, 16, 0, 16, 20), (2, 16, 20, 16, 40), (2, 16, 40, 17, 0),
(2, 17, 0, 17, 20), (2, 17, 20, 17, 40), (2, 17, 40, 18, 0);
-- an appointment already booked, to see an occupied slot right away in the schedule
INSERT INTO appointments (day, slot_id, client_id) VALUES
(CURDATE(), 2, 3);
|
- 第 33 行:如果数据库不存在则创建,字符集为 [utf8mb4] ,排序规则为 [utf8mb4_unicode_ci],比较字符串时不区分大小写和重音(示例 28);
- 第 37–41 行:先删除各表,再重新创建;该脚本会把数据库恢复到初始状态。顺序很重要:只要还有其他表通过外键引用某张表,这张表就无法被删除;
- 第 46–55 行:用户:一个用户名,以及用 哈希 算法 [bcrypt] 处理的密码(示例 25)、登录后显示的名称,以及角色([ADMIN]、[DOCTOR], 或 [USER])。约束 [unq_users_login] 确保一个用户名只属于一个账户;
- 第 60–72 行:每张表都有一个由数据库生成的主键 [id],以及一个列 [version],即乐观锁(示例 28)。列 [user] 是一个外键 ,引用 [users(id)]:数据库会拒绝任何不是现有用户 ID 的值。由于 [user] 是 SQL 语言中的一个词,因此用反引号括起来。三个约束:[fk_doctors_user] (外键)、[unq_doctors_user] (每位医生一个账户,每个账户一位医生)以及 [unq_doctors_first_name_last_name] (不允许重名)。所有约束都有名称:应用程序通过名称来识别被违反的约束;
- 第 77–89 行:[clients] 表的列与之完全相同;
- 第 94–103 行:一个时间段属于一位医生;其开始和结束时间以小时和分钟存储;
- 第 108–118 行:一次预约由一个日期(类型 [DATE],不含时间)、一个时间段和一位客户组成。约束 [unq1_appointments] 防止同一个时间段在同一天被预约两次:即使两个用户同时尝试预约,数据库也会强制执行这条规则;
- 第 130–140 行:演示用户,其密码就是其登录名。哈希以 [$2b$10$] 开头:算法([bcrypt],变体 [2b])和成本(10)。接着是盐值和哈希。这些哈希是由应用程序的 [Flask] 版本计算的;[PHP] 自己写入时使用前缀 [$2y$],但对两者的验证效果相同;
- 第 144–147 行:每位医生的 [user] 列是通过基于登录名的子查询获得的,而不是假定主键的值;
- 第 170–171 行:在 PELISSIER 医生的第二个时间段中,已为 BISTROU 女士安排了一个今天 ([CURDATE()])的预约:因此日历会立即显示一个已被预约的时间段。
与 [Symfony] 的惯常做法不同,数据库不是由 [Doctrine] 根据实体创建的,也不是通过迁移 创建的(示例 28):它与应用程序的其他版本共享,SQL 脚本为所有版本所共用。命令 [php bin/console doctrine:schema:validate] 用于验证实体描述是否一致,以及它们是否与数据库表相对应。
11.6. 项目配置
11.6.1. composer.json
| {
"name": "rdvmedecins/rdvmedecins2-symfony",
"description": "RdvMedecins: booking medical appointments, HTML pages built by the server (Symfony + Twig + Doctrine)",
"type": "project",
"license": "MIT",
"require": {
"php": ">=8.4",
"ext-intl": "*",
"ext-pdo_mysql": "*",
"doctrine/doctrine-bundle": "^3.3",
"doctrine/orm": "^3.7",
"firebase/php-jwt": "^7.2",
"symfony/asset": "^8.1",
"symfony/console": "^8.1",
"symfony/dotenv": "^8.1",
"symfony/form": "^8.1",
"symfony/framework-bundle": "^8.1",
"symfony/lock": "^8.1",
"symfony/rate-limiter": "^8.1",
"symfony/runtime": "^8.1",
"symfony/security-bundle": "^8.1",
"symfony/translation": "^8.1",
"symfony/twig-bundle": "^8.1",
"symfony/validator": "^8.1",
"symfony/yaml": "^8.1",
"twig/twig": "^3.30"
},
"autoload": {
"psr-4": {
"App\\": "src/"
}
},
"config": {
"allow-plugins": {
"symfony/runtime": true
},
"optimize-autoloader": true,
"sort-packages": true
},
"minimum-stability": "stable",
"prefer-stable": true
}
|
- 第 6–27 行:应用程序所需的库及其必须满足的约束。[^8.1] 的含义是“版本 8.1 或同一主版本 8 中更新的版本”:[Composer] 接受修复缺陷或添加功能的版本,但不接受可能破坏应用程序的版本(版本 9)。[php]、[ext-intl] 和 [ext-pdo_mysql] 这几行指的不是库,而是环境要求:如果 [PHP] 的版本或其扩展不兼容,[Composer] 会拒绝安装,而不是任由应用程序以后再出错。[Symfony] 不是单一的库:它的每个组件(路由、表单、安全等)都是一个库,应用程序只请求它所需要的那些;[Composer] 还会额外安装它们所依赖的库;
- 第 28–32 行:应用程序的 PSR-4 规则:[App] 命名空间中的类位于 [src] 文件夹中(示例 01:在示例中,文件 [public/index.php] 本身通过 [addPsr4] 向类加载器声明了这条规则);
- 第 34–36 行:组件 [Runtime] 是 插件 (plugin),用于 [Composer];它在安装期间运行,以写入文件 [vendor/autoload_runtime.php]。[Composer] 会请求执行插件代码的许可;此处授予了该许可。
[composer install] 安装满足这些约束的版本,并把所安装的确切版本记录在名为 [composer.lock] 的文件中。之后的安装(例如在另一台机器上)会使用此文件:它们会安装完全相同的版本。[composer update] 则相反,它会搜索 [composer.json] 所允许的最新版本,并更新 [composer.lock]。命令 [composer show] 列出安装在 [vendor] 文件夹中的内容。在典型的项目中,每次执行 [Symfony Flex] 时,该文件都会由 [composer require] 补充(示例 01)。
11.6.2. .env
| # =========================================================================
# .env:专属于此次安装的设置,在每次请求开始时由
# Dotenv 组件读取(见 public/index.php)。它们会变成
# 环境变量,配置(config 文件夹)通过
# %env(NAME)% 读取它们。真正的系统环境变量优先于此文件。
# =========================================================================
# dev:开发;prod:生产(见 README.md)
APP_ENV=dev
# Symfony 的密钥(防 CSRF 令牌、签名...)。在生产环境中:
# 使用另一个值,要长且随机
APP_SECRET=34b2364cc4c93df6e4ee35251a048088
# —— MySQL 数据库 [dbrdvmedecins2](脚本:database/dbrdvmedecins2.sql):
# 数据库管理系统、用户及其密码(Laragon 的:root,无
# 密码)、服务器、端口、数据库,然后是服务器版本(例如,对于 MariaDB:
# serverVersion=10.11.2-MariaDB)和字符集
DATABASE_URL="mysql://root:@127.0.0.1:3306/dbrdvmedecins2?serverVersion=8.0.32&charset=utf8mb4"
# —— 身份验证(见 src/Security/AuthService.php)
# JWT 令牌的密钥:至少 32 个字符(HMAC-SHA256)
JWT_SECRET=ef1cfc9709f10b5b5d183b4deb6d5dbbe69518629c3b12a8
# 令牌的有效时长,以分钟为单位(120 分钟 = 2 小时)
JWT_DURATION_MINUTES=120
# 生产环境中为 1(站点通过 HTTPS 提供服务):Cookie 绝不以未加密方式传输
COOKIE_SECURE=0
# —— 防范机器人(见 src/Security/AttemptLimiter.php)
# 同一 IP 地址对同一登录名允许的登录失败次数,之后
# 在此时长内(以分钟为单位)阻止;如果一个 IP 地址
# 累计达到 LOGIN_MAX_FAILURES_IP 次失败(所有登录名合计,例如机器人尝试
# 成千上万个不同的登录名),该 IP 地址也会被阻止
LOGIN_MAX_FAILURES=5
LOGIN_MAX_FAILURES_IP=25
LOGIN_BLOCK_MINUTES=15
# 每个 IP 地址每小时最多创建的客户账户数。在教室里,所有
# 计算机通常经由同一个地址出去:需要时请增大该值
REGISTRATION_MAX_PER_HOUR=10
|
包含特定于本次安装 的设置的文件(示例 25):这些设置因机器而异(数据库及其凭据),或者属于机密信息(密钥)。在真实项目中,生产环境的机密不会放在这里:它们由真实的环境变量、一个永不发布的 [.env.local] 文件,或 [Symfony] 密钥保管库提供(示例 25)。
- 第 9 行:应用程序模式:[dev] (开发:调试模式、调试页面、每次更改都会重建缓存)或 [prod];
- 第 12 行:[Symfony] 的密钥,尤其用于防 CSRF 令牌(示例 21);
- 第 18 行:数据库连接(示例 28);
- 第 20–38 行:应用程序特有的设置:JWT 令牌(示例 25)和防机器人保护(示例 27)。
11.6.3. config/bundles.php 和 config/packages/framework.yaml
| <?php
// config/bundles.php:应用程序的 Bundle(见示例 01):Symfony 的核心、
// Twig 视图、安全,以及 Doctrine(数据库访问)
return [
Symfony\Bundle\FrameworkBundle\FrameworkBundle::class => ['all' => true],
Symfony\Bundle\TwigBundle\TwigBundle::class => ['all' => true],
Symfony\Bundle\SecurityBundle\SecurityBundle::class => ['all' => true],
Doctrine\Bundle\DoctrineBundle\DoctrineBundle::class => ['all' => true],
];
|
应用程序的四个 Bundle:核心 [Symfony]、[Twig] (示例 13)、安全(示例 25),以及 [Doctrine] (示例 28)。
| # =========================================================================
# config/packages/framework.yaml:FrameworkBundle 的配置
# =========================================================================
framework:
secret: '%env(APP_SECRET)%'
# —— 语言(见示例 22):默认为英语,另有法语;
# 翻译服务及其字典(translations 文件夹)
default_locale: en
enabled_locales: ['en', 'fr']
translator:
default_path: '%kernel.project_dir%/translations'
fallbacks: ['en']
# —— 表单验证:其消息是我们字典中的键
# (ERRORS.FIRSTNAME_REQUIRED...),在域
# [messages] 中翻译,与视图所用的域相同(默认为 [validators] 域)
validation:
translation_domain: messages
# —— 会话(SESSION)(闪现消息、防 CSRF 令牌):var/sessions
# 文件夹中的文件。会话 Cookie 绝不能被页面的 JavaScript 读取
# (httponly),也不会随来自其他站点的 POST 请求一起发送
# (samesite lax),在生产环境中也不会以未加密方式发送(secure)
session:
handler_id: null
save_path: '%kernel.project_dir%/var/sessions/%kernel.environment%'
name: rdvmedecins_session
cookie_httponly: true
cookie_samesite: lax
cookie_secure: '%env(bool:COOKIE_SECURE)%'
csrf_protection: true
# —— 锁(见示例 20),用于尝试次数限制器
lock: 'flock://%kernel.project_dir%/var/lock'
# —— 尝试次数限制器(LIMITERS)(见示例 27 和 src/Security/AttemptLimiter.php)。
# fixed_window:每个周期 [interval] 内最多 [limit] 次尝试,从
# 第一次尝试开始计算
rate_limiter:
# 某个登录名从某个 IP 地址的登录失败次数
login:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# 某个 IP 地址的登录失败次数,所有登录名合计
login_ip:
policy: fixed_window
limit: '%env(int:LOGIN_MAX_FAILURES_IP)%'
interval: '%env(LOGIN_BLOCK_MINUTES)% minutes'
# 从某个 IP 地址每小时创建的账户数
registration:
policy: fixed_window
limit: '%env(int:REGISTRATION_MAX_PER_HOUR)%'
interval: '1 hour'
|
- 第 9–13 行:语言和翻译器(示例 22);
- 第 18–19 行:验证组件把其消息翻译到 [validators] 域中(示例 09);我们的约束使用自己词典中的键([ERRORS.FIRSTNAME_REQUIRED] 等)作为消息键,这些键位于 [messages] 域中:我们要把这一点告知验证组件。这样,整个应用程序每种语言只需要一份词典;
- 第 25–32 行:会话 (示例 20):文件存放在 [var/sessions] 文件夹中。应用程序在其中存储的内容非常少:闪现消息和防 CSRF 令牌。会话 Cookie 名为 [rdvmedecins_session];页面上的 [JavaScript] 永远无法读取它,也不会在来自其他站点的 POST 请求中发送它,在生产环境中也不会以明文发送(前缀 [bool:] 把变量转换为布尔值,示例 25);
- 第 35 行:锁(示例 20),供尝试次数限制器和验证码服务使用;
- 第 40–55 行:三个防机器人限制器 (示例 27),其设置来自文件 [.env]。一个值可以把文本和变量组合起来:['%env(LOGIN_BLOCK_MINUTES)% minutes']。
应用程序缓存 ([cache.app] 服务,示例 20)无需配置:它以文件形式存储在 [var/cache/dev/pools] (或 [prod])文件夹中。应用程序在其中存储医生和客户列表、验证码、尝试次数计数器和通行证——这些都必须在所有请求之间共享。如果有多台服务器,你会选择共享缓存,例如 [Redis] ([framework.cache.app: cache.adapter.redis])。
11.6.4. config/packages/security.yaml
| # =========================================================================
# config/packages/security.yaml:安全(见示例 25 和 26)
# =========================================================================
security:
# 账户密码的哈希:bcrypt,10 轮,与 SQL 脚本中的
# 哈希相同。PHP 还会验证应用程序其他版本的 $2b$(Python)和 $2a$
# (Java)哈希,这些版本共享同一个数据库
password_hashers:
App\Entity\User:
algorithm: bcrypt
cost: 10
# 用户提供者:此处无关紧要,已登录的用户由其令牌
# 描述(见 src/Security/TokenAuthenticator.php);不过 Symfony
# 仍然要求提供一个:一个空列表
providers:
none:
memory: ~
firewalls:
# 整个应用程序只有一个防火墙,无状态(STATELESS):用户不
# 存储在会话中,而是在每次请求时根据其 Cookie 中的
# JWT 令牌重新找到
main:
stateless: true
provider: none
custom_authenticators:
- App\Security\TokenAuthenticator
# ---------------------------------------------------------------------
# 访问规则(THE ACCESS RULE):规则按顺序检查,第一个
# 其模式(路径)与 URL 的路径匹配的规则生效:
# - 少数公开 URL(PUBLIC_ACCESS):主页、登录、
# 语言选择、创建账户;
# - 保留给特定角色的 URL(角色列表:满足其中一个即可);
# - 所有其他 URL 都需要已通过身份验证的用户(最后一条规则)。
# 这就是“除了允许的一切都禁止”的规则:以后添加的、
# 而又忘记保护的 URL,默认也会受到保护。
# 被拒绝的匿名访问者会被送到登录页面(防火墙的
# 入口点);没有所需角色的已验证用户
# 会收到 403 错误页面。
# ---------------------------------------------------------------------
access_control:
- { path: ^/$, roles: PUBLIC_ACCESS }
- { path: ^/(login|logout)$, roles: PUBLIC_ACCESS }
- { path: ^/language/, roles: PUBLIC_ACCESS }
- { path: ^/register, roles: PUBLIC_ACCESS }
# 患者在“My area”而不是日程表中取消自己的预约
- { path: ^/schedule/cancel$, roles: [ROLE_ADMIN, ROLE_DOCTOR] }
- { path: ^/(doctors|clients), roles: ROLE_ADMIN }
- { path: ^/my-, roles: ROLE_USER }
- { path: ^/, roles: IS_AUTHENTICATED }
|
安全配置(示例 25 和 26):
- 第 8–11 行:密码哈希:[bcrypt],10 轮,与 SQL 脚本中的哈希一致。要验证密码,[PHP] 会从哈希本身读取算法和成本:数据库中由 [Python] ([$2b$])或 [Java] ([$2a$])写入的哈希,与由 [PHP] ([$2y$])写入的哈希一样可以被验证;
- 第 16–18 行:用户提供者。应用程序的认证器并不需要它:已登录的用户由其令牌识别,无需读取数据库(示例 25)。但安全组件要求有一个提供者:一个没有任何用户的 [memory] 提供者;
- 第 24–28 行:整个应用程序只有一个无状态防火墙,使用我们的认证器。没有模式([pattern]):它覆盖所有 URL。[public] 文件夹中的文件([Bootstrap]、样式表、脚本)不会经过 [Symfony]:Web 服务器直接提供它们;
- 第 43–52 行:应用程序的访问规则。[access_control] 规则按顺序求值,应用第一条其模式与 URL 路径匹配的规则。[PUBLIC_ACCESS] 允许所有人访问该 URL,包括匿名访问者:主页、登录、语言选择和账户创建。接下来是限定某些角色的 URL 规则:角色列表(第 49 行)表示其中任何一个角色即可。最后一条规则 [^/] 适用于所有其余 URL,并要求已认证的用户。这就是“除了明确允许的,其余一律禁止”的规则:以后添加的 URL——即使你忘了保护它——也会自动受到保护。相反的错误——不小心没有保护的公共 URL——会立刻显现出来;而忘记保护的受保护页面这类错误则远没那么容易发现。
角色在这里通过 URL 模式在单个文件中验证,而不是通过操作上的 [#[IsGranted]] 属性(示例 26):两种方式都可行,并且可以结合使用。
11.6.5. config/packages/doctrine.yaml、twig.yaml、config/routes.yaml
| # config/packages/doctrine.yaml:Doctrine,数据库访问(见示例 28)
doctrine:
# 连接:.env 文件中的 DATABASE_URL。在调试模式下,每条 SQL
# 语句都会写入日志,开发服务器会显示该日志
dbal:
url: '%env(resolve:DATABASE_URL)%'
# 实体(ENTITIES):src/Entity 文件夹中的类,由 PHP 属性描述
orm:
mappings:
App:
type: attribute
dir: '%kernel.project_dir%/src/Entity'
prefix: 'App\Entity'
|
[Doctrine] 的配置与示例 28 中所示的相同。
| # config/packages/twig.yaml:Twig 视图(templates 文件夹)
twig:
default_path: '%kernel.project_dir%/templates'
# 表单使用 Bootstrap 5 的类绘制(见示例 18)
form_themes: ['bootstrap_5_layout.html.twig']
|
表单字段使用 [Bootstrap] 5 的类来绘制(示例 18)。
| # config/routes.yaml:路由由 src/Controller 文件夹中
# 控制器的 #[Route] 属性描述(见示例 01)
controllers:
resource: routing.controllers
|
路由由控制器的 [#[Route]] 属性描述(示例 01)。[php bin/console debug:router] 命令会列出所有路由(见下文 Web 层)。
11.7. 启动应用程序
11.7.1. public/index.php 和 bin/console
| <?php
// public/index.php:所有 HTTP 请求的入口点。[public] 文件夹
// 是站点的根目录:只有其中的文件可以从
// 浏览器访问(Bootstrap、样式表、脚本),绝不包括应用程序的代码。
//
// 文件 vendor/autoload_runtime.php 由 Symfony 的 Runtime 组件
// (symfony/runtime 库)写入:它加载类,读取
// .env 文件,启用调试模式,然后调用下面的函数,该函数返回
// 应用程序的内核;最后让内核处理当前请求,发送
// 响应,并结束请求(见示例的 index.php 文件)
use App\Kernel;
require_once dirname(__DIR__).'/vendor/autoload_runtime.php';
return function (array $context) {
return new Kernel($context['APP_ENV'], (bool) $context['APP_DEBUG']);
};
|
示例的入口点(示例 01)加载类、读取文件 [.env]、启用调试模式、创建内核、让它处理请求、发送响应,并终止请求。所有这些在这里都由 [Symfony] 的 [Runtime] 组件处理(第 14 行):这就是标准 [Symfony] 应用程序中 [public/index.php] 文件的形式。
- 第 14 行:由 [Composer] 写入的文件 [vendor/autoload_runtime.php](参见 [composer.json])会加载类加载器,然后执行包含它的脚本,在本例中是 [public/index.php],以获取其返回值:被包含的 [PHP] 文件可以像函数一样返回一个值([return]);
- 第 16–18 行:这个值是一个匿名函数,它接收应用程序的上下文 (环境变量,从 [.env] 中由 [Runtime] 组件读取)并返回内核。[Runtime] 组件处理其余的工作:[Request]、[handle]、[send] 和 [terminate] 对象。
这种做法的好处是,同一个 [index.php] 可以用于 [PHP-FPM] 之外的服务器。例如,使用 worker 模式的 [FrankenPHP] (参见关于作用域的一节),另一种“运行时”会把内核保留在内存中,并让它按顺序处理请求,而此文件无需改变。文件 [bin/console] 具有相同的结构:其函数负责命令的执行,围绕内核构建。
11.7.2. src/Kernel.php 和 config/services.yaml
| <?php
// src/Kernel.php:应用程序的内核(见示例 01)
namespace App;
use Symfony\Bundle\FrameworkBundle\Kernel\MicroKernelTrait;
use Symfony\Component\HttpKernel\Kernel as BaseKernel;
class Kernel extends BaseKernel
{
use MicroKernelTrait;
public function boot(): void
{
parent::boot();
// 时区:医疗机构所在的时区。它决定今天的日期(不能
// 预约过去的时间,见 src/Business/Dates.php)
date_default_timezone_set('Europe/Paris');
}
}
|
示例中的内核(示例 01),多了一个方法:
- 第 13–19 行:[boot] 在内核启动时、每个请求中都会被调用。它为 时区 设置 [PHP]。默认情况下,[PHP] 使用其配置中指定的时区([date.timezone],位于文件 [php.ini] 中),通常是协调世界时(UTC);然而,当前日期 用于一条业务规则:不得预约过去的时间。在巴黎,夏季的午夜到凌晨 2:00 之间,UTC 的日期仍然是前一天:因此以诊所所在的时区为准。
| # =========================================================================
# config/services.yaml:应用程序的服务(见示例 06)。src/ 文件夹中
# src/ 文件夹的类被声明给容器,容器按需创建它们,并
# 为每个类提供它所需的对象(依赖注入):
# 控制器接收 ApplicationModel,后者接收业务层,业务层接收
# DAO,DAO 接收 Doctrine 的实体管理器...
# 在一次请求期间,每个类只有一个对象。
# =========================================================================
services:
_defaults:
autowire: true
autoconfigure: true
App\:
resource: '../src/'
# 数据(DATA)对象,由代码(或 Doctrine)创建,绝不由
# 容器创建:它们不是服务
exclude:
- '../src/Entity/'
- '../src/Domain/'
- '../src/Views/'
- '../src/Kernel.php'
|
- 第 10–15 行:[src] 文件夹中的所有类都是由容器创建的服务,容器会向每个类提供其构造函数所请求的对象(示例 06)。这些服务是共享的:在整个请求中只有一个 [ApplicationModel]、一个 [BusinessService] 等(参见关于作用域的一章);
- 第 16–22 行:除了数据类:由 [Doctrine] 或业务层创建的实体、计算出的日历对象,以及由操作创建的视图模型。这些类被排除在外:它们不是服务。(其他数据类,如 [PersonData] 或 [Message],虽然被声明了,但由于没有人向容器请求它们,容器会自行丢弃它们。)
没有其他需要声明的内容:监听器([#[AsEventListener]])、控制器([#[Route]])、[Twig] 扩展、表单类型和认证器,都会被容器根据其属性或其父类识别([autoconfigure]),并据此进行配置。命令 [php bin/console debug:container App] 列出应用程序的服务。
11.8. 实体
[Doctrine] 实体(示例 28):每张表一个类,位于 [src/Entity] 文件夹中。
11.8.1. src/Entity/Role.php
| <?php
// src/Entity/Role.php:用户的三种角色(列 users.role):
// - ADMIN :管理员 - 预约 + 医生和客户的管理;
// - DOCTOR:医生 - 预订和取消预约;
// - USER :客户(患者)- 为自己预订,管理自己的账户。
// 一个“带值的”枚举(backed enum):每个成员都有一个值,即以原样
// 存储在数据库中的字符串;Role::from('ADMIN') 则反向转换。
namespace App\Entity;
enum Role: string
{
case ADMIN = 'ADMIN';
case DOCTOR = 'DOCTOR';
case USER = 'USER';
// Symfony 意义上的角色(见 config/packages/security.yaml):ROLE_ADMIN...
public function symfonyRole(): string
{
return 'ROLE_'.$this->value;
}
}
|
三个角色,列举如下 ([enum],[PHP] 8.1):这种类型的唯一可能取值就是它的各个枚举项:[Role::ADMIN]、[Role::DOCTOR], 和 [Role::USER]。类型为 [Role] 的变量不可能包含 ['ADMINN']:这个拼写错误会被检测出来。[enum Role: string] 声明了一个带值的枚举:每个枚举项都有一个值,在本例中是字符串。[Role::ADMIN->value] 等于 ['ADMIN'];[Role::from('ADMIN')] 返回对应的枚举项(对于未知值则抛出异常);[Role::tryFrom(...)] 在这种情况下返回 [null] 。枚举可以有方法:[symfonyRole()] (第 18–21 行)返回 由 [Symfony] 定义的角色,即 [ROLE_ADMIN]、[ROLE_DOCTOR] 或 [ROLE_USER] (示例 25)——即由 [access_control] 规则验证的那个角色。[$this] 在这里指代当前枚举项。
11.8.2. src/Entity/User.php
| <?php
// =========================================================================
// src/Entity/User.php:允许登录的用户(表 [users])。
// 每位医生和每位客户都有自己的账户(表 [doctors] 和
// [clients] 的列 [user],见 Person.php)。
//
// SQL 唯一性约束:unq_users_login(一个登录名只属于一个
// 账户)。它由脚本 database/dbrdvmedecins2.sql 创建;业务
// 层通过其名称识别它(见 src/Business/BusinessService.php)。
//
// PasswordAuthenticatedUserInterface:拥有(已哈希)密码的用户;
// 这是 Symfony 的哈希服务所期望的(见 AuthService)。
// =========================================================================
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
use Symfony\Component\Security\Core\User\PasswordAuthenticatedUserInterface;
#[ORM\Entity]
#[ORM\Table(name: 'users')]
class User implements PasswordAuthenticatedUserInterface
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
// 该行的版本号:乐观锁(见示例 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
#[ORM\Column(length: 30)]
private string $login,
// 已哈希的密码(bcrypt),绝不是密码本身
#[ORM\Column(length: 100)]
private string $password,
// 登录后显示的名称:"Marie PELISSIER"
#[ORM\Column(length: 40)]
private string $name,
// enumType:该列(文本)变为 Role,反之亦然
#[ORM\Column(length: 10, enumType: Role::class)]
private Role $role,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getLogin(): string
{
return $this->login;
}
public function getPassword(): string
{
return $this->password;
}
public function getName(): string
{
return $this->name;
}
public function getRole(): Role
{
return $this->role;
}
public function setLogin(string $login): void
{
$this->login = $login;
}
public function setPassword(string $hash): void
{
$this->password = $hash;
}
public function setName(string $name): void
{
$this->name = $name;
}
}
|
- 第 21–23 行:表 [users] 中的实体。它实现了安全组件的 [PasswordAuthenticatedUserInterface] 接口(示例 25):这正是密码哈希服务所期望的;
- 第 25–33 行:主键和版本,即乐观锁(示例 28);
- 第 35–48 行:其他列通过构造函数属性提升 (示例 03)在构造函数中声明:属性 [#[ORM\Column]] 既可以应用于被提升的参数,也可以应用于属性。[length] 指定 [VARCHAR] 列的长度。第 45 行:选项 [enumType] 会在读取时把列 [role] (文本)转换为 [Role] ,在写入时则反向转换:[$user->getRole()] 返回的是 [Role],绝不会是字符串;
- 第 50–93 行:getter 和三个 setter 方法。主键和版本没有 setter 方法:[Doctrine] 会负责让它们保持最新。
11.8.3. src/Entity/Person.php
| <?php
// =========================================================================
// src/Entity/Person.php:医生(表 [doctors])和客户
// (表 [clients])的共同点:称谓、姓、名,以及
// 关联的用户账户(列 [user])。
//
// 这两个表的列完全相同:它们只在这个抽象类中描述一次
// (“Person”永远不会被创建),Doctor
// 和 Client 继承自它;每个类只指定自己的表名。
// #[ORM\MappedSuperclass]:一个父类,其列就是继承它的
// 实体的列,但它自己没有表。
//
// 注意:这里的 [Client] 指的是医疗机构的患者(PATIENT),而不是 HTTP
// 客户端!这是原始业务领域的词汇,保持原样。
// =========================================================================
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\MappedSuperclass]
abstract class Person
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
protected ?int $id = null;
// 乐观锁(见示例 28)
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
protected int $version = 0;
public function __construct(
// Mr, Mme, Melle
#[ORM\Column(length: 5)]
protected string $title,
#[ORM\Column(name: 'last_name', length: 20)]
protected string $lastName,
#[ORM\Column(name: 'first_name', length: 20)]
protected string $firstName,
// -------------------------------------------------------------------
// 与用户账户的关系(RELATION):一个人员有一个账户,
// 由外键 [user] 指定。#[ORM\OneToOne]:每个
// 人员一个账户,每个账户一个人员;#[ORM\JoinColumn]:外键
// 的列(用反引号括起来:`user` 是 MySQL 的 SQL
// 语言中的一个词)。$doctor->getAccount() 返回一个 User 对象,在
// 首次访问时从数据库读取,或者如果查询要求,则立即读取(见 src/Dao)
// -------------------------------------------------------------------
#[ORM\OneToOne]
#[ORM\JoinColumn(name: '`user`', nullable: false)]
protected User $account,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getVersion(): int
{
return $this->version;
}
public function getTitle(): string
{
return $this->title;
}
public function getLastName(): string
{
return $this->lastName;
}
public function getFirstName(): string
{
return $this->firstName;
}
public function getAccount(): User
{
return $this->account;
}
public function edit(string $title, string $lastName, string $firstName): void
{
$this->title = $title;
$this->lastName = $lastName;
$this->firstName = $firstName;
}
// "Mme Alice DURAND"
public function label(): string
{
return "{$this->title} {$this->firstName} {$this->lastName}";
}
}
|
表 [doctors] 和 [clients]具有相同的列。它们共同的描述只写一次,放在一个抽象类([abstract class])中:这种类永远不会创建对象,仅用作继承的基类。类 [Doctor] 和 [Client]继承自它。
- 第 22 行:属性 [#[ORM\MappedSuperclass]] 使该类成为一个超类:它的列就是继承它的每个实体的列,但它自己没有表。([Doctrine] 也支持真正的实体层次结构,可以组织在单张表中或每个类一张表中:这里不属于这种情况,这里两张表是相互独立的。)这些属性是 [protected]:对子类可见;
- 第 51–53 行:与账户的关系 。[#[ORM\OneToOne]]:一个人拥有一个账户,一个账户至多属于一个人。[#[ORM\JoinColumn]] 指向外键列 [user],并确保它不为空([nullable: false])。列名用反引号括起来:[user] 是 [MySQL] 的 SQL 语言中的一个词,[Doctrine] 会在它所编写的 SQL 命令中以这种方式把它括起来(参见上面的控制台输出)。属性 [account]是一个 [User] 对象,而不是一个数字:这正是 ORM 的意义所在。当 [Doctrine] 读取一个人员时,如果请求需要,它也会读取其账户(懒加载;参见 DAO 层);否则,它会在该属性中放入一个惰性 [User] 对象(lazy),只有在第一次访问其某个属性时才会从数据库中读取——它已经知道的 ID 除外;
- 第 87–92 行:修改三个身份列;
- 第 95–98 行:一个人的姓名,“Alice DURAND 女士”,所有页面都会使用。在用引号括起来的字符串中,[{$this->title}] 会插入属性的值。
11.8.4. src/Entity/Doctor.php 和 Client.php
| <?php
// src/Entity/Doctor.php:一位医生(表 [doctors])。
// SQL 唯一性约束:unq_doctors_first_name_last_name(两位医生不能
// 有相同的名和姓)。
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'doctors')]
class Doctor extends Person
{
}
|
| <?php
// src/Entity/Client.php:一位客户,即一位患者(PATIENT)(表 [clients])。
// SQL 唯一性约束:unq_clients_first_name_last_name。
namespace App\Entity;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'clients')]
class Client extends Person
{
}
|
两个只指定其表的实体:其他一切都是继承而来的。[Client] 是诊所的患者 ,而不是 HTTP 客户端:这是原始的业务领域词汇,在应用程序的所有版本中都得到了保留。
11.8.5. src/Entity/Slot.php
| <?php
// src/Entity/Slot.php:医生的一个时间段(表 [slots]):
// 8:00 - 8:20 等。时间段由 SQL 脚本创建:应用程序
// 只读取它们。
namespace App\Entity;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'slots')]
class Slot
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
// 同一位医生有多个时间段:#[ORM\ManyToOne],通过外键
// [doctor_id]
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'doctor_id', nullable: false)]
private Doctor $doctor;
#[ORM\Column(name: 'start_hour')]
private int $startHour;
#[ORM\Column(name: 'start_minute')]
private int $startMinute;
#[ORM\Column(name: 'end_hour')]
private int $endHour;
#[ORM\Column(name: 'end_minute')]
private int $endMinute;
public function getId(): ?int
{
return $this->id;
}
public function getDoctor(): Doctor
{
return $this->doctor;
}
// "8:00 - 8:20";sprintf('%02d'):是 "8:05" 而不是 "8:5"
public function time(): string
{
return sprintf('%d:%02d - %d:%02d', $this->startHour, $this->startMinute, $this->endHour, $this->endMinute);
}
}
|
- 第 26–28 行:时间段与医生的关系。[#[ORM\ManyToOne]]:同一位医生有多个时间段,通过外键 [doctor_id] 关联;
- 第 30–40 行:开始和结束的小时与分钟。时间段由 SQL 脚本创建:该类没有构造函数,[Doctrine] 会自行填充其属性;
- 第 53–56 行:时间范围,“8:00 – 8:20”。[%02d] 格式(属于 [sprintf] )会写出用零补足的两位整数:[8:05] 而不是 [8:5]。
11.8.6. src/Entity/Appointment.php
| <?php
// src/Entity/Appointment.php:一个预约(表 [appointments]):某位客户,在某个时间段,
// 在某一天。
// SQL 唯一性约束:unq1_appointments (day, slot_id) - 一个时间段每天
// 只能被预订一次。由 SQL 脚本创建,由业务层
// 通过其名称识别。
namespace App\Entity;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\Mapping as ORM;
#[ORM\Entity]
#[ORM\Table(name: 'appointments')]
class Appointment
{
#[ORM\Id]
#[ORM\GeneratedValue]
#[ORM\Column]
private ?int $id = null;
#[ORM\Version]
#[ORM\Column(type: Types::INTEGER)]
private int $version = 0;
public function __construct(
// date_immutable 类型:列 [day](SQL 类型 DATE)变为日期
// DateTimeImmutable,时间为午夜;它以 yyyy-mm-dd 格式写入数据库
#[ORM\Column(type: Types::DATE_IMMUTABLE)]
private DateTimeImmutable $day,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'slot_id', nullable: false)]
private Slot $slot,
#[ORM\ManyToOne]
#[ORM\JoinColumn(name: 'client_id', nullable: false)]
private Client $client,
) {
}
public function getId(): ?int
{
return $this->id;
}
public function getDay(): DateTimeImmutable
{
return $this->day;
}
public function getSlot(): Slot
{
return $this->slot;
}
public function getClient(): Client
{
return $this->client;
}
}
|
- 第 30–31 行:列 [day](SQL 类型 [DATE])会被转换为午夜时刻的 [DateTimeImmutable] (类型 [Doctrine] [date_immutable])。不可变:它的方法绝不会修改对象本身;它们会返回一个新对象([$day->modify('+1 day')] 返回第二天,[$day] 保持不变)。整个应用程序都使用不可变日期:多个对象共享的日期,不会被其中某一个对象在其他对象不知情的情况下修改;
- 第 32–37 行:两个关系,一个指向时间段,一个指向预约的客户。
11.9. 领域:日历
11.9.1. src/Domain/DoctorDaySlot.php 和 DoctorDaySchedule.php
| <?php
// src/Domain/DoctorDaySlot.php:一个时间段,以及在某一天
// 可能在该时间段上预订的预约(如果时间段空闲则为 null)。
// 一个计算得出的“业务”对象,与任何表都不对应。
//
// readonly:属性由构造函数一次性设定 -
// 这正是计算得出的对象所需要的,之后没有人会修改它。
namespace App\Domain;
use App\Entity\Slot;
use App\Entity\Appointment;
readonly class DoctorDaySlot
{
public function __construct(
public Slot $slot,
public ?Appointment $appointment,
) {
}
}
|
| <?php
// src/Domain/DoctorDaySchedule.php:一位医生在某一天的
// 完整日程,即其时间段的列表,每个时间段要么空闲要么已被占用。由
// BusinessService::getDoctorDaySchedule 计算,由
// ScheduleController 转换为 HTML 表格。
namespace App\Domain;
use App\Entity\Doctor;
use DateTimeImmutable;
readonly class DoctorDaySchedule
{
/** @param list<DoctorDaySlot> $doctorDaySlots */
public function __construct(
public Doctor $doctor,
public DateTimeImmutable $day,
public array $doctorDaySlots,
) {
}
}
|
两个不对应任何表的计算对象:某一天的一个时间段及其可能存在的预约;一位医生某一天的日历,列出其可用的时间段。它们是 [readonly] 类(示例 03),其属性在构造函数中声明。注释 [/** @param list<DoctorDaySlot> ... */] 指明了数组的内容:[PHP] 无法确定数组内容的类型,但编辑器([PHP Intelephense])和分析工具会读取这些注释,它们被称为 [PHPDoc]。
11.10. DAO 层
DAO 层(示例 28)把查询集中在一起:每张表一个类,不含业务逻辑。其方法不启动事务;业务层在自己的事务中调用它们。它们用 DQL (示例 28)编写,或使用 查询构建器 ,位于 [Doctrine] 中,它通过方法调用生成 DQL 查询;其中的值是查询参数:不可能发生 SQL 注入。
11.10.1. src/Dao/PersonDao.php
| <?php
// =========================================================================
// src/Dao/PersonDao.php:医生和客户共用的 DAO 层。
//
// 医生和客户的 DAO 本来是相同的:这个抽象类
// 只写一次。$this->entityClass 是相关实体的类
// (Doctor::class 或 Client::class):DQL 查询针对的是它的表。
//
// 查询用 DQL 编写,即 Doctrine 的查询语言(见
// 示例 28),由 Doctrine 将其翻译为 SQL。值(名、姓...)是
// 查询的参数(:firstName):没有字符串拼接,因此没有
// SQL 注入。这些方法不开启任何事务:调用它们的是
// 业务层,在它自己的事务内部调用。
// =========================================================================
namespace App\Dao;
use App\Entity\Person;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\QueryBuilder;
abstract class PersonDao
{
/** @param class-string<Person> $entityClass */
public function __construct(protected EntityManagerInterface $em, protected string $entityClass)
{
}
// -----------------------------------------------------------------------
// 针对该类的表的查询,包含用户账户。Doctrine 的
// 查询构建器(createQueryBuilder)构建 DQL 查询
// 通过方法调用来完成:
// SELECT p, a FROM App\Entity\Doctor p JOIN p.account a
// JOIN p.account a:与 [users] 表的 SQL 连接;SELECT p, a:账户
// 由同一个查询一并加载。没有它,每次访问
// $person->getAccount() 都会触发它自己的查询
// -----------------------------------------------------------------------
protected function query(): QueryBuilder
{
return $this->em->createQueryBuilder()
->select('p', 'a')
->from($this->entityClass, 'p')
->join('p.account', 'a');
}
// 按姓再按名排序的列表
/** @return list<Person> */
public function list(): array
{
return $this->query()->orderBy('p.lastName')->addOrderBy('p.firstName')->getQuery()->getResult();
}
// 一个人员及其账户;如果不存在则为 null
public function read(int $id): ?Person
{
return $this->query()->where('p.id = :id')->setParameter('id', $id)
->getQuery()->getOneOrNullResult();
}
// 用户账户为 [$userId] 的人员
public function readByUser(int $userId): ?Person
{
return $this->query()->where('a.id = :userId')->setParameter('userId', $userId)
->getQuery()->getOneOrNullResult();
}
// 具有这些名和姓的人员(如果有的话)。比较
// 由 MySQL 完成,因此使用数据库的排序规则(utf8mb4_unicode_ci:不区分
// 大小写和重音)- 与 SQL 唯一性约束的规则
// 完全相同
public function namesake(string $firstName, string $lastName): ?Person
{
return $this->query()->where('p.firstName = :firstName')->andWhere('p.lastName = :lastName')
->setParameter('firstName', $firstName)->setParameter('lastName', $lastName)
->setMaxResults(1)->getQuery()->getOneOrNullResult();
}
// 该人员将在下一次 flush(业务层事务的 flush)时被插入;
// 数据库将生成其 id,Doctrine 会将其存储在对象中
public function add(Person $person): void
{
$this->em->persist($person);
}
// 该人员将在下一次 flush 时被删除
public function remove(Person $person): void
{
$this->em->remove($person);
}
}
|
医生和客户共用的 DAO 层,在一个抽象类中只实现一次。
- 第 25 行:构造函数接收实体管理器(示例 28)和相关的类,[Doctor::class] 或 [Client::class] (表示完整类名的字符串)。注释 [@param class-string<Person>] 向开发者说明了这一点。服务容器不知道该提供哪个字符串:是子类调用这个构造函数;
- 第 38–44 行:一个同时也加载所读取用户账户的查询。[createQueryBuilder] 创建一个查询构建器;[select('p', 'a')]、[from($this->entityClass, 'p')], 和 [join('p.account', 'a')] 写出 DQL 查询 [SELECT p, a FROM App\Entity\Doctor p JOIN p.account a]。连接([JOIN])沿着实体的关系 [account]进行:[Doctrine] 推导出 SQL 条件([ON d0_.user = u1_.id])。对两个别名执行的 [SELECT] 要求对账户进行预先加载 :一次查询就能取回人员及其账户。否则,管理员所看到的医生列表会在第一次访问 [$doctor->getAccount()->getLogin()] 时,为每位医生触发一次查询:这就是所谓的“N + 1 查询”问题。另一个原因:医生和客户的列表存储在缓存中([ApplicationModel],稍后讨论);添加到缓存中的对象必须是完整的;
- 第 48–51 行:列表按姓再按名排序([orderBy],然后是 [addOrderBy]:第二个排序条件;第二个 [orderBy] 会替换第一个)。[getQuery()] 返回 DQL 查询;[getResult()] 执行它并返回实体数组;
- 第 54–58 行:[where] 使用具名参数([:id])添加条件,其值由 [setParameter] 提供。[getOneOrNullResult] 返回找到的唯一实体,或 [null];
- 第 61–65 行:账户为 [$userId] 的人员,条件基于所关联账户的 ID;
- 第 71–76 行:名和姓相同的人员。[andWhere] 添加第二个条件(第二个 [where] 会替换第一个)。比较由 [MySQL] 使用数据库的排序规则执行:不区分大小写并忽略重音,与唯一性约束完全一样(示例 28);
- 第 80–89 行:插入和删除,它们将由 [flush] 作为业务层事务的一部分发送到数据库(示例 28)。
没有更新方法:业务层修改所读取的实体,[Doctrine] 会在 [flush] 时发送 [UPDATE] (变更跟踪,示例 28),并使用乐观锁。
11.10.2. src/Dao/DoctorDao.php 和 ClientDao.php
| <?php
// src/Dao/DoctorDao.php:医生的 DAO - 一切都继承自 PersonDao。
namespace App\Dao;
use App\Entity\Doctor;
use Doctrine\ORM\EntityManagerInterface;
class DoctorDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Doctor::class);
}
}
|
一切都是继承的:构造函数接收容器的实体管理器,并将其与实体类一起传给 [PersonDao] ([parent::__construct] 调用父类的构造函数)。
| <?php
// src/Dao/ClientDao.php:客户的 DAO - 即人员的 DAO,外加一个
// 加锁方法。
namespace App\Dao;
use App\Entity\Client;
use Doctrine\DBAL\LockMode;
use Doctrine\ORM\EntityManagerInterface;
class ClientDao extends PersonDao
{
public function __construct(EntityManagerInterface $em)
{
parent::__construct($em, Client::class);
}
// -----------------------------------------------------------------------
// 在当前事务结束之前,对某位客户的行加锁(LOCK)
// (SELECT ... FOR UPDATE),并返回其 id(如果客户不
// 存在则为 null)。请求同一把锁的第二个事务会等待,直到
// 第一个事务完成。LockMode::PESSIMISTIC_WRITE:Doctrine 的“悲观”
// 锁,需要一个已打开的事务。
// 用于预订(见 BusinessService::addAppointment):同一位患者的两次
// 同时预订因此会一个接一个地处理,
// 并且第二个能看到第一个创建的预约。
// -----------------------------------------------------------------------
public function lock(int $id): ?int
{
$row = $this->em->createQuery('SELECT c.id FROM App\Entity\Client c WHERE c.id = :id')
->setParameter('id', $id)
->setLockMode(LockMode::PESSIMISTIC_WRITE)
->getOneOrNullResult();
return $row['id'] ?? null;
}
}
|
- 第 28–35 行:悲观锁,即另一种类型的锁。[setLockMode(LockMode::PESSIMISTIC_WRITE)] 会向查询添加 [FOR UPDATE] :[SELECT c0_.id AS id_0 FROM clients c0_ WHERE c0_.id = ? FOR UPDATE]。所读取的行会被锁定 ,直到当前事务结束:另一个请求相同锁的事务会等待 第一个事务完成。[Doctrine] 不允许在事务之外使用这种锁。该查询只读取 ID([SELECT c.id]):其结果不是实体,而是一个关联数组([['id' => 3]]),或 [null]。我们将在业务层中看到这种锁的用途。
11.10.3. src/Dao/SlotDao.php
| <?php
// src/Dao/SlotDao.php:时间段的 DAO 层。
namespace App\Dao;
use App\Entity\Slot;
use Doctrine\ORM\EntityManagerInterface;
class SlotDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// 一个时间段及其医生
public function read(int $id): ?Slot
{
return $this->em->createQuery(
'SELECT s, d FROM App\Entity\Slot s JOIN s.doctor d WHERE s.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// 医生的时间段,按时间顺序排列。s.doctor = :doctorId:
// 与 id(即外键的 id)比较的关联
/** @return list<Slot> */
public function listByDoctor(int $doctorId): array
{
return $this->em->createQuery(
'SELECT s FROM App\Entity\Slot s WHERE s.doctor = :doctorId ORDER BY s.startHour, s.startMinute')
->setParameter('doctorId', $doctorId)->getResult();
}
// 删除医生的所有时间段(删除医生时):一个
// DQL DELETE 查询,立即执行:
// DELETE FROM slots WHERE doctor_id = ?
public function deleteByDoctor(int $doctorId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)->execute();
}
}
|
一个预约时间段及其医生(预先加载);一位医生的预约时间段,按时间顺序排列:[s.doctor = :doctorId] 把一个关系与一个 ID 进行比较——即外键的 ID;以及用 DQL 编写的 [DELETE] ,立即执行([execute()]),无需先读取各行。
11.10.4. src/Dao/AppointmentDao.php
| <?php
// =========================================================================
// src/Dao/AppointmentDao.php:预约的 DAO 层。
//
// [appointments] 表不直接引用医生:我们通过时间段
// (JOIN a.slot s ... WHERE s.doctor = ...)。
// 日期连同其类型一起传递(Types::DATE_IMMUTABLE):Doctrine
// 以数据库的格式 yyyy-mm-dd 写入它们。
// =========================================================================
namespace App\Dao;
use App\Entity\Appointment;
use DateTimeImmutable;
use Doctrine\DBAL\Types\Types;
use Doctrine\ORM\EntityManagerInterface;
class AppointmentDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// 一个预约、其客户及其时间段
public function read(int $id): ?Appointment
{
return $this->em->createQuery(
'SELECT a, c, s FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s WHERE a.id = :id')
->setParameter('id', $id)->getOneOrNullResult();
}
// 医生在某一天的预约,连同其客户
/** @return list<Appointment> */
public function doctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->em->createQuery(
'SELECT a, c FROM App\Entity\Appointment a JOIN a.client c JOIN a.slot s
WHERE a.day = :day AND s.doctor = :doctorId')
->setParameter('day', $day, Types::DATE_IMMUTABLE)
->setParameter('doctorId', $doctorId)
->getResult();
}
// -----------------------------------------------------------------------
// 客户从日期 [$since](含)起的预约,按时间
// 顺序排列,连同该时间段及该时间段的医生(两次连接:
// JOIN a.slot s JOIN s.doctor d,以及 SELECT a, s, d)
// -----------------------------------------------------------------------
/** @return list<Appointment> */
public function clientUpcomingAppointments(int $clientId, DateTimeImmutable $since): array
{
return $this->em->createQuery(
'SELECT a, s, d FROM App\Entity\Appointment a JOIN a.slot s JOIN s.doctor d
WHERE a.client = :clientId AND a.day >= :since
ORDER BY a.day, s.startHour, s.startMinute')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getResult();
}
// 客户从日期 [$since](含)起的预约数量;
// getSingleScalarResult:结果唯一一行中的唯一值
public function countClientUpcoming(int $clientId, DateTimeImmutable $since): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a WHERE a.client = :clientId AND a.day >= :since')
->setParameter('clientId', $clientId)
->setParameter('since', $since, Types::DATE_IMMUTABLE)
->getSingleScalarResult();
}
// 医生的预约数量(过去或未来)
public function countByDoctor(int $doctorId): int
{
return (int) $this->em->createQuery(
'SELECT COUNT(a.id) FROM App\Entity\Appointment a JOIN a.slot s WHERE s.doctor = :doctorId')
->setParameter('doctorId', $doctorId)
->getSingleScalarResult();
}
// 该预约将在下一次 flush 时被插入
public function add(Appointment $appointment): void
{
$this->em->persist($appointment);
}
public function remove(Appointment $appointment): void
{
$this->em->remove($appointment);
}
// 立即删除客户的所有预约(过去和未来)
public function deleteByClient(int $clientId): void
{
$this->em->createQuery('DELETE FROM App\Entity\Appointment a WHERE a.client = :clientId')
->setParameter('clientId', $clientId)->execute();
}
}
|
表 [appointments]并不直接引用医生:它通过时间段来关联。
- 第 34–42 行:一位医生某一天的预约及其客户。两次连接:一次([a.client c])用于加载客户([SELECT a, c]),另一次([a.slot s])用于按医生过滤。[setParameter] 的第三个参数指定值的类型,即 [Doctrine]:此时 [DateTimeImmutable] 会以列的格式 [DATE]、[yyyy-mm-dd] 写入;
- 第 50–59 行:一位患者即将到来的预约,包括其时间段以及分配给该时间段的医生:[JOIN s.doctor d] 沿着关系进行。排序同样基于时间段,即来自另一张表的列:连接使这一点成为可能;
- 第 63–79 行:计数。[COUNT(a.id)] 统计预约数;[getSingleScalarResult] 返回结果中单行的单个值(一个字符串,由 [(int)] 转换为整数);
- 第 93–97 行:使用 DQL 删除某个客户的所有预约。
11.10.5. src/Dao/UserDao.php
| <?php
// src/Dao/UserDao.php:用户账户的 DAO 层。创建(或删除)
// 医生或客户时,也会创建(或删除)其账户 - 见 src/Business。
// 被修改的账户通过其方法(setLogin...)进行修改:Doctrine 会在下一次 flush 时
// 发送 UPDATE(变更跟踪,见示例 28)。
namespace App\Dao;
use App\Entity\User;
use Doctrine\ORM\EntityManagerInterface;
class UserDao
{
public function __construct(private EntityManagerInterface $em)
{
}
// 如果没有用户具有该登录名则为 null;findOneBy:该实体的仓库
// 查找其列具有这些值的行
public function readByLogin(string $login): ?User
{
return $this->em->getRepository(User::class)->findOneBy(['login' => $login]);
}
public function add(User $user): void
{
$this->em->persist($user);
}
public function remove(User $user): void
{
$this->em->remove($user);
}
}
|
账户:按登录名检索,并存储 实体(示例 28):[findOneBy(criteria)] 返回符合条件的唯一实体,或 [null];以及添加和删除。
11.11. 业务层
业务层集中了业务规则和事务(示例 28)。它由一个接口描述,并由两个类实现:[BusinessService],即业务层本身,以及 [ApplicationModel],即 Web 层缓存(稍后讨论)。
11.11.1. src/Business/Dates.php
| <?php
// src/Business/Dates.php:今天的日期。它被业务规则(不能
// 预订过去的时间,每位患者只能有一个即将到来的预约)使用:
// 因此它位于业务层。Web 层会复用它。
namespace App\Business;
use DateTimeImmutable;
class Dates
{
// 今天的午夜,使用应用程序的时区(见 src/Kernel.php)
public static function today(): DateTimeImmutable
{
return new DateTimeImmutable('today');
}
}
|
当前日期的午夜时刻(['today']),采用应用程序的时区(参见 [src/Kernel.php])。它用于业务规则(不得预约过去的时间,只能有一个即将到来的预约):因此它位于业务层。静态方法([static])无需创建对象即可调用:[Dates::today()]。
11.11.2. src/Business/BusinessException.php
| <?php
// =========================================================================
// src/Business/BusinessException.php:业务层在违反
// 业务规则(登录名已被占用、医生仍有
// 预约、时间段已被预订...)时抛出的异常。它不携带文本,而是携带一个
// 翻译键(例如 "ERRORS.LOGIN_TAKEN"):由 Web 层在显示页面时
// 将其翻译为法语或英语(见 translations)。
//
// BusinessException 不是异常情况:它是一个正常的答复(“此登录名
// 已被占用”),会显示给用户。任何其他异常都是真正的
// 异常情况,最终会出现在 500 错误页面上。
// =========================================================================
namespace App\Business;
use RuntimeException;
use Throwable;
class BusinessException extends RuntimeException
{
public function __construct(
// 消息的翻译键
public readonly string $key,
// 消息可能的参数({minutes}...)
public readonly array $params = [],
?Throwable $previous = null,
) {
parent::__construct($key, 0, $previous);
}
}
|
违反业务规则时抛出的异常。它携带的不是文本,而是一个翻译键 ([ERRORS.LOGIN_TAKEN])及其参数:Web 层会把它翻译成页面所用的语言(示例 22)。业务层对界面语言一无所知。[RuntimeException] 是 [PHP] 的一个子类。构造函数的属性 [public readonly] 由构造函数属性提升声明并初始化(示例 03);[parent::__construct($key, 0, $previous)] 调用 [RuntimeException] 的构造函数,传入消息、代码和前一个异常(即导致本异常的那个异常——例如数据库错误:它会和新异常一起出现在日志中)。
11.11.3. src/Business/PersonData.php
| <?php
// src/Business/PersonData.php:在“医生”或“客户”表单中输入的数据,
// 由 Web 层传递给业务层。
namespace App\Business;
readonly class PersonData
{
public function __construct(
public string $title, // Mr, Mme, Melle
public string $lastName,
public string $firstName,
// 创建:可选(null),默认为小写的姓
// 修改:可选,如果缺失则登录名保持不变
public ?string $login = null,
// 创建:可选,默认为登录名
// 修改:可选,如果缺失则密码保持不变
public ?string $password = null,
// 修改:显示表单时记录的版本
// (乐观锁)
public ?int $version = null,
) {
}
}
|
来自“人员”表单的数据,由 Web 层传递给业务层:一个名为 [readonly] 的类。登录名、密码和版本是可选的([?string]、[?int],默认值 [null]);注释说明了它们缺失时的含义。
11.11.4. src/Business/Business.php
| <?php
// =========================================================================
// src/Business/Business.php:业务层的契约:读取、日程、
// 预约、医生和客户的管理。
//
// 接口(INTERFACE)描述类必须具有的方法,而不说明
// 这些方法如何编写。BusinessService(业务层)和 ApplicationModel(Web 层
// 的缓存)都实现了它;PHP 在加载类时会检查
// 是否缺少任何方法。
//
// ?Type:可能缺失的结果(null:不存在的医生...)。
// list<Doctor>(在文档注释中):以 0、1、2... 为索引的医生数组
// =========================================================================
namespace App\Business;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use DateTimeImmutable;
interface Business
{
// ———————————————— 读取
/** @return list<Client> */
public function getAllClients(): array;
/** @return list<Doctor> */
public function getAllDoctors(): array;
/** @return list<Slot> */
public function getAllSlots(int $doctorId): array;
/** @return list<Appointment> */
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array;
public function getClientById(int $id): ?Client;
public function getDoctorById(int $id): ?Doctor;
public function getAppointmentById(int $id): ?Appointment;
public function getSlotById(int $id): ?Slot;
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule;
// 用户账户为 [$userId] 的客户(患者)
public function getClientByUserId(int $userId): ?Client;
// 客户的预约,今天的或未来的,包含时间段和医生
/** @return list<Appointment> */
public function getClientUpcomingAppointments(int $clientId): array;
// ———————————————— 预约(ADMIN、DOCTOR、USER)
// 在以下情况抛出 BusinessException:
// - 日期已过去("ERRORS.PAST_DATE");
// - 患者已有一个即将到来的预约("ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT");
// - 该时间段在当天已被占用("ERRORS.SLOT_ALREADY_BOOKED")。
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment;
public function deleteAppointment(Appointment $appointment): void;
// ———————————————— 医生(ADMIN)
// 创建医生及其用户账户(角色 DOCTOR)
public function addDoctor(PersonData $data): Doctor;
// 修改医生及其用户账户
public function editDoctor(int $id, PersonData $data): Doctor;
// 删除医生、其时间段及其账户 - 如果有预约则拒绝
public function deleteDoctor(int $id): void;
// ———————————————— 客户
// (ADMIN;addClient 也用于患者的注册,
// editClient 和 deleteClient 由患者用于其自己的账户)
// 创建客户及其用户账户(角色 USER)
public function addClient(PersonData $data): Client;
public function editClient(int $id, PersonData $data): Client;
// 删除客户、其账户及其所有预约(过去和未来)
public function deleteClient(int $id): void;
}
|
业务层的契约:一个接口 (示例 06),即方法列表,不含代码。读取操作返回实体或实体数组(注释 [@return list<Client>] 指明了其内容);[?Client]:一个客户,或者如果它不存在则为 [null] 。注释说明了每个写入操作的规则,以及它可能抛出的 [BusinessException] 的键。
11.11.5. src/Business/Descriptor.php
| <?php
// src/Business/Descriptor.php:业务规则中区分医生和客户的一切内容
// (见 BusinessService)。医生和客户遵循
// 相同的规则:公共代码只写一次,并由一个描述符来参数化。
namespace App\Business;
use App\Dao\PersonDao;
use App\Entity\Role;
use Closure;
readonly class Descriptor
{
public function __construct(
public PersonDao $dao,
public Role $role, // DOCTOR 或 USER
// 用于创建人员的实体类:Doctor::class 或 Client::class
public string $entityClass,
public string $notFoundKey, // 人员不存在时的消息
public string $alreadyExistsKey, // 相同的名和姓已存在时的消息
// 可选(null):如果存在,则只要该人员仍有预约
// (countAppointments(id) > 0),就拒绝删除,并给出 hasAppointmentsKey 消息
public ?Closure $countAppointments,
public ?string $hasAppointmentsKey,
// 可选:必须在人员之前删除的内容(通过外键
// 引用该人员的行);接收其 id
public ?Closure $beforeDelete,
) {
}
}
|
医生和客户遵循相同的管理规则,只有少数细微差别:DAO、账户角色、要创建的实体类、错误消息和删除规则。这个描述符 把这些细节整合在一起;公共代码读取它们。有两个属性是函数 ([?Closure]:一个函数,或 [null]):预约计数(用于阻止删除,仅限医生),以及删除对该人员的引用。
11.11.6. src/Business/BusinessService.php
| <?php
// =========================================================================
// src/Business/BusinessService.php:业务层的实现。
//
// 医生和客户的管理遵循三条业务规则:
//
// 1. 人员(医生或客户)及其用户账户始终是
// 一体的:它们在同一个
// 事务中一起创建、修改和删除 - 要么全部成功,要么什么都不写入;
// 2. 登录名在整个应用程序中是唯一的,两位医生(或两位
// 客户)不能有相同的名和姓;
// 3. 删除:
// - 有预约的医生不能被删除(其患者
// 会在未被通知的情况下失去预约):必须先
// 取消这些预约。其时间段会随之消失;
// - 而客户则会连同其所有预约(过去和未来)一起消失 -
// 无论删除来自管理员还是患者本人。
//
// 以及预订的两条规则,无论预订者的角色是什么
// (ADMIN、DOCTOR 或患者本人):
// 4. 不能预约过去的时间;
// 5. 一位患者同一时间只能有一个即将到来的预约。
//
// 医生和客户遵循完全相同的规则:公共代码
// 只写一次(私有方法 xxxPerson),并由一个描述符来参数化,
// 该描述符说明我们处理的是哪种类型的人员。
//
// 事务由 transaction 方法开启(在文件末尾),
// 该方法还会把数据库报告的错误转换为 BusinessException。
// =========================================================================
namespace App\Business;
use App\Dao\ClientDao;
use App\Dao\SlotDao;
use App\Dao\DoctorDao;
use App\Dao\AppointmentDao;
use App\Dao\UserDao;
use App\Domain\DoctorDaySchedule;
use App\Domain\DoctorDaySlot;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Person;
use App\Entity\Role;
use App\Entity\Appointment;
use App\Entity\User;
use Closure;
use DateTimeImmutable;
use Doctrine\DBAL\Exception\UniqueConstraintViolationException;
use Doctrine\ORM\EntityManagerInterface;
use Doctrine\ORM\OptimisticLockException;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Symfony\Component\PasswordHasher\PasswordHasherInterface;
class BusinessService implements Business
{
// -----------------------------------------------------------------------
// 数据库错误 -> BusinessException
//
// 当 UNIQUE 约束拒绝某次写入时,Doctrine 会抛出
// UniqueConstraintViolationException,其消息来自 MySQL。它
// 引用了约束的名称:
// Duplicate entry 'Marie-PELISSIER' for key 'doctors.unq_doctors_first_name_last_name'
// (MySQL 8 会在名称前加上表名,MariaDB 不会)。这就是为什么
// SQL 脚本为其所有约束命名。
// -----------------------------------------------------------------------
private const CONSTRAINT_MESSAGES = [
'unq_users_login' => 'ERRORS.LOGIN_TAKEN',
'unq_doctors_first_name_last_name' => 'ERRORS.DOCTOR_ALREADY_EXISTS',
'unq_clients_first_name_last_name' => 'ERRORS.PATIENT_ALREADY_EXISTS',
'unq1_appointments' => 'ERRORS.SLOT_ALREADY_BOOKED',
];
private const CONSTRAINT = "/for key '(?:[^'.]*\\.)?([^']+)'/";
private Descriptor $doctor;
private Descriptor $client;
// 密码的哈希(bcrypt,见 config/packages/security.yaml)
private PasswordHasherInterface $hasher;
// 所有依赖都由 Symfony 的服务容器提供
// (依赖注入,见示例 06)
public function __construct(
private EntityManagerInterface $em,
private DoctorDao $doctors,
private ClientDao $clients,
private SlotDao $slots,
private AppointmentDao $appointments,
private UserDao $users,
PasswordHasherFactoryInterface $hashers,
) {
$this->hasher = $hashers->getPasswordHasher(User::class);
$this->doctor = new Descriptor(
dao: $doctors,
role: Role::DOCTOR,
entityClass: Doctor::class,
notFoundKey: 'ERRORS.DOCTOR_NOT_FOUND',
alreadyExistsKey: 'ERRORS.DOCTOR_ALREADY_EXISTS',
// $appointments->countByDoctor(...):方法本身,作为 Closure
// (即所谓的“first-class callable”语法)
countAppointments: $appointments->countByDoctor(...),
hasAppointmentsKey: 'ERRORS.DOCTOR_HAS_APPOINTMENTS',
// 没有预约的医生可能仍然有时间段:
// 没有医生,时间段就没有意义,它们会随医生一起被删除(否则
// 外键 slots.doctor_id 会禁止删除)
beforeDelete: $slots->deleteByDoctor(...));
$this->client = new Descriptor(
dao: $clients,
role: Role::USER,
entityClass: Client::class,
notFoundKey: 'ERRORS.PATIENT_NOT_FOUND',
alreadyExistsKey: 'ERRORS.PATIENT_ALREADY_EXISTS',
// 没有 countAppointments:客户的删除从不会被拒绝;
// 其预约(过去和未来)会随其一起被删除(否则
// 外键 appointments.client_id 会禁止删除)
countAppointments: null,
hasAppointmentsKey: null,
beforeDelete: $appointments->deleteByClient(...));
}
// =======================================================================
// 读取
// =======================================================================
public function getAllClients(): array
{
return $this->clients->list();
}
public function getAllDoctors(): array
{
return $this->doctors->list();
}
public function getAllSlots(int $doctorId): array
{
return $this->slots->listByDoctor($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->appointments->doctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->clients->read($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->doctors->read($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->appointments->read($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->slots->read($id);
}
public function getClientByUserId(int $userId): ?Client
{
return $this->clients->readByUser($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->appointments->clientUpcomingAppointments($clientId, Dates::today());
}
// 医生在某一天的日程:其时间段,以及每个时间段在当天
// 被预订的预约(如果空闲则为 null)
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
$doctor = $this->getDoctorById($doctorId);
if ($doctor === null) {
return null;
}
// 时间段编号 -> 在该时间段上预订的预约
$bookings = [];
foreach ($this->getDoctorDayAppointments($doctorId, $day) as $appointment) {
$bookings[$appointment->getSlot()->getId()] = $appointment;
}
// array_map:对每个时间段应用该函数,并返回结果数组
$doctorDaySlots = array_map(
fn (Slot $slot) => new DoctorDaySlot($slot, $bookings[$slot->getId()] ?? null),
$this->getAllSlots($doctorId));
return new DoctorDaySchedule($doctor, $day, $doctorDaySlots);
}
// =======================================================================
// 预约
// =======================================================================
// -----------------------------------------------------------------------
// 预订,在事务中:
// 1. 不能预约过去的时间;
// 2. 我们对患者的行加锁(SELECT ... FOR UPDATE):如果同一位
// 患者在同一时刻预订两个时间段(两个标签页、双
// 击...),第二个事务会等待第一个结束 - 然后会看到
// 它刚刚创建的预约;
// 3. 每位患者只能有一个即将到来的预约;
// 4. 最后是插入。如果该时间段刚刚被另一位患者占用,
// 则由 SQL 约束 unq1_appointments (day, slot_id) 拒绝
// 插入 - 由 transaction() 转换为 BusinessException。
// -----------------------------------------------------------------------
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->transaction(function () use ($day, $slot, $client) {
$today = Dates::today();
if ($day < $today) {
throw new BusinessException('ERRORS.PAST_DATE');
}
$patientId = $this->clients->lock($client->getId())
?? throw new BusinessException('ERRORS.PATIENT_NOT_FOUND');
if ($this->appointments->countClientUpcoming($patientId, $today) > 0) {
throw new BusinessException('ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT');
}
$appointment = new Appointment($day, $slot, $client);
$this->appointments->add($appointment);
return $appointment;
});
}
public function deleteAppointment(Appointment $appointment): void
{
$this->transaction(fn () => $this->appointments->remove($appointment));
}
// =======================================================================
// 医生和客户 - 公共方法委托给共同的私有
// 方法,并使用相应的描述符
// =======================================================================
public function addDoctor(PersonData $data): Doctor
{
return $this->addPerson($this->doctor, $data);
}
public function editDoctor(int $id, PersonData $data): Doctor
{
return $this->editPerson($this->doctor, $id, $data);
}
public function deleteDoctor(int $id): void
{
$this->deletePerson($this->doctor, $id);
}
public function addClient(PersonData $data): Client
{
return $this->addPerson($this->client, $data);
}
public function editClient(int $id, PersonData $data): Client
{
return $this->editPerson($this->client, $id, $data);
}
// 客户、其账户及其所有预约(ADMIN,或患者本人
// 在“Manage my account”中:同一个方法,同一条规则)
public function deleteClient(int $id): void
{
$this->deletePerson($this->client, $id);
}
// -----------------------------------------------------------------------
// 创建:用户账户和人员(引用该账户),在同一个
// 事务中。Doctrine 先插入账户,然后插入人员,其外键
// [user] 接收数据库刚刚为该账户生成的 id。
// -----------------------------------------------------------------------
private function addPerson(Descriptor $d, PersonData $data): Person
{
$lastName = mb_strtoupper(trim($data->lastName));
$firstName = trim($data->firstName);
// dbrdvmedecins2 数据库的规则:登录名 = 小写的姓,
// 密码 = 登录名 - 除非 ADMIN(或患者)输入了其他值
$login = mb_strtolower($data->login ?: $lastName);
$password = $data->password ?: $login;
return $this->transaction(function () use ($d, $data, $lastName, $firstName, $login, $password) {
$this->checkPersonUnique($d, $firstName, $lastName, null);
$this->checkLoginFree($login);
// hash:密码的 bcrypt 哈希
$user = new User($login, $this->hasher->hash($password), "$firstName $lastName", $d->role);
$this->users->add($user);
// new ($d->entityClass)(...):一个类的实例,该类的名称在描述符的
// [entityClass] 属性中(Doctor 或 Client)
$person = new ($d->entityClass)($data->title, $lastName, $firstName, $user);
$d->dao->add($person);
return $person;
});
}
// -----------------------------------------------------------------------
// 修改:人员及其账户(显示的名称“firstName LASTNAME”必须
// 随之更新;登录名和密码只有在输入了新值时才会更改)。
// -----------------------------------------------------------------------
private function editPerson(Descriptor $d, int $id, PersonData $data): Person
{
return $this->transaction(function () use ($d, $id, $data) {
$person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
// 乐观锁:如果数据库中的版本不再是表单中的
// 版本,说明在此期间有人修改了这条记录 - 我们拒绝,
// 而不是悄悄地覆盖他们的更改
if ($data->version !== null && $data->version !== $person->getVersion()) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE');
}
$lastName = mb_strtoupper(trim($data->lastName));
$firstName = trim($data->firstName);
$this->checkPersonUnique($d, $firstName, $lastName, $id);
$person->edit($data->title, $lastName, $firstName);
// 其账户:显示的名称,以及(如果已输入)登录名和
// 密码
$account = $person->getAccount();
$account->setName("$firstName $lastName");
$login = $data->login ? mb_strtolower($data->login) : null;
if ($login !== null && $login !== $account->getLogin()) {
$this->checkLoginFree($login);
$account->setLogin($login);
}
if ($data->password) {
$account->setPassword($this->hasher->hash($data->password));
}
// 无需再做其他事情:在事务结束时,Doctrine 会发送
// 已修改行的 UPDATE,并带有其乐观锁
// UPDATE ... SET ..., version = version + 1 WHERE id = ? AND version = ?
// 如果该记录在上面的读取之后被修改,则没有行
// 被修改,Doctrine 会抛出 OptimisticLockException
return $person;
});
}
// -----------------------------------------------------------------------
// 删除,在同一个事务中,按外键
// 要求的顺序:
// 1. 如果仍有预约则可能拒绝(医生);
// 2. 引用该人员的内容(医生的时间段、客户的预约),
// 立即删除;
// 3. 人员(它引用其账户),然后是其账户:Doctrine
// 在事务结束时按该顺序删除它们。
// -----------------------------------------------------------------------
private function deletePerson(Descriptor $d, int $id): void
{
$this->transaction(function () use ($d, $id) {
$person = $d->dao->read($id) ?? throw new BusinessException($d->notFoundKey);
if ($d->countAppointments !== null && ($d->countAppointments)($id) > 0) {
throw new BusinessException($d->hasAppointmentsKey);
}
if ($d->beforeDelete !== null) {
($d->beforeDelete)($id);
}
$d->dao->remove($person);
$this->users->remove($person->getAccount());
});
}
// 拒绝同一类型中另一位人员已使用的名和姓
// ($currentId:正在被修改的人员,他们当然有权
// 保留自己的名和姓;创建时为 null)
private function checkPersonUnique(Descriptor $d, string $firstName, string $lastName, ?int $currentId): void
{
$namesake = $d->dao->namesake($firstName, $lastName);
if ($namesake !== null && $namesake->getId() !== $currentId) {
throw new BusinessException($d->alreadyExistsKey);
}
}
private function checkLoginFree(string $login): void
{
if ($this->users->readByLogin($login) !== null) {
throw new BusinessException('ERRORS.LOGIN_TAKEN');
}
}
// -----------------------------------------------------------------------
// 在事务中执行 [$work](wrapInTransaction,见示例 28):
// 如果函数正常结束,Doctrine 会将待处理的写入
// 发送到数据库(flush),然后提交事务(COMMIT);如果
// 函数抛出异常(包括 BusinessException),则 ROLLBACK:什么都不会写入。
//
// “登录名可用”和“名 + 姓唯一”的检查在写入之前进行,
// 以给出清晰的消息。但两位 ADMIN 可能
// 在同一时刻保存相同的登录名(或相同的医生):在这种
// 罕见的情况下,由 SQL 唯一性约束拒绝第二次写入。
// 同样,对同一条记录的两次同时修改由
// 乐观锁来裁决。因此我们在事务外围捕获这些错误,
// 将它们转换为 BusinessException。任何其他错误都是真正的
// 异常情况:我们让它向上传递。
// 异常之后,Doctrine 会关闭实体管理器:当前请求
// 不得再写入任何内容(控制器会重定向,或
// 重新显示表单)。
// -----------------------------------------------------------------------
private function transaction(Closure $work): mixed
{
try {
return $this->em->wrapInTransaction($work);
} catch (UniqueConstraintViolationException $e) {
if (preg_match(self::CONSTRAINT, $e->getMessage(), $m)
&& isset(self::CONSTRAINT_MESSAGES[$m[1]])) {
throw new BusinessException(self::CONSTRAINT_MESSAGES[$m[1]], previous: $e);
}
throw $e;
} catch (OptimisticLockException $e) {
throw new BusinessException('ERRORS.CONCURRENT_UPDATE', previous: $e);
}
}
}
|
应用程序中最重要的文件。我们将按主题逐一讲解。
11.11.6.1. 依赖项和描述符
第 86–124 行:构造函数从容器接收实体管理器(用于事务)、五个 DAO 实例,以及哈希服务工厂 ([PasswordHasherFactoryInterface]),并向它请求账户所用的哈希服务:[getPasswordHasher(User::class)] 提供应用在 [User] 类的 [security.yaml] 中所选算法([bcrypt],10 次迭代)的服务。接下来是两个描述符。具名参数 ([dao: $doctors],示例 01)使调用更易读。[$appointments->countByDoctor(...)] (括号中的三个点 没有 特别含义):这是 [PHP] 8.1 的语法,它从一个方法创建一个 [Closure]——一个稍后才会被调用的函数([($d->countAppointments)($id)],第 359 行)。删除医生时会一并删除其时间段([deleteByDoctor]),但如果他们有预约则不能删除;删除客户时会一并删除其所有预约([deleteByClient])。
11.11.6.2. 读取操作和日历
读取操作(第 130–178 行)委托给 DAO 层。医生的日程(第 182–198 行)是计算出来的:医生、其时间段以及当天的预约。预约存储在一个按时间段编号索引的数组中:[$bookings[$slot->getId()] ?? null] 返回某个时间段的预约,如果该时间段空闲则返回 [null] 。[array_map] 把每个时间段转换为 [DoctorDaySlot]。
11.11.6.3. 预约
第 216–232 行:四个步骤,在单个事务中完成。
- 不得预约过去的时间:[DateTimeImmutable] 的值可以使用常用的运算符([<]、[>=] 等)进行比较;
- 患者的记录被锁定 ([lock],[SELECT ... FOR UPDATE])。为什么?“每位患者只能有一个即将到来的预约”这条规则是通过计数来验证的(第三步),然后才进行插入(第四步)。如果同一位患者同时预约两个时间段(两个标签页、双击),两个事务都可能统计出零个预约,然后各自插入自己的预约:规则就会被违反。有了锁,第二个事务会等待第一个事务完成,然后统计出……一个预约。[?? throw new BusinessException(...)]:如果该客户已不存在,[lock] 会返回 [null],运算符 [??] 会计算其第二个操作数,从而抛出异常(因为自 [PHP] 8 起,[throw] 是一个表达式);
- 统计即将到来的预约;
- 在事务结束时插入。如果该时间段刚刚被另一位患者预约,数据库约束 [unq1_appointments] 会拒绝这次插入:方法 [transaction] 会把这个错误转换为 [BusinessException]。
11.11.6.4. 管理医生和患者
公共方法(第 244–274 行)使用正确的描述符调用共享的私有方法。
- 第 281–302 行:创建。姓氏被转换为大写([mb_strtoupper]:支持带重音字母的 [strtoupper] 版本),名和姓会去除多余的空格([trim])。默认情况下,登录名是小写的姓氏,密码就是登录名(按照演示账户的规则):[$a ?: $b] 在 [$a] 为“真”(既不是 [null] 也不是空字符串)时等价于它,否则等价于 [$b] 。在事务中:先是验证(名和姓可用、登录名可用),然后是账户,其密码经过哈希处理([hash]),再是引用该账户的人员。[new ($d->entityClass)(...)] 会创建一个类的对象,该类的名称存放在描述符的 [entityClass] 属性中(表达式两侧必须加括号)。[Doctrine] 会在人员之前插入账户:它知道实体之间的关系,并推导出[INSERT] 对象的顺序。[use (...)]:普通的匿名函数([function () use ($d, ...)])看不到包含它的方法的变量;[use] 把它们传递给它(箭头函数 [fn () =>] 能自行看到它们,但只能包含一个表达式);
- 第 308–344 行:更新,带有两层乐观锁。第一层是一次比较(第 316–318 行):表单的版本(隐藏字段,示例 28)必须与数据库中记录的版本一致;否则,说明有人在表单显示之后、提交之前修改了该记录。第二层是 [Doctrine] 的锁:在事务结束时发送的 [UPDATE] 记录带有条件 [WHERE version = ?],它能检测到发生在读取和写入之间的更改([OptimisticLockException])。接着是账户:其显示名称(“firstName LASTNAME”)总是会更新;其登录名和密码只有在输入了新值时才会更新;它自己的乐观锁同样保护 [users] 表中的行。没有什么需要“保存”的:所读取的实体由实体管理器跟踪,管理器会写入其更改。在事务结束时,[Doctrine] 会存储实体的新版本:调用者收到的是已更新的人员;
- 第 355–368 行:删除,按外键所要求的顺序进行:首先是引用该人员的记录(时间段或预约),紧接着由 DAO 执行 [DELETE] ;然后是该人员,再是其账户,[Doctrine] 会在事务结束时按这个顺序删除它们。相反的顺序会被数据库拒绝:仍被外键引用的行无法删除;
- 第 373–387 行:被修改的人员可以保留自己的名和姓;[$currentId] 在创建时等价于 [null] 。
11.11.6.5. 数据库事务和错误
第 406–419 行:所有写入操作都使用此方法。[wrapInTransaction] 在事务中执行函数(示例 28):先 [flush],如果正常完成则 [COMMIT] ,如果发生异常则 [ROLLBACK] ——包括 [BusinessException]:在操作过程中违反规则不会留下任何痕迹。“登录名可用”和“名和姓可用”的检查是在写入之前执行的,以便给出清晰的消息。然而,两位管理员可能同时尝试注册同一个登录名:每个人都发现它可用,而第二个 [INSERT] 会被约束 [unq_users_login] 拒绝。[Doctrine] 随后抛出 [UniqueConstraintViolationException] (示例 28),其消息来自 [MySQL];其中包含被违反的约束的名称:
| SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry 'dupont' for key 'users.unq_users_login'
|
第 75 行的正则表达式提取这个名称([MySQL] 8 会在它前面加上表名,即 [users.unq_users_login],而 [MariaDB] 则不会:部分 [(?:[^'.]*\.)?] 同时接受两种形式),而第 68–73 行的表提供消息键。违反其他约束则是真正的异常情况:会重新抛出([throw $e]),并导致 500 错误页面。最后,[Doctrine] 上的乐观锁所检测到的冲突([OptimisticLockException])会变成与版本比较所检测到的冲突相同的 [BusinessException] 。
回顾 [wrapInTransaction] (示例 28)的一个后果:发生异常之后,实体管理器会被关闭 ,在当前请求期间无法再写入。控制器对此已有考虑:在出现 [BusinessException] 之后,它们会重定向或重新显示表单,而不再写入任何其他内容。
11.12. 身份验证
[src/Security] 文件夹包含示例 25 至 27,涉及数据库用户和一些额外的安全措施。让我们回顾一下其原理(示例 25): 的 [main] 防火墙,对应 [config/packages/security.yaml] 是 无状态的 ([stateless]);对于每个请求,由我们自行设计的认证器 从 Cookie [rdvmedecins_jwt] 中读取 JWT 令牌并识别用户;然后规则 [access_control] 决定对各页面的访问。
11.12.1. src/Security/ConnectedUser.php
| <?php
// =========================================================================
// src/Security/ConnectedUser.php:已登录的用户,由
// 其 JWT 令牌描述(见示例 25)。UserInterface:Symfony 期望已验证用户
// 具备的接口(控制器中的 $this->getUser()、#[CurrentUser]、
// 视图中的 app.user 和 is_granted()...)。
//
// 我们令牌的声明(claims)(见 AuthService::tokenCookie):
// sub :用户账户的 id(JWT 约定:"subject"),为文本
// login :登录名
// name :显示的名称("Marie PELISSIER"),用于导航栏
// role :ADMIN、DOCTOR 或 USER
// iat, exp :令牌的创建日期和过期日期
//
// 此对象不是来自数据库:它在每次请求时都根据
// 令牌重建,令牌的签名保证了其内容。
// =========================================================================
namespace App\Security;
use App\Entity\Role;
use Symfony\Component\Security\Core\User\UserInterface;
readonly class ConnectedUser implements UserInterface
{
public function __construct(
public int $userId,
public string $login,
public string $name,
public Role $role,
) {
}
// 由已验证令牌的声明所描述的用户;如果某个声明
// 缺失或形式不符合预期,则为 null。Role::tryFrom:对未知角色返回 null
public static function of(array $claims): ?self
{
$role = Role::tryFrom((string) ($claims['role'] ?? ''));
if (! isset($claims['sub'], $claims['login'], $claims['name']) || $role === null
|| ! ctype_digit((string) $claims['sub'])) {
return null;
}
return new self((int) $claims['sub'], (string) $claims['login'], (string) $claims['name'], $role);
}
public function isAdmin(): bool
{
return $this->role === Role::ADMIN;
}
public function isPatient(): bool
{
return $this->role === Role::USER;
}
// —— UserInterface 接口:用户的标识符(其登录名),
// 及其在 Symfony 意义上的角色(ROLE_ADMIN、ROLE_DOCTOR 或 ROLE_USER,见
// Role 枚举),由
// config/packages/security.yaml 的 access_control 规则检查
public function getUserIdentifier(): string
{
return $this->login;
}
public function getRoles(): array
{
return [$this->role->symfonyRole()];
}
}
|
已登录的用户,由其令牌描述:其账户 ID、用户名、姓名和角色。与示例 25 中的 [User] 一样,它实现了 [UserInterface] 接口,这是 [Symfony] 对已认证用户的要求。这个对象不是来自数据库:它在每个请求中都根据令牌重新构建,令牌的签名保证了其内容。因此,应用程序不会在每个请求中从数据库读取账户。该类是 [readonly] 的(示例 08):其公共属性在构造之后不能被修改。
- 第 36–44 行:用户由一个已经经过验证的令牌的声明(claims)来描述,如果某个声明缺失或格式不符合预期,则为 [null] 。正确签名的令牌本不应格式错误;然而,密钥可能与另一个应用程序共享,而那个应用程序可能会生成不同的令牌:谨慎一些不需要付出任何代价。[Role::tryFrom] 返回角色,对于未知值则返回 [null] ;[ctype_digit] 验证字符串是否只由数字组成;
- 第 46–54 行:视图和控制器经常提出的两个问题;
- 第 60–68 行:[UserInterface] 接口。用户的标识符是其登录名;按 [Symfony] 的定义,其角色仅限于单个角色,即 [ROLE_ADMIN]、[ROLE_DOCTOR] 或 [ROLE_USER],由枚举 [Role] 计算得出。这些就是规则 [access_control]、属性 [#[IsGranted]], 以及视图的函数 [is_granted] 所检查的角色。([eraseCredentials] 方法用于在登录后清除明文密码,它已在 [Symfony] 8 中从接口里移除。)
11.12.2. src/Security/AuthService.php
| <?php
// =========================================================================
// src/Security/AuthService.php:身份验证逻辑:
// - validate() :检查登录名 / 密码对;
// - tokenCookie() :为已验证的用户构建 JWT 令牌,以及携带它的
// Cookie;
// - currentUser() :由令牌描述的用户。
//
// JWT 令牌通过什么传输?通过 Cookie(见示例 25):显示普通 HTML 页面的浏览器
// 因此会自行在每次
// 请求时提交它。该 Cookie 的选项对安全很重要:
// - HttpOnly:页面的 JavaScript 无法读取该 Cookie(因此被注入的
// 脚本无法窃取令牌);
// - SameSite=Lax:浏览器不会随来自其他站点的 POST 发送该 Cookie
// (这是针对所谓 CSRF 攻击的第一重保护;第二重是
// 表单的防 CSRF 令牌);
// - Secure:在生产环境(HTTPS)中,Cookie 绝不以未加密方式传输;
// - 有效期:Cookie 会在令牌过期的同时消失。
// =========================================================================
namespace App\Security;
use App\Dao\UserDao;
use App\Entity\User;
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
use RuntimeException;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\PasswordHasher\Hasher\PasswordHasherFactoryInterface;
use Throwable;
class AuthService
{
// 携带令牌的 Cookie 的名称
public const COOKIE = 'rdvmedecins_jwt';
// .env 文件的设置:#[Autowire(env: ...)](见示例 25)
public function __construct(
private UserDao $users,
private PasswordHasherFactoryInterface $hashers,
#[Autowire(env: 'JWT_SECRET')] private string $secret,
#[Autowire(env: 'int:JWT_DURATION_MINUTES')] private int $duration,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
// HMAC-SHA256 需要至少 256 位的密钥:我们明确地说明这一点,
// 而不是让库在后面才失败
if (strlen($this->secret) < 32) {
throw new RuntimeException('JWT_SECRET must be at least 32 characters long (see .env).');
}
}
// 如果登录名不存在或密码错误则为 null。verify 使用已存储哈希中包含的“盐值”
// 对输入的密码进行哈希,然后
// 比较两个结果
public function validate(string $login, string $password): ?User
{
$user = $this->users->readByLogin($login);
if ($user === null
|| ! $this->hashers->getPasswordHasher(User::class)->verify($user->getPassword(), $password)) {
return null;
}
return $user;
}
// -----------------------------------------------------------------------
// [$user] 的 JWT 令牌,放在携带它的 Cookie 中。令牌经过签名
// (HMAC-SHA256),使用密钥:浏览器可以读取它(它没有
// 加密),但不能修改它 - 任何修改都会使签名
// 失效。
// -----------------------------------------------------------------------
public function tokenCookie(User $user): Cookie
{
$now = time();
$claims = [
'sub' => (string) $user->getId(),
'login' => $user->getLogin(),
'name' => $user->getName(),
'role' => $user->getRole()->value,
'iat' => $now,
'exp' => $now + $this->duration * 60,
];
$token = JWT::encode($claims, $this->secret, 'HS256');
return Cookie::create(self::COOKIE, $token)
->withExpires($now + $this->duration * 60)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// 清除令牌 Cookie:响应携带一个同名的、空的、已过期的 Cookie
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE);
return $response;
}
// -----------------------------------------------------------------------
// 由令牌描述的用户;如果令牌已过期、被伪造或
// 格式错误则为 null。JWT::decode 会检查签名和过期日期(声明 exp)。
// -----------------------------------------------------------------------
public function currentUser(string $token): ?ConnectedUser
{
try {
// decode 返回一个对象;(array) 将其转换为关联数组
$claims = (array) JWT::decode($token, new Key($this->secret, 'HS256'));
} catch (Throwable) {
return null;
}
return ConnectedUser::of($claims);
}
}
|
- 第 37 行:令牌 Cookie 的名称,一个类常量,通过 [AuthService::COOKIE] 读取;
- 第 40–52 行:该服务接收账户的 DAO 层;哈希服务工厂(对应 [User] 类的那个,bcrypt,在 [security.yaml] 中声明),以及来自 [.env] 文件的三个设置,通过 [#[Autowire(env: ...)]] 属性获得(示例 25)。前缀 [int:] 和 [bool:] 会转换环境变量的文本。如果密钥太短,服务一启动就会报告,并给出清晰的消息(参见“常见问题”);
- 第 57–65 行:验证用户名和密码(示例 25),账户由 DAO 层从数据库中检索。请注意,该服务直接使用 DAO 层,而不经过业务层:密码验证不是业务规则;
- 第 73–90 行:用户的令牌以及承载它的 Cookie。声明与示例 25 相同,包括账户 ID([sub],按标准要求是一个字符串)和用户名。[Cookie::create] 创建一个 Cookie,再由 [with...] 方法补充(每个方法都返回一个新的 Cookie:该对象是不可变的):其过期日期(即令牌的过期日期)、[Secure] (在生产环境中,通过 HTTPS)、[HttpOnly] 和 [SameSite=Lax] (参见第 9–18 行的注释);
- 第 93–97 行:删除 Cookie。[clearCookie(name)] 会向响应中添加一个同名的 Cookie——为空且已过期——这样浏览器就会删除它。该方法是静态的:它不需要任何配置,调用它的类也无需接收该服务;
- 第 103–112 行:令牌验证(示例 25)。
11.12.3. src/Security/TokenAuthenticator.php
| <?php
// =========================================================================
// src/Security/TokenAuthenticator.php:防火墙的身份验证器(AUTHENTICATOR)(见
// config/packages/security.yaml 和示例 25):在每次请求时,它根据 Cookie [rdvmedecins_jwt] 中的
// JWT 令牌确定用户是谁。
//
// 它自己不拒绝任何东西:缺失或无效的令牌会使访问者
// 保持匿名。随后由 access_control 规则拒绝访问受保护的
// 页面;被拒绝的匿名访问者随后会被交给入口点(ENTRY POINT)(
// start 方法),由它把他们送回登录页面。
// =========================================================================
namespace App\Security;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ResponseEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
use Symfony\Component\Security\Core\Exception\AuthenticationException;
use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
use Symfony\Component\Security\Http\Authenticator\AbstractAuthenticator;
use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
use Symfony\Component\Security\Http\Authenticator\Passport\Passport;
use Symfony\Component\Security\Http\Authenticator\Passport\SelfValidatingPassport;
use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
class TokenAuthenticator extends AbstractAuthenticator implements AuthenticationEntryPointInterface
{
// 指示令牌无效的请求属性,需要清除
private const INVALID_TOKEN = '_invalid_token';
public function __construct(
private AuthService $auth,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
// 仅当请求携带令牌 Cookie 时,身份验证器才会起作用
public function supports(Request $request): ?bool
{
return $request->cookies->getString(AuthService::COOKIE) !== '';
}
// 由 AuthService 检查过的令牌描述了用户:通行证
// 自行验证,徽章直接返回该用户(无需
// 在数据库中查找他们,见示例 25)
public function authenticate(Request $request): Passport
{
$user = $this->auth->currentUser($request->cookies->getString(AuthService::COOKIE))
?? throw new CustomUserMessageAuthenticationException('invalid token');
return new SelfValidatingPassport(new UserBadge($user->login, fn () => $user));
}
public function onAuthenticationSuccess(Request $request, TokenInterface $token, string $firewallName): ?Response
{
return null;
}
// 无效的令牌(过期、伪造):访问者保持匿名(null),并且
// Cookie 将从响应中被清除,无论是什么响应(见 clearInvalidToken)
public function onAuthenticationFailure(Request $request, AuthenticationException $exception): ?Response
{
$request->attributes->set(self::INVALID_TOKEN, true);
return null;
}
// -----------------------------------------------------------------------
// 入口点(ENTRY POINT):匿名访问者请求受保护的页面。转到
// 登录页面。如果他们有令牌 Cookie,说明其令牌已不
// 再有效(过期、伪造):其会话已过期,我们会告知他们
// -----------------------------------------------------------------------
public function start(Request $request, ?AuthenticationException $authException = null): Response
{
if ($request->cookies->has(AuthService::COOKIE)) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
}
return new RedirectResponse($this->urls->generate('login'));
}
// -----------------------------------------------------------------------
// 一个 kernel.response 监听器(见示例 24),写在同一个类中:
// 它会在所有响应中清除无效令牌的 Cookie
// -----------------------------------------------------------------------
#[AsEventListener(event: KernelEvents::RESPONSE)]
public function clearInvalidToken(ResponseEvent $event): void
{
if ($event->getRequest()->attributes->get(self::INVALID_TOKEN)) {
AuthService::clearCookie($event->getResponse());
}
}
}
|
示例 25 中的认证器,在 [security.yaml] ([custom_authenticators])中声明。它同时也充当防火墙的入口点 :它实现了 [AuthenticationEntryPointInterface] 接口,并且 [Symfony] 会自动选用它,因为它是防火墙唯一的认证器。
- 第 45–48 行:[supports] 判断认证器是否应当介入:仅当请求包含令牌 Cookie 时才介入。没有 Cookie 时,访问者是匿名的,不再采取进一步的操作;
- 第 53–58 行:[authenticate] 验证令牌。无效的令牌会触发 [AuthenticationException] (其子类 [CustomUserMessageAuthenticationException], 可携带自由格式的消息)。否则,会生成一个自验证通行证([SelfValidatingPassport]:没有需要验证的密码;令牌的签名就充当密码),其用户是根据令牌构造的,无需在数据库中查找;
- 第 60–63 行:身份验证成功后,返回 [null]:请求继续进入所请求的操作;
- 第 67–71 行:失败之后(令牌过期或被伪造),同样返回 [null] :访问者仍是匿名的。如果访问者请求受保护的页面,规则 [access_control] 会把他们重定向到登录页,但他们可以查看公共页面(包括登录页本身!)。唯一的提示是请求属性中的一项说明,表示应当删除该 Cookie;
- 第 78–84 行:入口点,当匿名访问者请求受保护的页面时由防火墙调用:重定向到登录页。如果请求中包含令牌 Cookie,就意味着该令牌已不再有效:此时会显示消息“您的会话已过期:请重新登录。”(一条弹出消息,稍后讨论);
- 第 90–96 行:事件 [kernel.response] 的监听器(示例 24),定义在同一个类中:[#[AsEventListener]] 属性应用于一个方法,认证器——与其他任何服务一样是一个服务——也就成了监听器。它会删除无效令牌的 Cookie,不论响应是什么:登录页、公共页面,或来自入口点的重定向。无效的 Cookie 毫无用处,还会干扰下一个请求的消息。
11.12.4. src/Security/InvalidSession.php
| <?php
// src/Security/InvalidSession.php:令牌有效,但它
// 所指的账户已不存在:它在登录之后被删除了(由患者
// 本人在另一个标签页中,或由 ADMIN 删除)。我们将这种情况视为
// 会话过期:ErrorPage 监听器会清除 Cookie 并送回登录
// 页面。
namespace App\Security;
use RuntimeException;
class InvalidSession extends RuntimeException
{
}
|
示例 25 中没有涵盖的一种情形:令牌有效,但它所指向的账户已不存在。某位患者在一个标签页中删除了自己的账户,但令牌仍然存在于另一个标签页中;或者管理员删除了一位已登录患者的账户。令牌的签名无法表明账户是否存在;只有当应用程序查找与账户关联的患者时([Utils::connectedPatient],稍后讨论),才会发现该账户已不存在。此时它会抛出这个异常,监听器 [ErrorPage] (稍后讨论)会把它当作会话过期处理。该类是空的:只有它的类型 才重要,监听器据此识别它([instanceof])。
11.12.5. src/Security/CaptchaService.php、Captcha.php 和 CaptchaDrawing.php
[CaptchaDrawing.php] 和 [Captcha.php] 来自示例 27。服务几乎相同:
| <?php
// =========================================================================
// src/Security/CaptchaService.php:一个验证码(CAPTCHA)(“区分人类与
// 机器人的测试”),由服务器自己构建,不使用任何外部服务(见示例 27)。
//
// 工作原理:
// 1. generate() 绘制一段随机文本,生成其图像,并将正确
// 答案存储在服务器的缓存中,使用一个随机标识符;
// 2. 页面显示图像,并将标识符放入表单的一个隐藏字段中
// (答案本身绝不离开服务器);
// 3. verify(id, typed) 将输入与预期答案比较,然后忘记
// 这个验证码:每张图像只使用一次,机器人无法重放
// 已经找到的答案。
//
// 为什么使用缓存?PHP 应用程序在两次请求之间不会在内存中保留任何东西:
// 每个请求都从零开始。因此,需要在一次请求之后继续保留的内容
// 都放入缓存(这里是 var/cache 中的文件),由所有
// 请求共享,如果使用像 Redis 这样的缓存,甚至可以由多个服务器共享。
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\Lock\LockFactory;
class CaptchaService
{
// 图像的有效时长,以秒为单位:10 分钟用于填写表单
private const LIFETIME = 600;
public function __construct(private CacheItemPoolInterface $cache, private LockFactory $locks)
{
}
public function generate(): Captcha
{
$text = CaptchaDrawing::randomText(5); // 5 个字符
$id = bin2hex(random_bytes(12)); // 一个无法猜测的标识符
// 缓存会在 10 分钟后自行忘记答案
$item = $this->cache->getItem("captcha.$id");
$this->cache->save($item->set($text)->expiresAfter(self::LIFETIME));
return new Captcha($id, CaptchaDrawing::svg($text));
}
// 如果 [$typed] 是验证码 [$id] 的正确答案则为 true(不区分
// 大小写)。验证码在任何情况下都会被消耗。
public function verify(?string $id, ?string $typed): bool
{
// 标识符来自浏览器:十六进制数字,或者为空
if ($id === null || ! ctype_xdigit($id) || $typed === null) {
return false;
}
// 如果两个请求在同一时刻提交同一个验证码,只有一个
// 能获得锁(acquire(false):不等待)- 另一个失败
$lock = $this->locks->createLock("captcha.$id");
if (! $lock->acquire(false)) {
return false;
}
try {
$item = $this->cache->getItem("captcha.$id");
$this->cache->deleteItem("captcha.$id");
} finally {
$lock->release();
}
return $item->isHit() && strcasecmp($item->get(), trim($typed)) === 0;
}
}
|
- 第 35–43 行:随机生成的 5 个字符的字符串、一个随机标识符([random_bytes],一个加密级生成器,其字节由 [bin2hex] 写成十六进制),以及存储在缓存 中(示例 20)、保存 10 分钟的正确答案([expiresAfter],以秒为单位);
- 第 47–66 行:与示例 27 的一个区别。先读取答案,再将其从缓存中移除。在读取与移除之间,提交同一个验证码的第二个请求也可能读取到它:一张已解出的图片对应两次尝试。因此,专属于该验证码的锁 (示例 20)同时保护读取和移除。[acquire(false)] 会立即获取它:如果另一个请求已持有该锁,则返回 [false] ,而在这场竞争中落败的请求会失败。[finally] 块在所有情况下都会释放锁。比较时忽略大小写([strcasecmp] 对于两个不区分大小写时相同的字符串返回 0)以及输入两侧的空格([trim])。
11.12.6. src/Security/AttemptLimiter.php
| <?php
// =========================================================================
// src/Security/AttemptLimiter.php:防范机器人的第二道屏障(第一道
// 是验证码):我们统计尝试次数,超过阈值后
// 会阻止一段时间(见示例 27)。
//
// - 登录:同一 IP 地址对同一登录名在 LOGIN_MAX_FAILURES 次失败(验证码错误或
// 密码错误)之后,该组合会被
// 阻止,直到从第一次失败起计算的 LOGIN_BLOCK_MINUTES 分钟窗口结束。
// 如果同一 IP 地址累计达到
// LOGIN_MAX_FAILURES_IP 次失败(所有登录名合计,例如机器人尝试
// 成千上万个不同的登录名),它也会被阻止;
// - 创建账户:同一 IP 地址每小时最多创建 REGISTRATION_MAX_PER_HOUR 个
// 账户。
//
// 在教室里要注意:所有计算机通常通过
// 同一个 IP 地址访问互联网。这就是为什么登录阻止首先作用于
// (IP,登录名)这个组合 - 输错密码的学生不会阻止
// 他的邻座 - 也是为什么阈值可以调整(.env 文件)。
//
// 这些计数器来自 RateLimiter 组件的三个限制器,它们在
// config/packages/framework.yaml 中声明,并存储在缓存中。
// =========================================================================
namespace App\Security;
use Symfony\Component\RateLimiter\LimiterInterface;
use Symfony\Component\RateLimiter\RateLimiterFactoryInterface;
class AttemptLimiter
{
// 限制器 [login]、[login_ip] 和 [registration] 的工厂:参数的名称
// 指明了所用的限制器(见示例 27)
public function __construct(
private RateLimiterFactoryInterface $loginLimiter,
private RateLimiterFactoryInterface $loginIpLimiter,
private RateLimiterFactoryInterface $registrationLimiter,
) {
}
// ———————————————————————————————— 登录
// 剩余的阻止分钟数(0 = 允许尝试)
public function loginBlockMinutes(string $ip, string $login): int
{
return max(self::remainingMinutes($this->ipLoginLimiter($ip, $login)),
self::remainingMinutes($this->loginIpLimiter->create($ip)));
}
// consume():再记一次失败;第一次失败会开启一个
// LOGIN_BLOCK_MINUTES 分钟的窗口,窗口结束时计数器重新从零开始
public function loginFailure(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->consume();
$this->loginIpLimiter->create($ip)->consume();
}
// 登录成功会重置该登录名的计数器
public function loginSuccess(string $ip, string $login): void
{
$this->ipLoginLimiter($ip, $login)->reset();
}
// ———————————————————————————————— 注册
public function registrationBlockMinutes(string $ip): int
{
return self::remainingMinutes($this->registrationLimiter->create($ip));
}
public function registrationSuccess(string $ip): void
{
$this->registrationLimiter->create($ip)->consume();
}
// ———————————————————————————————— 通用机制
// (IP,登录名)这一组合的限制器:create(key) 返回一个在该键下
// 拥有自己计数器的限制器
private function ipLoginLimiter(string $ip, string $login): LimiterInterface
{
return $this->loginLimiter->create("$ip|".mb_strtolower(trim($login)));
}
// consume(0) 查询限制器而不消耗任何内容:还剩“令牌”吗?
// getRetryAfter:当前窗口结束的日期;距此
// 剩余的秒数向上取整到分钟:30 秒 -> "1 minute"
private static function remainingMinutes(LimiterInterface $limiter): int
{
$state = $limiter->consume(0);
if ($state->getRemainingTokens() > 0) {
return 0;
}
return max(1, (int) ceil(($state->getRetryAfter()->getTimestamp() - time()) / 60));
}
}
|
针对机器人的第二道防线,位于验证码之后:我们统计尝试次数,一旦超过阈值,就阻止访问。示例 27 介绍了 [RateLimiter] 组件,它来自 [Symfony]。三个限制器在 [config/packages/framework.yaml] 中声明(策略 [fixed_window]:固定时长的窗口,由第一个被消耗的令牌开启);该服务接收它们的工厂,通过参数名来识别(第 34–38 行):[$loginLimiter] 对应限制器 [login],[$loginIpLimiter] 对应 [login_ip],[$registrationLimiter] 对应 [registration]。工厂使用其方法 [create(key)] 创建一个在此键下拥有独立计数器的限制器。两条规则:
- 连接 (第 44–62 行):每次失败(验证码或密码错误)都会被计数两次:一次针对(IP 地址,登录名)这一对,一次只针对 IP 地址。这一对在 5 次失败尝试之后被封锁(设置 [LOGIN_MAX_FAILURES]),而 IP 地址在 25 次之后被封锁(设置 [LOGIN_MAX_FAILURES_IP]),不论是哪些登录名:这是在对付尝试数千个不同登录名的机器人。为什么不先封锁 IP 地址呢?在教室(或公司)里,所有机器往往通过同一个IP 地址访问互联网:一个输错密码的学生不应该封锁他的邻座。[consume()] 消耗一个令牌(计为一次失败的尝试);第一次尝试会开启一个 15 分钟的窗口(设置 [LOGIN_BLOCK_MINUTES]),窗口结束时计数器归零。一次成功的连接会重置该用户的计数器([reset]);
- 账户创建 (第 66–74 行):每个 IP 地址每小时最多创建 10 个账户(设置 [REGISTRATION_MAX_PER_HOUR]);
- 第 80–83 行:限制器的键。登录名为小写:[Admin] 和 [admin] 被视为相同(与数据库一致;参见其排序规则);
- 第 88–95 行:[consume(0)] 在不消耗任何令牌的情况下查询限制器(示例 27):如果还有剩余令牌,则允许此次尝试;否则,[getRetryAfter] 返回当前窗口的结束日期,到那时为止剩余的秒数会向上取整到下一分钟([ceil]):如果还剩 30 秒,就显示“1 分钟”。所显示的消息取决于此:“失败尝试次数过多。请在 15 分钟后重试。”
限制器的计数器存储在缓存中:它们被所有请求共享,并且在服务器重启后仍然保留。命令 [php bin/console cache:pool:clear cache.rate_limiter] 会把它们全部重置为零(在开发期间,当你把自己锁住时很有用);[php bin/console cache:clear]会清空整个 [var/cache] 目录,效果相同。
11.12.7. src/Security/RegistrationPass.php 和 RegistrationPassRequired.php
| <?php
// =========================================================================
// src/Security/RegistrationPass.php:创建账户的“通行证”。
//
// 要打开“创建患者账户”页面,必须先抄写登录页面的
// 验证码(见 RegistrationController,POST
// /register/access)。然后服务器会签发一张通行证:
// - 一个随机标识符,存储在 HttpOnly Cookie 中;
// - 有效期 15 分钟(填写表单的时间,即使在输入错误后多次
// 尝试也是如此);
// - 一旦创建账户就被消耗:一个已解答的验证码最多对应一个账户。
// 机器人无法批量创建账户。
//
// 没有有效的通行证时,GET 和 POST /register 会送回登录
// 页面(见 #[RegistrationPassRequired] 属性和监听器
// CheckRegistrationPass):直接输入 URL /register 无法
// 绕过验证码。
//
// 与验证码一样,通行证也保存在缓存中。
// =========================================================================
namespace App\Security;
use Psr\Cache\CacheItemPoolInterface;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Response;
class RegistrationPass
{
public const COOKIE = 'rdvmedecins_registration';
// 该 Cookie 仅由浏览器发送到 /register... 地址
private const PATH = '/register';
// 通行证的有效期,以分钟为单位
private const LIFETIME = 15;
public function __construct(
private CacheItemPoolInterface $cache,
#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure,
) {
}
// 签发一张新的通行证;返回携带它的 Cookie
public function issue(): Cookie
{
$id = bin2hex(random_bytes(12));
$item = $this->cache->getItem("pass.$id");
$this->cache->save($item->set(true)->expiresAfter(self::LIFETIME * 60));
return Cookie::create(self::COOKIE, $id)
->withExpires(time() + self::LIFETIME * 60)
->withPath(self::PATH)
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX);
}
// 如果 [$id] 是一张存在且未过期的通行证则为 true;hasItem:缓存
// 中是否有该项?
public function isValid(?string $id): bool
{
return $id !== null && ctype_xdigit($id) && $this->cache->hasItem("pass.$id");
}
// 该通行证已被使用:我们将其遗忘...
public function consume(?string $id): void
{
if ($id !== null && ctype_xdigit($id)) {
$this->cache->deleteItem("pass.$id");
}
}
// ...并且用一个同名、同路径、已过期的 Cookie 清除其 Cookie
public static function clearCookie(Response $response): Response
{
$response->headers->clearCookie(self::COOKIE, self::PATH);
return $response;
}
}
|
创建患者账户受登录页上的验证码保护。但账户创建表单位于另一个页面([/register]):当请求表单时,系统如何知道验证码是刚刚解出的?通过一个令牌:当验证码被解出时,服务器会生成一个随机标识符,将其在缓存中存储 15 分钟,并通过 Cookie 发送给浏览器。只有持有有效令牌,表单才会显示——账户才会被创建;令牌在创建账户时被消耗。因此,解出一次验证码只允许创建一个账户,而直接输入地址 [/register] 是行不通的。
- 第 46–57 行:该 Cookie 带有路径 [/register] ([withPath]):浏览器只会把它发送给以此路径开头的地址。它只包含一个随机标识符——无法猜测——并且只有服务器的缓存知道它是否有效:该 Cookie 无需签名;
- 第 61–64 行:[hasItem] 表明缓存中是否存在此键下的(未过期的)条目;
- 第 75–79 行:要删除 Cookie,必须指定相同的名称和相同的路径:对浏览器而言,名称相同但路径不同的两个 Cookie 是两个不同的 Cookie。
| <?php
// src/Security/RegistrationPassRequired.php:我们自己的 PHP 属性(见
// 示例 24),放置在需要创建账户通行证的操作上
// (见 RegistrationPass 和监听器 CheckRegistrationPass)。
namespace App\Security;
use Attribute;
#[Attribute(Attribute::TARGET_METHOD)]
class RegistrationPassRequired
{
}
|
一个我们自己发明的 [PHP] 属性,与示例 24 中的 [#[Timed]] 类似,应用于需要通行证的操作。它由监听器 [CheckRegistrationPass] 读取。
11.13. 监听器:src/EventListener
三个内核事件监听器(示例 24),按惯例存放在 [src/EventListener] 文件夹中。设置在类上的 [#[AsEventListener]] 属性指定事件和优先级;被调用的方法则是 [__invoke]。
11.13.1. src/EventListener/SetLanguage.php
| <?php
// =========================================================================
// src/EventListener/SetLanguage.php:请求的语言(见示例 22):
// 如果 Cookie [rdvmedecins_language] 的语言受支持,则使用它,否则使用英语。
//
// 优先级 40:该监听器在 Symfony 的路由(优先级 32)之前运行。因此
// 它对所有请求都会运行,即使是那些没有匹配到任何
// 路由的请求(404、405 页面...):它们的错误页面使用正确的语言。出于
// 同样的原因,它还会设置翻译器本身的语言,否则这应由
// Symfony 的一个监听器(优先级 15)完成,而路由错误会使
// 它无法运行。
// =========================================================================
namespace App\EventListener;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Contracts\Translation\LocaleAwareInterface;
#[AsEventListener(event: KernelEvents::REQUEST, priority: 40)]
class SetLanguage
{
// 记住所选语言的 Cookie(见 LanguageController)
public const COOKIE = 'rdvmedecins_language';
// 支持的语言(translations 文件夹);第一个是默认语言
public const LANGUAGES = ['en', 'fr'];
// LocaleAwareInterface:具有语言的服务,这里是翻译器
public function __construct(private LocaleAwareInterface $translator)
{
}
public function __invoke(RequestEvent $event): void
{
$request = $event->getRequest();
$language = $request->cookies->get(self::COOKIE);
$language = in_array($language, self::LANGUAGES, true) ? $language : self::LANGUAGES[0];
$request->setLocale($language);
$this->translator->setLocale($language);
}
}
|
请求语言(示例 22):Cookie 中的语言(如果是受支持的语言);否则为默认语言(英语)。与示例 22 的一个区别:优先级为 40(第 21 行),它高于路由的优先级(32)。示例 22 中的监听器(优先级 20)在路由之后运行;对于不匹配任何路由的 URL,路由会在监听器之前抛出异常,于是即使对说法语的用户,404 页面也会是英文的。出于同样的原因,监听器自己设置翻译器的语言(第 41 行),这通常由 [Symfony] 的监听器([LocaleAwareListener])完成,而它同样位于路由之后。[LocaleAwareInterface] 是带有语言的服务所使用的接口;翻译器就是其中之一,而 [Symfony] 在这里注入的正是这个翻译器。
11.13.2. src/EventListener/CheckRegistrationPass.php
| <?php
// =========================================================================
// src/EventListener/CheckRegistrationPass.php:标有
// #[RegistrationPassRequired] 属性的操作(GET 和 POST /register)需要
// 有效的通行证(见 src/Security/RegistrationPass.php);否则,返回
// 登录页面,并附带一条消息。因此直接输入 URL
// /register 无法绕过验证码。
//
// 一个 kernel.controller 监听器(见示例 24):操作已被选定,但
// 尚未被调用。为了拒绝,它用一个返回重定向的
// 函数替换该操作(setController)。
// =========================================================================
namespace App\EventListener;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\Flash;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpKernel\Event\ControllerEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
#[AsEventListener(event: KernelEvents::CONTROLLER)]
class CheckRegistrationPass
{
public function __construct(
private RegistrationPass $passes,
private Flash $flash,
private UrlGeneratorInterface $urls,
) {
}
public function __invoke(ControllerEvent $event): void
{
if ($event->getAttributes(RegistrationPassRequired::class) === []) {
return;
}
if (! $this->passes->isValid($event->getRequest()->cookies->get(RegistrationPass::COOKIE))) {
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
$url = $this->urls->generate('login');
$event->setController(fn () => new RedirectResponse($url));
}
}
}
|
[kernel.controller] 的监听器(示例 24):操作已被选定,但尚未被调用。
- 第 37–39 行:[getAttributes(class)] 返回该操作所带的此类属性:空列表;该操作不需要令牌;监听器什么也不做;
- 第 40–44 行:没有有效令牌:会显示一条消息,并且该操作被一个重定向到登录页的函数替换([setController])。内核会调用这个函数而不是该操作。URL 在箭头函数之外计算,因此箭头函数只需要一个变量。
监听器通过其构造函数接收服务:监听器是由容器创建的服务,与控制器一样。
11.13.3. src/EventListener/ErrorPage.php
| <?php
// =========================================================================
// src/EventListener/ErrorPage.php:错误如何变成 HTML 页面
// (见示例 24)。三种情况:
// 1. InvalidSession(账户在登录后被删除)-> 返回
// 登录页面,与会话过期时相同;
// 2. HTTP 错误:无效请求(400)、角色不足(403)、未知
// 页面(404)、不支持的方法(405)、缺失或错误的防 CSRF
// 令牌(419)...-> 错误页面,带有原始状态码;
// 3. 任何其他异常(真正的异常情况):Symfony 已将其连同调用栈
// 写入日志;在生产环境(APP_ENV=prod)中,
// 用户会看到 500 错误页面 - 绝不会看到调用栈;在
// 开发环境中,则是 Symfony 的调试页面。
//
// 优先级 -10:在将异常写入日志的 Symfony 监听器
// (0)之后,也在安全监听器(1)之后,后者会把拒绝访问转换为
// 重定向到登录页面(匿名访问者)或 403 错误
// (已验证用户);在构建 Symfony 错误页面的监听器
// (-128)之前。
// =========================================================================
namespace App\EventListener;
use App\Security\AuthService;
use App\Security\InvalidSession;
use App\Web\Flash;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Event\ExceptionEvent;
use Symfony\Component\HttpKernel\Exception\HttpExceptionInterface;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Twig\Environment;
#[AsEventListener(event: KernelEvents::EXCEPTION, priority: -10)]
class ErrorPage
{
public function __construct(
private Environment $twig,
private Flash $flash,
private UrlGeneratorInterface $urls,
// 调试模式(APP_ENV=dev):容器的 kernel.debug 参数
#[Autowire('%kernel.debug%')] private bool $debug,
) {
}
public function __invoke(ExceptionEvent $event): void
{
$e = $event->getThrowable();
if ($e instanceof InvalidSession) {
$this->flash->error('ERRORS.SESSION_EXPIRED');
$event->setResponse(AuthService::clearCookie(new RedirectResponse($this->urls->generate('login'))));
return;
}
if ($e instanceof HttpExceptionInterface) {
$event->setResponse($this->page($e->getStatusCode()));
return;
}
// 真正的异常情况:在开发环境中,是 Symfony 的调试页面
if (! $this->debug) {
$event->setResponse($this->page(500));
}
}
// 错误页面,带有错误的 HTTP 状态码及其消息
private function page(int $code): Response
{
$message = match ($code) {
400 => 'ERRORS.BAD_REQUEST',
403 => 'ERRORS.FORBIDDEN',
404, 405 => 'ERRORS.NOT_FOUND',
419 => 'ERRORS.PAGE_EXPIRED',
default => 'ERRORS.SERVER_ERROR',
};
return new Response($this->twig->render('error.html.twig', ['pageTitle' => 'ERROR_PAGE.TITLE',
'code' => $code, 'message' => $message]), $code);
}
}
|
错误如何变成 HTML 页面:这是示例 24 中的监听器 [ErrorPage] 的扩展版本。它监听事件 [kernel.exception],优先级为 -10(第 37 行):在记录异常日志的 [Symfony] 监听器(优先级 0)之后,也在安全组件的监听器(优先级 1)之后,后者会把拒绝访问转换为对入口点的调用(匿名访问者)或 403 错误(角色不合适的已认证用户);在 [Symfony] 生成错误页面的处理器(-128)之前。三种情形:
- 第 53–57 行:[InvalidSession] (账户已被删除):“会话已过期”消息、删除令牌 Cookie,以及登录页;
- 第 59–62 行:HTTP 错误:[HttpExceptionInterface] 是带有 HTTP 状态码的异常([NotFoundHttpException]、[AccessDeniedHttpException]、[HttpException(419)] 等)的异常处理接口,其状态码由 [getStatusCode] 抛出。随后显示错误页面,并显示此状态码;
- 第 65–67 行:其他异常属于真正的错误。在开发环境中([kernel.debug],示例 24),监听器什么也不做:将显示 [Symfony] 的调试页面,其中包含调用栈。在生产环境中则显示 500 错误页面:用户永远看不到调用栈,日志已经记录了它;
- 第 71–82 行:错误页面,视图 [error.html.twig],显示消息的状态码和键。[match] ([PHP] 8)使用严格相等,根据一个值选出另一个值;[404, 405 =>] 涵盖两种情况;[default] 处理所有其他情况。代码 405(Method Not Allowed:对只接受 POST 的地址发起 GET)会显示为“页面未找到”错误。
11.14. 登录控制器
11.14.1. src/Controller/AuthController.php
| <?php
// =========================================================================
// src/Controller/AuthController.php:登录的公开路由:
// GET / 重定向到该角色的主页(或 /login)
// GET /login 显示登录表单(带验证码)
// POST /login 检查尝试次数限制、验证码、登录名 / 密码
// POST /logout 注销
//
// 按以下顺序防范机器人:
// 1. 该 IP 地址对此登录名最近的失败次数过多?
// -> 立即拒绝,甚至不查看密码;
// 2. 验证码答案错误?-> 拒绝(计为一次失败);
// 3. 此时才检查密码。
// 对于在第 1 步或第 2 步被拒绝的尝试,我们从不检查其密码:
// 因此机器人即使不断尝试也学不到任何东西。
// =========================================================================
namespace App\Controller;
use App\Entity\Role;
use App\Security\AuthService;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\ConnectedUser;
use App\Web\BaseController;
use App\Web\Message;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class AuthController extends BaseController
{
public function __construct(
private AuthService $auth,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
) {
}
// 每个角色登录后的主页:其路由的名称
public static function homePage(Role $role): string
{
return $role === Role::USER ? 'area' : 'schedule';
}
// -----------------------------------------------------------------------
// GET /
// 该路由是公开的:如果有用户,则能获知该用户
// ($this->getUser()),但不要求任何东西。
// -----------------------------------------------------------------------
#[Route('/', name: 'home', methods: ['GET'])]
public function home(): Response
{
$user = $this->getUser();
return $this->redirectToRoute($user instanceof ConnectedUser
? self::homePage($user->role) : 'login');
}
// -----------------------------------------------------------------------
// GET /login[?login=xxx]:可选参数会预先填充登录名字段
// (在创建账户之后立即使用,见 RegistrationController)
// -----------------------------------------------------------------------
#[Route('/login', name: 'login', methods: ['GET'])]
public function form(Request $request): Response
{
// 已登录(令牌仍然有效):直接前往主页
$user = $this->getUser();
if ($user instanceof ConnectedUser) {
return $this->redirectToRoute(self::homePage($user->role));
}
// mb_substr:最多 30 个字符
return $this->page(mb_substr($request->query->getString('login'), 0, 30), null);
}
// -----------------------------------------------------------------------
// POST /login
// -----------------------------------------------------------------------
#[Route('/login', name: 'login_submit', methods: ['POST'])]
public function logIn(Request $request): Response
{
$this->checkCsrf($request);
$login = $request->request->getString('login');
$password = $request->request->getString('password');
$ip = (string) $request->getClientIp();
// 1. 最近的失败次数过多?
$minutes = $this->limiter->loginBlockMinutes($ip, $login);
if ($minutes > 0) {
return $this->page($login, new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]));
}
// 2. 验证码
if (! $this->captchas->verify($request->request->getString('captchaId'),
$request->request->getString('captcha'))) {
$this->limiter->loginFailure($ip, $login);
return $this->page($login, new Message('ERRORS.WRONG_CAPTCHA'));
}
// 3. 密码
$user = $login !== '' && $password !== '' ? $this->auth->validate($login, $password) : null;
if ($user === null) {
$this->limiter->loginFailure($ip, $login);
return $this->page($login, new Message('LOGIN.ERROR'));
}
$this->limiter->loginSuccess($ip, $login);
$response = $this->redirectToRoute(self::homePage($user->getRole()));
$response->headers->setCookie($this->auth->tokenCookie($user));
return $response;
}
// -----------------------------------------------------------------------
// POST /logout:清除令牌 Cookie,然后前往登录页面。
// 仅限 POST:放在另一个站点上的简单链接(GET),无法
// 在用户不知情的情况下使其注销。
// -----------------------------------------------------------------------
#[Route('/logout', name: 'logout', methods: ['POST'])]
public function logOut(Request $request): Response
{
$this->checkCsrf($request);
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// 表单,始终带有新的验证码(每张图像只使用
// 一次);重新显示输入的登录名,绝不显示密码。出现错误时:
// 422 状态码,与无效表单相同(见示例 19)
private function page(string $login, ?Message $error): Response
{
return $this->render('login.html.twig', ['pageTitle' => 'LOGIN.TITLE', 'error' => $error,
'login' => $login, 'captcha' => $this->captchas->generate()],
new Response(status: $error ? 422 : 200));
}
}
|
登录控制器,以示例 27 为基础。它继承自应用程序的 [BaseController] 类(稍后讨论),而该类本身是 [AbstractController] 的子类。
- 第 41–44 行:每个角色的主页及其路由名称:患者是“我的空间”,其他角色是日历;
- 第 51–57 行:地址 [/] 链接到该角色的主页或登录页。该路由是公开的([access_control] 规则,位于 [security.yaml]):[getUser()] 返回由认证器确定的用户(如果有的话),不要求任何东西。[redirectToRoute] (示例 04)创建一个到具名路由的重定向;
- 第 63–73 行:已登录的用户直接前往其主页。URL 的可选参数 [login] 会预填该字段(在创建账户之后);[mb_substr] 把它截断为 30 个字符;
- 第 78–110 行:登录流程,按示例 27 中所示的顺序:防 CSRF 令牌(稍后讨论)、任何封锁措施、验证码,以及密码。对于被限制器或验证码拒绝的尝试,绝不会验证密码:机器人即使坚持尝试也学不到任何东西。[getClientIp] 返回客户端的 IP 地址。如果尝试失败,页面会被直接渲染(不重定向):重新显示的表单总是带有新的验证码和所输入的登录名。错误是一个 [Message] 对象(见下文),由一个键及其参数组成,显示在页面底部。如果成功,登录计数器会重置为零,浏览器会被重定向到该角色的主页,并带上令牌 Cookie([headers->setCookie]);
- 第 117–122 行:注销会删除令牌 Cookie(示例 25)。它只接受 POST,并且需要防 CSRF 令牌:放在其他站点上的简单链接无法在用户不知情的情况下让其注销;
- 第 127–132 行:登录页面。[render] 的第三个参数是要填充的响应:错误会以代码 422(Unprocessable Content)返回,与无效表单的情形相同(示例 19)。[new Response(status: ...)] 使用了具名参数 ([PHP] 8):构造函数的前两个参数保留其默认值。
登录页面接收变量 [pageTitle],即页面标题的翻译键:所有操作都会把它传给各自的视图,供模板使用(见下文)。
11.15. Web 层:共享服务
[src/Web] 文件夹包含控制器共享的元素。
11.15.1. src/Web/ApplicationModel.php
| <?php
// =========================================================================
// src/Web/ApplicationModel.php:业务层的缓存 / 外观(相当于应用程序其他版本中
// [ApplicationModel] 类):医生和客户的
// 列表从数据库读取一次,然后由
// 缓存提供。
//
// 为什么用 Symfony 的缓存,而不是简单地用该对象的一个属性?因为
// PHP 应用程序在两次请求之间不会在内存中保留任何东西:该
// 对象是共享服务,但服务只在一次请求期间存在。
// 而缓存则由所有请求共享(见示例 20 和 23)。
//
// 这些列表可能会变化(ADMIN 添加、修改、删除医生和
// 客户):因此每次写入都要经过这个外观,它会在写入之后立即忘记相关的
// 列表;下一个需要它的请求再从数据库重新读取。这就是
// 业务层只有单一入口点的全部意义:“写入 => 更新缓存”
// 这条规则只在这里编写。
// =========================================================================
namespace App\Web;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Slot;
use App\Entity\Doctor;
use App\Entity\Appointment;
use App\Business\PersonData;
use App\Business\Business;
use App\Business\BusinessService;
use DateTimeImmutable;
use Symfony\Contracts\Cache\CacheInterface;
// 与业务层相同的契约
class ApplicationModel implements Business
{
private const DOCTORS = 'rdvmedecins.doctors';
private const CLIENTS = 'rdvmedecins.clients';
// CacheInterface:应用程序的缓存(cache.app 服务),通过
// Symfony 的“contracts”接口来使用,比 PSR-6 的接口更简单
public function __construct(private BusinessService $business, private CacheInterface $cache)
{
}
// ———————————————— 从缓存读取
// get(key, function):如果缓存中存在则返回缓存的值;否则调用该函数,
// 并将其结果存入缓存(没有时间限制),然后
// 返回。实体以序列化形式存储在其中(见 serialize):每个
// 读取它们的请求得到的都是副本,Doctrine 不会跟踪这些副本
public function getAllDoctors(): array
{
return $this->cache->get(self::DOCTORS, fn () => $this->business->getAllDoctors());
}
public function getAllClients(): array
{
return $this->cache->get(self::CLIENTS, fn () => $this->business->getAllClients());
}
// 用户账户为 [$userId] 的医生 - 用于为已登录的医生预先选中
// 其自己的日程。array_find:数组中第一个
// 满足条件的元素(如果没有则为 null)
public function getDoctorByUserId(int $userId): ?Doctor
{
return array_find($this->getAllDoctors(), fn (Doctor $d) => $d->getAccount()->getId() === $userId);
}
// ———————————————— 简单委托
public function getAllSlots(int $doctorId): array
{
return $this->business->getAllSlots($doctorId);
}
public function getDoctorDayAppointments(int $doctorId, DateTimeImmutable $day): array
{
return $this->business->getDoctorDayAppointments($doctorId, $day);
}
public function getClientById(int $id): ?Client
{
return $this->business->getClientById($id);
}
public function getDoctorById(int $id): ?Doctor
{
return $this->business->getDoctorById($id);
}
public function getAppointmentById(int $id): ?Appointment
{
return $this->business->getAppointmentById($id);
}
public function getSlotById(int $id): ?Slot
{
return $this->business->getSlotById($id);
}
public function getDoctorDaySchedule(int $doctorId, DateTimeImmutable $day): ?DoctorDaySchedule
{
return $this->business->getDoctorDaySchedule($doctorId, $day);
}
// 这里没有缓存:重要的是最新的数据(刚刚
// 修改或删除了自己账户的患者)
public function getClientByUserId(int $userId): ?Client
{
return $this->business->getClientByUserId($userId);
}
public function getClientUpcomingAppointments(int $clientId): array
{
return $this->business->getClientUpcomingAppointments($clientId);
}
public function addAppointment(DateTimeImmutable $day, Slot $slot, Client $client): Appointment
{
return $this->business->addAppointment($day, $slot, $client);
}
public function deleteAppointment(Appointment $appointment): void
{
$this->business->deleteAppointment($appointment);
}
// ———————————————— 写入 => 缓存被遗忘
// (delete:该项从缓存中移除)
public function addDoctor(PersonData $data): Doctor
{
$doctor = $this->business->addDoctor($data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function editDoctor(int $id, PersonData $data): Doctor
{
$doctor = $this->business->editDoctor($id, $data);
$this->cache->delete(self::DOCTORS);
return $doctor;
}
public function deleteDoctor(int $id): void
{
$this->business->deleteDoctor($id);
$this->cache->delete(self::DOCTORS);
}
public function addClient(PersonData $data): Client
{
$client = $this->business->addClient($data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function editClient(int $id, PersonData $data): Client
{
$client = $this->business->editClient($id, $data);
$this->cache->delete(self::CLIENTS);
return $client;
}
public function deleteClient(int $id): void
{
$this->business->deleteClient($id);
$this->cache->delete(self::CLIENTS);
}
}
|
应用程序的所有版本都有一个名为 [ApplicationModel] 的类:它是从 Web 层到业务层的唯一入口点,并把医生和客户的列表保存在内存中。几乎所有页面都会访问这些列表(日历中的医生下拉列表、预约窗口中的患者列表,以及管理页面),而且它们很少变化。
在 [PHP] 中发生变化的是“在内存中”的含义。像 [Java]、[C#] 或 [Python] 这样的应用程序在请求之间一直保留在内存中;[Flask] 版本把这些列表存储在启动时创建的单个对象的属性中。[PHP] 应用程序在每个请求中都会重新创建(示例 01):对象 [ApplicationModel] 确实是一个共享服务,但它只在单个请求期间存在(示例 23)。因此,这些列表存储在 缓存 中,即 [Symfony] 的缓存(示例 20),它由所有请求共享。
- 第 34 行:该类实现了 [Business] 接口,与 [BusinessService] 相同:控制器调用的是相同的方法,无论由哪个类来提供服务;
- 第 42 行:这次缓存是通过 [CacheInterface] 接口接收的,该接口来自 [Symfony] 的“contracts”(与 [cache.app] 是同一个服务),它比示例中的 PSR-6 接口更简单;
- 第 52–60 行:[get(key, function)] 返回存储在该键下的值;如果该值不存在,则调用该函数(该函数从数据库读取列表),将其结果永久存入缓存,并返回。第一个需要该列表的查询直接从数据库读取;后续查询则在缓存中找到它。缓存以序列化形式存储实体数组(示例 20),并在读取时重建它,同时重建已加载的关联(每个人员的账户)。重建后的实体是 [Doctrine] 实体管理器不跟踪的副本:它们只用于显示,绝不用于写入(业务层总是从数据库重新读取要修改的内容);
- 第 65–68 行:与某个账户关联的医生,通过 [array_find] 从缓存列表中检索(示例 06);
- 第 72–127 行:[Business] 契约的其他方法只是简单地委托给业务层。账户的客户([getClientByUserId])总是从数据库而不是缓存中检索:以最新数据为准(例如刚刚修改或删除了自己账户的患者);
- 第 132–170 行:更新操作。医生或客户进行的每次更新都不会保存相关列表([delete]):下一个需要它的查询将从数据库中检索。这正是单一入口点的意义所在:“写入时更新缓存”这条规则只在这里实现。如果写入失败(例如抛出 [BusinessException]),列表不会被覆盖——因为它没有改变。如果应用程序通过其他途径写入数据库(另一个程序、使用同一数据库的另一个版本的应用程序),就会使缓存过期:[php bin/console cache:pool:clear cache.app] 可以清除它。
11.15.2. src/Web/Message.php 和 Flash.php
| <?php
// src/Web/Message.php:待翻译的消息:其键及其参数。
// 视图用 {{ message.key|trans(message.params) }} 显示它。
namespace App\Web;
readonly class Message
{
public function __construct(
public string $key,
public array $params = [],
) {
}
}
|
待翻译的消息:一个键及其参数。业务层中的错误([BusinessException])和控制器中的错误都会变成 [Message],视图会将其翻译为页面所用的语言。
| <?php
// =========================================================================
// src/Web/Flash.php:“闪现”消息:只在下一个页面上
// 显示一次的消息(见示例 20)。它是应用程序所有表单使用的
// “Post / Redirect / Get”模式的天然补充:成功的
// POST 不构建页面,而是重定向(302)到一个 GET 页面;而
// 消息则必须在重定向之后保留下来。
//
// Symfony 将它们存储在会话中(var/sessions 文件夹的文件,见
// config/packages/framework.yaml)。
//
// 消息不包含文本,而是包含翻译键及其参数
// (一个 Message 对象):它在显示时被翻译为
// 页面的语言(见 templates/fragments)。两个列表:成功消息(显示在
// 页面顶部)和错误消息(显示在底部)。
// =========================================================================
namespace App\Web;
use Symfony\Component\HttpFoundation\RequestStack;
class Flash
{
// 请求栈,用于访问当前请求的会话
public function __construct(private RequestStack $requests)
{
}
public function success(string $key, array $params = []): void
{
$this->add('success', $key, $params);
}
public function error(string $key, array $params = []): void
{
$this->add('errors', $key, $params);
}
// getFlashBag:会话中闪现消息的“包”;add(type, message)
// 将消息添加到该类型的列表中(见示例 20)
private function add(string $type, string $key, array $params): void
{
$this->requests->getSession()->getFlashBag()->add($type, new Message($key, $params));
}
}
|
闪现消息(示例 20):由某个操作放入会话中的消息,由下一个页面显示,然后被丢弃。这是对 Post/Redirect/Get 模式的补充,应用程序中的所有表单都遵循该模式。共有两种类型:成功消息显示在页面顶部,错误消息显示在页面底部。
- 第 25 行:请求栈 ([RequestStack]),这是 [Symfony] 的一个服务,它知道当前请求,因此也知道其会话。共享服务不能通过构造函数接收请求本身:它只创建一次,可能被多个请求使用(一个主请求及其子请求);
- 第 41–44 行:会话闪现消息的“包”([getFlashBag]),其中 [add(type, message)] 用于补充该类型的列表。这正是 [addFlash] 方法在 [AbstractController] 中所做的事(示例 20);将其做成服务后,就可以在控制器之外放置消息,例如在身份验证器或监听器中。
[Message] 对象原样存储在会话中:[PHP] 对会话数据进行序列化(示例 20),并在下一次请求时重建它。在视图中,[app.flashes('errors')] 渲染该类型的消息列表,并将其从会话中移除。
11.15.3. src/Web/BaseController.php
| <?php
// =========================================================================
// src/Web/BaseController.php:应用程序控制器的父类。它
// 继承自 AbstractController(见示例 03),并添加了对手写表单的
// 防 CSRF 令牌的检查(见示例 21)。
// =========================================================================
namespace App\Web;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpKernel\Exception\HttpException;
abstract class BaseController extends AbstractController
{
// 手写表单的防 CSRF 令牌的标识符:整个应用程序只有一个
// (在视图中:csrf_token('rdvmedecins'))。Form 组件的
// 表单则各自有自己的令牌
public const CSRF = 'rdvmedecins';
// -----------------------------------------------------------------------
// 缺失或错误的防 CSRF 令牌:页面很可能是在包含该令牌的
// 会话过期之前显示的。错误 419,这是页面过期的(非官方
// 但很普遍的)代码:ErrorPage 监听器会显示
// “The page has expired: reload it, then try again.”
// -----------------------------------------------------------------------
protected function checkCsrf(Request $request): void
{
if (! $this->isCsrfTokenValid(self::CSRF, $request->request->getString('_token'))) {
throw new HttpException(419, 'invalid anti-CSRF token');
}
}
}
|
控制器的父类。视图中手动编写的表单(登录、注销、删除、预订等)包含一个防 CSRF 令牌(示例 21),其标识符为 [rdvmedecins]:这里一个标识符就足够了,因为所有这些操作都已经要求用户已登录或通过验证码。Form 组件中的每个表单都有自己的令牌,由该组件进行验证。
缺少令牌或令牌无效时,操作会以 419 错误终止(第 27–32 行),这是表示页面已过期的(非官方但被广泛使用的)代码:令牌存储在会话中,在会话结束前显示的页面所包含的令牌,服务器已不再识别。随后 [ErrorPage] 监听器会显示“页面已过期:请重新加载,然后再试一次。”[HttpException] 是通用的 HTTP 异常:其构造函数接收代码和一条消息(供日志使用,而非给用户看)。
11.15.4. src/Web/Utils.php
| <?php
// =========================================================================
// src/Web/Utils.php:Web 层的小型实用函数:
// - 日期:"yyyy-mm-dd",日期如 "Wednesday 23 September 2026";
// - 输入:读取浏览器发送的正整数、日期;
// - 用户:已登录的用户及其患者(Client 实体)。
// 静态方法无需对象即可调用(Utils::iso($day));其他方法
// 需要服务(当前请求、安全...):该类是一个
// 服务,由控制器通过其构造函数接收。
// =========================================================================
namespace App\Web;
use App\Entity\Client;
use App\Security\InvalidSession;
use App\Security\ConnectedUser;
use DateTimeImmutable;
use IntlDateFormatter;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
class Utils
{
// Security:Symfony 的安全服务,它知道当前请求的用户
// (由身份验证器确定的用户)
public function __construct(
private RequestStack $requests,
private Security $security,
private ApplicationModel $application,
) {
}
// ———————————————————————————————— 日期
// 如果 [$text] 是一个存在的、yyyy-mm-dd 格式的日期,则返回该日期;否则为 null。
// createFromFormat 接受 "2026-02-30"(它会变成 3 月 2 日):因此我们
// 检查回读的日期是否与收到的文本写法完全一致
public static function validDate(mixed $text): ?DateTimeImmutable
{
if (! is_string($text) || ! preg_match('/^\d{4}-\d{2}-\d{2}$/', $text)) {
return null;
}
// "!Y-m-d":感叹号将时间设为午夜
$date = DateTimeImmutable::createFromFormat('!Y-m-d', $text);
return $date !== false && $date->format('Y-m-d') === $text ? $date : null;
}
public static function iso(DateTimeImmutable $day): string
{
return $day->format('Y-m-d');
}
// "mercredi 23 septembre 2026" / "Wednesday 23 September 2026",取决于请求的语言
// (见示例 16)。ICU 模式:EEEE 完整的星期几,
// d 日,MMMM 完整的月份,y 年份
public function formatDay(DateTimeImmutable $day): string
{
$language = $this->requests->getCurrentRequest()?->getLocale() ?? 'en';
return (new IntlDateFormatter($language, IntlDateFormatter::NONE, IntlDateFormatter::NONE,
pattern: 'EEEE d MMMM y'))->format($day);
}
// ———————————————————————————————— 输入
// "3" -> 3;""、"abc"、"-2"、"+2"、null -> null
public static function positiveInteger(mixed $value): ?int
{
if (! is_string($value) || ! preg_match('/^\d{1,9}$/', $value)) {
return null;
}
$n = (int) $value;
return $n > 0 ? $n : null;
}
// ———————————————————————————————— 用户
// 已登录的用户。受保护的操作只有在用户存在时才会被调用;
// 作为预防措施,用户缺失会被视为会话过期
public function user(): ConnectedUser
{
$user = $this->security->getUser();
return $user instanceof ConnectedUser ? $user : throw new InvalidSession();
}
// -----------------------------------------------------------------------
// 与已登录用户对应的患者(Client 实体)。
//
// JWT 令牌只包含账户(users.id)的 id。对于 USER 角色,我们通过
// clients.user 列找到对应的客户。
//
// 如果没有,说明该账户在登录之后已被删除,
// 而其令牌仍然有效:我们将其视为会话
// 过期(见 InvalidSession)。
// -----------------------------------------------------------------------
public function connectedPatient(): Client
{
return $this->application->getClientByUserId($this->user()->userId)
?? throw new InvalidSession();
}
}
|
一些实用函数。静态方法无需对象即可调用([Utils::iso($day)]);其他方法需要服务:因此该类本身也是一个服务,由控制器通过其构造函数接收。
- 第 38–46 行:[yyyy-mm-dd] 或 [null] 参数的日期。两项检查:格式(正则表达式),然后是日期是否存在。[createFromFormat] 很宽容:2 月 30 日会变成 3 月 2 日。因此我们重新读取得到的日期,并验证它与收到的文本写法完全一致。格式中的 [!] 会将时间设为午夜(没有它,时间将是当前时间)。[mixed]:任意类型;
- 第 56–61 行:“Saturday 26 September 2026”或“samedi 26 septembre 2026”,取决于请求的语言。[IntlDateFormatter] (示例 16),使用的是模式 而不是样式:这些代码来自 ICU 库,[EEEE] 表示完整拼写的星期几,[d] 表示日,[MMMM] 表示完整拼写的月份,[y] 表示年份。参数 [pattern] 是按名称传递的:在签名中位于它之前且未提供值的参数,保留其默认值;
- 第 66–73 行:请求参数可以是字符串,例如 [null],甚至可以是数组([?doctorId[]=1],示例 10)。只接受数字(最多九位:以避免超出容量),并且该数必须严格为正;
- 第 79–83 行:已登录的用户,由身份验证器确定,由 [Security] 服务返回,该服务来自 [Symfony]。受保护的操作只会为已通过身份验证的用户调用,但用户缺失的情况仍按会话过期处理。[throw] 是一个表达式([PHP] 8):它可以出现在运算符 [? :] 中;
- 第 95–99 行:已登录用户的患者 ([Client])。令牌只包含账户 ID;客户通过 [clients.user] 列来识别。如果它不存在,说明该账户在用户登录之后已被删除:[InvalidSession]。
11.15.5. src/Twig/ViewsExtension.php
| <?php
// =========================================================================
// src/Twig/ViewsExtension.php:一个 Twig 扩展(见示例 16),它为视图
// 添加所有页面都需要的函数:
// - user() :已登录的用户(或 null),用于导航栏;
// - titles() :人员可能的称谓(Mr、Mme、Melle)。
// =========================================================================
namespace App\Twig;
use App\Form\PersonFieldsType;
use App\Security\AuthService;
use App\Security\ConnectedUser;
use Symfony\Bundle\SecurityBundle\Security;
use Symfony\Component\HttpFoundation\RequestStack;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;
class ViewsExtension extends AbstractExtension
{
public function __construct(
private Security $security,
private RequestStack $requests,
private AuthService $auth,
) {
}
public function getFunctions(): array
{
return [
new TwigFunction('user', $this->user(...)),
new TwigFunction('titles', fn () => PersonFieldsType::TITLES),
];
}
// -----------------------------------------------------------------------
// 由防火墙确定的用户。404 或 405 错误页面是在防火墙之前
// 构建的(失败的路由先于防火墙,见
// 示例 24):此时直接从令牌中读取用户,以使
// 错误页面的导航栏完整
// -----------------------------------------------------------------------
public function user(): ?ConnectedUser
{
$user = $this->security->getUser();
if ($user instanceof ConnectedUser) {
return $user;
}
$token = $this->requests->getMainRequest()?->cookies->getString(AuthService::COOKIE);
return $token ? $this->auth->currentUser($token) : null;
}
}
|
[Twig] 的一个扩展(示例 16),它为视图添加了所有页面都需要的两个函数:
- [user()]:已登录的用户,或者 [null],用于导航栏。通常,它来自 [Security] 服务(第 44 行)。然而,404 或 405 错误页面是在防火墙检查请求之前生成的:失败的路由优先于防火墙(示例 24)。因此直接从令牌中检索用户(第 48–49 行),使错误页面上的导航栏完整。[getMainRequest] 获取主请求;运算符 [?->] 在对象为 [null] 时返回 [null],而不调用该方法;
- [titles()]:一个人员可能的称谓([Mr]、[Mme]、[Melle]),它是人员表单类中的一个常量(见下文)。
[$this->user(...)] (第 31 行)是一等函数 ([PHP] 8.1)的语法:它创建一个调用该对象的 [user] 方法的函数。该扩展会自动声明为 [Twig],与示例 16 一样:容器会识别继承自 [AbstractExtension] 的类。
11.16. 字典
界面文本与该应用程序其他版本中的相同,那些版本将它们存储在嵌套的 JSON 文件中:
| {
"LOGIN": {
"TITLE": "Login",
"USERNAME": "Login"
}
}
|
[Flask] 版本在启动时将它们“扁平化”:[LOGIN.TITLE] 指向文本 [Login]。[Symfony] 的 YAML 字典也是如此(示例 22):嵌套的键用句点分隔。因此我们只是将 JSON 文件转换为 YAML,并将其他版本中的 [{{name}}] 参数替换为 ICU 语法的参数 [{name}] (文件名中的 [+intl-icu] 后缀,示例 22):
| APP:
TITLE: 'RdvMedecins'
LOGOUT: 'Log out'
DOCTORS:
ADDED: 'Doctor {name} has been added (login: {login}).'
ERRORS:
TOO_MANY_ATTEMPTS: 'Too many failed attempts. Try again in {minutes, plural, one {# minute} other {# minutes}}.'
|
文件 [translations/messages+intl-icu.fr.yaml] 和 [messages+intl-icu.en.yaml] 此处不再重复列出。在视图中,键用 [{{ 'APP.LOGOUT'|trans }}] 表示,带参数的文本则用 [{{ 'DOCTORS.ADDED'|trans({name: ..., login: ...}) }}] 表示。字典中缺失的键会原样显示,这会立即暴露遗漏(命令 [php bin/console debug:translation fr] 会列出视图使用但字典中缺失的键)。ICU 实现了以前版本无法做到的事情:使用 [plural] 格式处理复数 (“1 minute”、“15 minutes”)(示例 22)。我们新增了一个文本条目:[ERRORS.PAGE_EXPIRED],即 419 页面上的消息,其他版本中没有该条目。
表单错误消息也是这些字典中的键([ERRORS.FIRSTNAME_REQUIRED]……):验证组件使用 [messages] 域翻译它们,依据的是 [translation_domain: messages] 这一行,位于 [framework.yaml] 中。它们的参数对应于约束:[{limit}],表示密码的最小长度。
11.17. 表单
“人员”表单是 Form 组件的表单(示例 18 和 19):一个类型类描述字段及其约束;操作创建表单([createForm]),将请求传给它([handleRequest]),然后检查它是否已提交且有效([isSubmitted]、[isValid])。无效的表单会重新显示,并在字段下方显示用户的输入和错误消息(密码除外:[PasswordType] 字段绝不会重新显示)。每个表单的防 CSRF 令牌由该组件自行验证。
| <?php
// =========================================================================
// src/Form/PersonFieldsType.php:“人员”表单的字段及其
// 约束(见示例 18 和 19)。三个表单共享相同的身份
// 字段(称谓、名、姓):
//
// PersonFieldsType 称谓、名、姓
// ├─ PersonType + 可选的登录名 / 密码、版本
// │ (ADMIN 添加或修改医生 / 客户)
// ├─ RegistrationType + 必填的登录名 / 密码 / 确认
// │ (患者创建其账户)
// └─ MyAccountType + 登录名、可选的新密码、必填的
// 当前密码、版本
// (患者修改其账户)
//
// 子类继承自这个类(按 PHP 的含义):它们的 buildForm 先
// 调用父类的 buildForm,然后添加自己的字段。
//
// 这些表单没有数据类(data_class,见示例 19):经过验证的
// 输入是一个关联数组,由 data() 方法将其转换为
// 供业务层使用的 PersonData。
//
// 标签、帮助文本和错误消息是字典中的键:
// Form 组件翻译标签和帮助文本,Validator
// 组件翻译消息(见 config/packages/framework.yaml)。
// Sequentially:按顺序检查约束,并且检查
// 在第一个不满足的约束处停止 - 每个字段只有一条消息。
// 最大长度与 SQL 列的相同。
// =========================================================================
namespace App\Form;
use App\Business\PersonData;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\CallbackTransformer;
use Symfony\Component\Form\Extension\Core\Type\ChoiceType;
use Symfony\Component\Form\Extension\Core\Type\TextType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
abstract class PersonFieldsType extends AbstractType
{
public const TITLES = ['Mr', 'Mme', 'Melle'];
// 登录名:小写字母、数字、点、连字符、下划线 - 最多 30 个字符
public const LOGIN_FORMAT = '/^[a-z0-9._-]{1,30}$/';
// 患者选择的密码的最小长度
public const PASSWORD_MIN = 6;
public function buildForm(FormBuilderInterface $builder, array $options): void
{
$builder
// array_combine:['Mr' => 'Mr', ...],每个选项的标签
// 和值;choice_translation_domain false:称谓不翻译
->add('title', ChoiceType::class, [
'label' => 'PERSONS.TITLE_LABEL',
'choices' => array_combine(self::TITLES, self::TITLES),
'choice_translation_domain' => false,
'invalid_message' => 'ERRORS.INVALID_TITLE',
'constraints' => [new Assert\NotBlank(message: 'ERRORS.INVALID_TITLE')],
])
->add('first_name', TextType::class, [
'label' => 'PERSONS.FIRSTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.FIRSTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.FIRSTNAME_TOO_LONG'),
])],
])
->add('last_name', TextType::class, [
'label' => 'PERSONS.LASTNAME_LABEL',
'attr' => ['maxlength' => 20],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LASTNAME_REQUIRED'),
new Assert\Length(max: 20, maxMessage: 'ERRORS.LASTNAME_TOO_LONG'),
])],
]);
}
// 通用选项:无效的表单原样发回给浏览器,
// 不经过浏览器自身的验证(见示例 19:以服务器
// 为准);防 CSRF 令牌错误时的消息
public function configureOptions(OptionsResolver $resolver): void
{
$resolver->setDefaults([
'attr' => ['novalidate' => 'novalidate'],
'csrf_message' => 'ERRORS.PAGE_EXPIRED',
]);
}
// -----------------------------------------------------------------------
// 登录名字段,子表单共用。登录名始终为
// 小写:一个转换器(CallbackTransformer)在验证之前
// 转换输入。它的第一个函数将表单的值转换为
// 显示的文本(这里无需处理),第二个函数将输入转换为表单的值
// -----------------------------------------------------------------------
protected static function addLogin(FormBuilderInterface $builder, array $options): void
{
$builder->add('login', TextType::class, ['label' => 'PERSONS.LOGIN_LABEL', 'required' => false,
'attr' => ['maxlength' => 30, 'autocomplete' => 'off'], ...$options]);
$builder->get('login')->addModelTransformer(new CallbackTransformer(
fn (?string $login) => $login,
fn (?string $login) => $login === null ? null : mb_strtolower($login)));
}
// 经过验证的输入 -> 业务层期望的数据。空
// 字段为 null(Form 组件会这样转换它们)
public static function data(array $input): PersonData
{
$password = $input['password'] ?? null;
return new PersonData($input['title'], $input['last_name'], $input['first_name'],
$input['login'] ?? null, $password === '' ? null : $password,
isset($input['version']) && ctype_digit((string) $input['version']) ? (int) $input['version'] : null);
}
}
|
三个表单共享相同的身份字段(称谓、名、姓):管理员表单(用于医生或客户)、患者账户创建表单和“管理我的账户”。它们共同的父类是抽象类;它的每个子类都会扩展这些字段。这些表单都没有数据类(示例 19 中的 [data_class] 选项):它们的数据是一个关联数组,每个字段对应一个元素。
- 第 44–50 行:输入规则,以常量形式给出,视图也会读取它们(称谓列表,通过 [Twig] 扩展 的函数 [titles()]);
- 第 57–63 行:称谓,一个列表([ChoiceType],示例 18)。[array_combine] 生成数组 [['Mr' => 'Mr', ...]]:每个选项的标签及其值。[choice_translation_domain: false]:称谓不是翻译键。[invalid_message]:当值不在列表中时的消息(手工构造的请求);
- 第 64–79 行:名和姓。约束 [Sequentially] (示例 09)按顺序检查其各项约束,并在第一个不满足的约束处停止:每个字段只有一条消息。[Length(max: 20)]:最多 20 个字符;列长度为 SQL;HTML 属性 [maxlength] 可防止输入更多字符。输入开头和结尾的空格由 Form 组件自行删除(文本字段的 [trim] 选项设置为 [true]),空输入会变成 [null];而带有 [PasswordType] 选项的字段则不会被清理:空格可以是密码的一部分;
- 第 85–91 行:通用选项。[novalidate] 在提交表单时禁用浏览器验证([required]、[maxlength]……):由服务器执行验证,其结果为最终结果(示例 19)。[csrf_message]:防 CSRF 令牌无效时的消息,即 419 页面上的那条;
- 第 99–106 行:登录名,三个表单通用,每个表单再添加各自的选项(运算符 [...] 将一个数组的元素添加到另一个数组中;两者都有的键取最后一个值)。登录名始终为小写:一个转换器 在输入被验证之前对其进行转换。模型转换器([addModelTransformer])有两个函数:第一个将表单数据转换为显示的值(在本例中无需任何操作),第二个将输入的值转换为表单数据。[CallbackTransformer] 基于这两个函数创建一个转换器;
- 第 110–116 行:验证后的输入会被转换为 [PersonData] 供业务层使用:业务层不知道表单的存在。空密码为 [null] (不变,或取默认值);版本(乐观锁的隐藏字段,例如 28)是整数,或者 [null]。
| <?php
// src/Form/PersonType.php:医生或客户的表单(ADMIN):
// 可选的登录名和密码(见 src/Business/PersonData.php)。
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\OptionsResolver\OptionsResolver;
use Symfony\Component\Validator\Constraints as Assert;
class PersonType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
$creation = $options['creation'];
// 空字段是被接受的:约束只适用于已输入的值
self::addLogin($builder, [
'help' => $creation ? 'PERSONS.LOGIN_HELP_CREATE' : 'PERSONS.LOGIN_HELP_EDIT',
'constraints' => [new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN')],
]);
$builder->add('password', PasswordType::class, [
'label' => 'PERSONS.PASSWORD_LABEL',
'required' => false,
'help' => $creation ? 'PERSONS.PASSWORD_HELP_CREATE' : 'PERSONS.PASSWORD_HELP_EDIT',
'attr' => ['maxlength' => 72, 'autocomplete' => 'new-password'],
// 最多 72 个字符:超过后,bcrypt 会忽略其余部分
'constraints' => [new Assert\Length(max: 72, maxMessage: 'ERRORS.PASSWORD_TOO_LONG')],
]);
// 修改:所显示记录的版本,放在隐藏字段中(
// 乐观锁)
if (! $creation) {
$builder->add('version', HiddenType::class);
}
}
// 我们自己的一个选项(见示例 28):创建表单或修改表单
public function configureOptions(OptionsResolver $resolver): void
{
parent::configureOptions($resolver);
$resolver->setDefaults(['creation' => true]);
}
}
|
管理员表单。[parent::buildForm] (第 17 行)添加父类的字段;接下来是用户名和密码,它们是可选的:约束只适用于已输入的值([NotBlank] 除外),因此空字段是被接受的。[Regex] 验证登录名的格式;[Length(max: 72)] 限制密码长度:[bcrypt] 只考虑前 72 个字节(示例 25)。选项 [creation] (第 40–44 行)是我们设计的选项,声明时带有默认值(示例 28),用于区分创建和修改:提示文字不同(“可选:默认为小写的姓”、“留空则保持不变”),并且只有修改时才有隐藏的版本字段。
| <?php
// src/Form/RegistrationType.php:“创建患者账户”:必填的登录名、密码和
// 确认。
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class RegistrationType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'help' => 'REGISTRATION.LOGIN_HELP',
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
$builder->add('password', RepeatedType::class, self::repeatedPassword(true));
}
// -----------------------------------------------------------------------
// 密码及其确认:一个重复(REPEATED)字段(见示例 19),其
// 两次输入必须相同(否则:invalid_message)。为
// 注册(必填)和患者账户(可选)所共用。
// {limit}:在 PASSWORD_TOO_SHORT 消息中,表示最小长度;
// help_translation_parameters:帮助文本的参数
// -----------------------------------------------------------------------
public static function repeatedPassword(bool $required): array
{
$length = new Assert\Length(min: self::PASSWORD_MIN, max: 72,
minMessage: 'ERRORS.PASSWORD_TOO_SHORT', maxMessage: 'ERRORS.PASSWORD_TOO_LONG');
return [
'type' => PasswordType::class,
'required' => $required,
'invalid_message' => 'ERRORS.PASSWORDS_DIFFER',
'first_options' => [
'label' => $required ? 'PERSONS.PASSWORD_LABEL' : 'MY_ACCOUNT.NEW_PASSWORD_LABEL',
'help' => $required ? 'REGISTRATION.PASSWORD_HELP' : 'PERSONS.PASSWORD_HELP_EDIT',
'help_translation_parameters' => ['min' => self::PASSWORD_MIN],
],
'second_options' => ['label' => 'ACCOUNT.CONFIRMATION_LABEL'],
'options' => ['attr' => ['maxlength' => 72, 'autocomplete' => 'new-password']],
'constraints' => $required
? [new Assert\Sequentially([new Assert\NotBlank(message: 'ERRORS.PASSWORD_REQUIRED'), $length])]
: [$length],
];
}
}
|
创建患者账户:登录名和密码是必填的,并且密码必须确认。密码是一个重复字段([RepeatedType],示例 19):两个 [PasswordType] 字段,其输入必须一致(否则,会在第一个字段下方显示 [invalid_message] 消息)。它的选项由一个静态方法生成,与“管理我的账户”共享(第 36–55 行):
- [first_options] 和 [second_options]:两个字段各自的选项;[options]:它们共有的选项;
- [help_translation_parameters]:帮助文本“At least {min} characters.”的参数;
- 只有患者选择的密码才要求最小长度(6 个字符)。消息 [ERRORS.PASSWORD_TOO_SHORT] 包含 [{limit}],这是约束 [Length] 提供给其消息的参数;
- [autocomplete="new-password"]:浏览器会提示生成密码,而不是用已保存的密码填充该字段。
| <?php
// src/Form/MyAccountType.php:“管理我的账户”(患者):必填的登录名、
// 可选的新密码、必填的当前密码。
namespace App\Form;
use Symfony\Component\Form\Extension\Core\Type\HiddenType;
use Symfony\Component\Form\Extension\Core\Type\PasswordType;
use Symfony\Component\Form\Extension\Core\Type\RepeatedType;
use Symfony\Component\Form\FormBuilderInterface;
use Symfony\Component\Validator\Constraints as Assert;
class MyAccountType extends PersonFieldsType
{
public function buildForm(FormBuilderInterface $builder, array $options): void
{
parent::buildForm($builder, $options);
self::addLogin($builder, [
'required' => true,
'attr' => ['maxlength' => 30, 'autocomplete' => 'username'],
'constraints' => [new Assert\Sequentially([
new Assert\NotBlank(message: 'ERRORS.LOGIN_REQUIRED'),
new Assert\Regex(self::LOGIN_FORMAT, message: 'ERRORS.INVALID_LOGIN'),
])],
]);
// 可选:为空 = 密码不变
$builder->add('password', RepeatedType::class, RegistrationType::repeatedPassword(false));
// 当前密码,任何账户修改都必须提供;mapped
// false:它不属于表单的数据,而是单独读取
$builder->add('current_password', PasswordType::class, [
'label' => 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL',
'help' => 'MY_ACCOUNT.CURRENT_PASSWORD_HELP',
'mapped' => false,
'attr' => ['maxlength' => 72, 'autocomplete' => 'current-password'],
'constraints' => [new Assert\NotBlank(message: 'ERRORS.CURRENT_PASSWORD_REQUIRED')],
]);
$builder->add('version', HiddenType::class);
}
}
|
“管理我的账户”:新密码是可选的(为空:保持不变),当前密码是必填的。[mapped: false] (第 33 行):当前密码不属于表单数据([getData()] 不包含它);操作通过 [$form->get('current_password')->getData()] 单独读取它。它在这里不进行验证,而是由操作来验证:错误的密码必须被尝试次数限制器计为一次登录失败。([Symfony] 有一个约束 [UserPassword],它将输入的密码与已登录用户的密码进行比较;该约束在这里不适用:我们的已登录用户 [ConnectedUser] 不包含其密码的哈希值。)
11.18. 视图模板
[src/Views] 文件夹包含视图模板:由操作创建、视图只是读取的对象。所有页面都遵循的规则:视图中没有逻辑。操作准备好已经格式化的数据(“Ms. Marie PELISSIER”、“8:00 – 8:20”),并已根据用户的角色进行过滤;视图将这些数据放入 HTML 中。所有这些类都是 [readonly] 类型,并且只有属性,这些属性由其构造函数初始化。该文件夹被排除在服务之外([config/services.yaml]):它们是数据,而不是服务。
| <?php
// src/Views/OptionView.php:下拉列表(医生、患者)的一个选项。
//
// src/Views 文件夹包含“视图模型”:由操作
// 一次性构建、视图只是读取的对象。所有页面
// 遵循的规则:视图中没有逻辑。操作
// 准备好已经格式化的数据("Mme Marie PELISSIER"、
// "8:00 - 8:20"、selected = true...),并已根据
// 用户的角色过滤;视图只是将它们放入 HTML 中。
namespace App\Views;
readonly class OptionView
{
public function __construct(
public int $id,
public string $label,
public bool $selected,
) {
}
}
|
下拉列表中的一个选项:ID、标签,以及该选项是否被选中?
| <?php
// src/Views/ScheduleRow.php:所显示日程的一行(一个时间段)。
namespace App\Views;
readonly class ScheduleRow
{
public function __construct(
public int $slotId,
public string $time, // "8:00 - 8:20"
public bool $free,
// 已占用时间段所显示的姓名;null = "Booked"
public ?string $patient,
public bool $mine, // 已登录患者的预约
public bool $bookable, // 是否显示“Book”按钮?
public string $bookUrl,
// 仅在显示“Cancel”按钮时设置
public ?int $appointmentId,
) {
}
}
|
日程表中的一个条目:一个时间段,以及已登录用户被授权查看和对其执行的操作。[patient] 仅在用户有权查看患者姓名时才会填充;[bookable] 表示是否显示“Book”按钮;[appointmentId] 表示是否显示“Cancel”按钮。
| <?php
// src/Views/ScheduleView.php:所显示的日程:医生、日期、各行。
namespace App\Views;
readonly class ScheduleView
{
/** @param list<ScheduleRow> $rows */
public function __construct(
public string $doctor, // "Mme Marie PELISSIER"
public string $day, // "Wednesday 23 September 2026"
public array $rows,
) {
}
}
|
| <?php
// src/Views/BookingView.php:时间段的预订对话框。
namespace App\Views;
readonly class BookingView
{
/** @param list<OptionView> $clients */
public function __construct(
public int $slotId,
public string $time,
// ADMIN / DOCTOR:可供选择的患者
public array $clients,
// USER:患者就是其本人
public ?string $patient,
) {
}
}
|
显示的日程表和预订窗口:对管理员和医生,是可供选择的患者列表;对患者,则是其本人的姓名。注释 [/** @param list<ScheduleRow> $rows */] 为编辑器和分析工具指明了数组的内容:[PHP] 只能声明类型 [array]。
| <?php
// src/Views/PersonKeys.php:每种人员类型(医生或客户)专用的翻译键,
// 用于共用的视图 persons/list 和
// persons/form。
namespace App\Views;
readonly class PersonKeys
{
public function __construct(
public string $title, // "Doctors"
public string $add, // "Add a doctor"
public string $edit, // "Edit a doctor"
public string $empty, // "No doctors."
public string $confirmDelete, // "Delete this doctor... ?"
public string $added, // "Doctor {name} has been added (login: {login})."
public string $edited,
public string $deleted,
) {
}
// 字典某个部分的八个键("DOCTORS"、"CLIENTS")
public static function of(string $section): self
{
return new self("$section.TITLE", "$section.ADD", "$section.EDIT", "$section.EMPTY",
"$section.DELETE_CONFIRM", "$section.ADDED", "$section.UPDATED", "$section.DELETED");
}
}
|
医生或客户专用的翻译键,用于它们共有的两个视图。静态方法 [of] (第 23–27 行)为字典的某一部分生成八个键:[PersonKeys::of('DOCTORS')] 生成 [DOCTORS.TITLE]、[DOCTORS.ADD]……[new self(...)] 创建该类本身的一个对象。
| <?php
// src/Views/AppointmentView.php:患者专区中一个即将到来的预约。
namespace App\Views;
readonly class AppointmentView
{
public function __construct(
public int $id,
public string $day, // "Wednesday 23 September 2026"
public string $time, // "8:00 - 8:20"
public string $doctor, // "Mme Marie PELISSIER"
public string $scheduleUrl, // 医生在当天的日程
) {
}
}
|
患者区域中即将到来的预约。
11.19. Web 层:路由和控制器
11.19.1. 路由
路由由控制器的 [#[Route]] 属性描述(示例 02),这些控制器由 [config/routes.yaml] 文件加载。[debug:router] 命令会列出所有路由,以及它们的名称、方法和路径:
| $ php bin/console debug:router
--------------------- ---------- ----------------------
Name Method Path
--------------------- ---------- ----------------------
home GET /
login GET /login
login_submit POST /login
logout POST /logout
clients_list GET /clients
clients_add GET|POST /clients/add
clients_edit GET|POST /clients/{id}/edit
clients_delete POST /clients/{id}/delete
doctors_list GET /doctors
doctors_add GET|POST /doctors/add
doctors_edit GET|POST /doctors/{id}/edit
doctors_delete POST /doctors/{id}/delete
language GET /language/{code}
area GET /my-area
area_cancel POST /my-area/cancel
account GET|POST /my-account
account_delete POST /my-account/delete
registration_access POST /register/access
registration GET|POST /register
schedule GET /schedule
schedule_book POST /schedule/book
schedule_cancel POST /schedule/cancel
--------------------- ---------- ----------------------
|
URL 文件与应用程序的其他版本相对应:修改和删除医生是 POST 请求([/doctors/{id}/edit], [/doctors/{id}/delete]),而不是示例 28 中的 PUT 和 DELETE。代码总是根据路由名称生成 URL([redirectToRoute('login')]、视图中的 [path('schedule')] ,示例 04):更改 URL 只需修改其 [#[Route]] 属性。
访问规则不在控制器中,而在 [access_control] 规则中,位于 [config/packages/security.yaml],如上所示:每个 URL 前缀 一条规则([^/(doctors|clients)] 用于管理员,[^/my-] 用于患者……),以及最后一条规则,要求所有其他 URL 都必须是已通过身份验证的用户。应用程序的 URL 路由正是为此而选择的:同一角色的所有页面都以相同的方式开头。不匹配任何路由的 URL 路由会返回 404 页面,即使对匿名访问者也是如此;对仅以 POST 方式存在的 URL([/logout])发出 GET 请求,会得到 405 页面,并呈现为“页面未找到”(处理程序 [ErrorPage])。
11.19.2. src/Controller/LanguageController.php
| <?php
// =========================================================================
// src/Controller/LanguageController.php:GET /language/fr、GET /language/en:导航栏上的
// 两个 FR / EN 按钮。公开路由:必须能够在登录之前
// 更改语言。
//
// 该选择会被记在 Cookie 中:在之后的每次请求中,监听器
// SetLanguage 会再次读取它,并设置请求的语言。然后我们返回到
// 来源页面(见示例 22)。
// =========================================================================
namespace App\Controller;
use App\EventListener\SetLanguage;
use App\Web\BaseController;
use Symfony\Component\DependencyInjection\Attribute\Autowire;
use Symfony\Component\HttpFoundation\Cookie;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
class LanguageController extends BaseController
{
public function __construct(#[Autowire(env: 'bool:COOKIE_SECURE')] private bool $cookieSecure)
{
}
// {code} 被限制为受支持的语言(requirements):/language/de 会得到 404 页面
#[Route('/language/{code}', name: 'language', requirements: ['code' => 'fr|en'], methods: ['GET'])]
public function change(Request $request, string $code): Response
{
$response = $this->redirect($this->originPage($request));
$response->headers->setCookie(Cookie::create(SetLanguage::COOKIE, $code)
->withExpires(new \DateTimeImmutable('+1 year'))
->withSecure($this->cookieSecure)
->withHttpOnly(true)
->withSameSite(Cookie::SAMESITE_LAX));
return $response;
}
// -----------------------------------------------------------------------
// 上一页,根据浏览器发送的 HTTP "Referer" 头部。
// 只保留其路径(/schedule?...):如果重定向到请求提供的完整
// 地址,就可能把用户送到
// 另一个站点(所谓“开放重定向”漏洞)。
// -----------------------------------------------------------------------
private function originPage(Request $request): string
{
$referer = $request->headers->get('Referer');
$url = $referer ? parse_url($referer) : false;
$path = $url['path'] ?? '';
// "//site.com/..." 会被浏览器理解为另一个站点上的地址
// :同样拒绝
if (! isset($url['scheme']) || ! str_starts_with($path, '/') || str_starts_with($path, '//')
|| str_starts_with($path, '/language/')) {
return '/';
}
return isset($url['query']) ? "$path?{$url['query']}" : $path;
}
}
|
导航栏上的 FR / EN 按钮:语言选择存储在一个 Cookie 中,保存一年(示例 22),然后浏览器返回到它来自的页面。该 Cookie 是 [HttpOnly] 的:页面上的 [JavaScript] 不需要读取它。它没有签名:监听器 [SetLanguage] 会验证它的值,未知的值会回退为英语(参见关于范围的章节)。
- 第 29 行:[requirements: ['code' => 'fr|en']] 只接受参数 [{code}]的这两个值:[/language/de] 不对应任何路由(404 页面);
- 第 47–59 行:上一页由头部
HTTP ***[Referer] 指定,浏览器会随请求发送该头部。该数据由客户端提供,因此不可信:如果重定向到请求中的完整 URL,攻击者就可以通过指向 [/language/fr] 且包含伪造的 ***[Referer] 的链接(即所谓的 “开放重定向” 漏洞),把用户送到自己的网站。因此,我们只保留路径 和参数([/schedule?doctorId=1&...]),由 [parse_url] 函数提取,该函数来自 [PHP],它将 URL 拆分为各个部分([scheme]、[host]、[path]、[query]……)。以 [//] 开头的路径也会被拒绝:浏览器会将 [//site.com/page] 解释为另一个站点上的地址。最后,我们不能返回到 [/language/...]:那会形成循环。
11.19.3. src/Controller/ScheduleController.php
| <?php
// =========================================================================
// src/Controller/ScheduleController.php:日程页面:选择医生和
// 日期,该医生在该日的日程,预约的预订和
// 取消。
//
// GET /schedule?doctorId=1&day=2026-09-23 页面
// GET /schedule?doctorId=1&day=2026-09-23&book=7 同一页面,并
// 打开
// 7 号时间段的预订对话框
// POST /schedule/book 创建预约
// POST /schedule/cancel 取消预约
//
// 整个页面由其 URL 描述:可以重新加载、加入书签,
// 可以使用浏览器的“后退”按钮 - 无需一行
// JavaScript。
//
// 每种角色能看到什么以及能做什么:
//
// | 角色 | 显示的已占用时间段 | Book | Cancel |
// |───────────────|───────────────────────────────────|────────────────────|─────────|
// | ADMIN, DOCTOR | 患者的姓名 | 为患者预订 | 是 |
// | | | 从列表中选择 | |
// | USER(患者) | "Booked",如果是自己的预约则 | 为自己预订,如果 | 否 (*) |
// | | 显示其本人的姓名 | 没有即将到来的 | |
// | | | 预约 | |
//
// (*) 患者在其“My area”页面中取消自己的预约。
//
// 保密性:对于患者,其他患者的姓名并不是
// 简单地被视图隐藏 - 而是从未传递给视图。因此发送给浏览器的 HTML
// 不包含它,甚至不以隐藏形式包含(否则简单的“查看页面
// 源代码”就会将其暴露)。
//
// 不能预订过去的时间:“Book”按钮只出现在
// 今天及之后的日期(并且业务层无论如何都会拒绝过去的
// 预订)。
//
// 安全:所有 /schedule URL 都需要已通过身份验证的用户,
// 而 /schedule/cancel 需要 ADMIN 或 DOCTOR 角色(见 config/packages/security.yaml)。
// =========================================================================
namespace App\Controller;
use App\Domain\DoctorDaySchedule;
use App\Entity\Client;
use App\Entity\Person;
use App\Entity\Role;
use App\Business\Dates;
use App\Business\BusinessException;
use App\Views\ScheduleView;
use App\Views\ScheduleRow;
use App\Views\OptionView;
use App\Views\BookingView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use DateTimeImmutable;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/schedule')]
class ScheduleController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private Utils $utils,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// GET /schedule
// URL 的参数按原样读取($request->query),以区分
// 缺失的参数(null)和空参数(?doctorId=)。
// -----------------------------------------------------------------------
#[Route('', name: 'schedule', methods: ['GET'])]
public function show(Request $request): Response
{
$error = null;
$user = $this->utils->user();
$rights = $this->rights();
// 日期:如果 URL 中的日期有效则使用它,否则使用今天
$day = Dates::today();
$rawDay = $request->query->get('day');
if ($rawDay !== null) {
$requestedDay = Utils::validDate($rawDay);
if ($requestedDay !== null) {
$day = $requestedDay;
} else {
$error = 'ERRORS.INVALID_DATE';
}
}
$bookableDay = $day >= Dates::today();
// 医生:使用 URL 中的医生;如果没有,则对已登录的医生使用其本人
$rawDoctorId = $request->query->get('doctorId');
$doctorId = Utils::positiveInteger($rawDoctorId);
if ($rawDoctorId === null && $user->role === Role::DOCTOR) {
$doctorId = $this->application->getDoctorByUserId($user->userId)?->getId();
}
// 医生下拉列表
$doctors = array_map(fn (Person $d) => self::option($d, $d->getId() === $doctorId),
$this->application->getAllDoctors());
// 日程,如果已选择医生(并且日期有效)
$schedule = null;
if ($doctorId !== null && $error === null) {
$doctorSchedule = $this->application->getDoctorDaySchedule($doctorId, $day);
if ($doctorSchedule === null) {
$error = 'ERRORS.DOCTOR_NOT_FOUND';
} else {
$schedule = $this->scheduleView($doctorSchedule, $rights, $bookableDay);
}
}
// 预订对话框:仅当所请求的时间段可以被该用户预订时
// 才显示。array_find:第一个满足
// 条件的元素(如果没有则为 null)
$booking = null;
$slotId = Utils::positiveInteger($request->query->get('book'));
if ($schedule !== null && $slotId !== null) {
$row = array_find($schedule->rows,
fn (ScheduleRow $r) => $r->slotId === $slotId && $r->bookable);
if ($row !== null) {
$booking = new BookingView(
$row->slotId,
$row->time,
$rights['manager']
? array_map(fn (Client $c) => self::option($c, false), $this->application->getAllClients())
: [],
$rights['patient']?->label());
}
}
return $this->render('schedule.html.twig', [
'pageTitle' => 'SCHEDULE.PAGE_TITLE',
'error' => $error ? new Message($error) : null,
'doctors' => $doctors,
'doctorId' => $doctorId,
'day' => Utils::iso($day),
'schedule' => $schedule,
'booking' => $booking,
// 显示的日程,不带预订对话框
'backUrl' => $doctorId !== null ? $this->scheduleUrl($doctorId, $day) : $this->generateUrl('schedule'),
'info' => $this->patientInfo($rights, $schedule),
]);
}
// -----------------------------------------------------------------------
// POST /schedule/book 字段:doctorId、day、slotId、clientId
//
// 对于患者(USER),clientId 字段会被忽略:他们始终为
// 自己预订。信任浏览器发送的字段
// 会让狡猾的患者能够以另一位患者的名义预订。
//
// “Post / Redirect / Get”模式:无论结果如何,这里都不构建页面
// - 留下一条闪现消息,然后重定向到日程
// (见示例 20)。
// -----------------------------------------------------------------------
#[Route('/book', name: 'schedule_book', methods: ['POST'])]
public function book(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$slotId = Utils::positiveInteger($request->request->get('slotId'));
if ($doctorId === null || $slotId === null) {
// -> “无效请求”页面(见 src/EventListener/ErrorPage.php)
throw new BadRequestHttpException('invalid schedule or slot');
}
$user = $this->utils->user();
if ($user->isPatient()) {
$client = $this->utils->connectedPatient();
} else {
$clientId = Utils::positiveInteger($request->request->get('clientId'));
if ($clientId === null) {
// 没有选择患者:预订对话框会再次打开
$this->flash->error('ERRORS.CHOOSE_PATIENT');
return $this->redirect($this->scheduleUrl($doctorId, $day, $slotId));
}
$client = $this->application->getClientById($clientId);
}
$slot = $this->application->getSlotById($slotId);
if ($client === null) {
$this->flash->error('ERRORS.PATIENT_NOT_FOUND');
} elseif ($slot === null || $slot->getDoctor()->getId() !== $doctorId) {
$this->flash->error('ERRORS.SLOT_NOT_FOUND');
} else {
try {
// 规则(不能是过去的时间、每位患者只能有一个即将到来的
// 预约、时间段空闲)由业务层检查
$this->application->addAppointment($day, $slot, $client);
$this->flash->success('SCHEDULE.BOOKED');
} catch (BusinessException $e) {
// 相同的规则,但当预订者是患者
// 本人时,使用第二人称的消息(“You already have...”而不是
// “This patient...”)。其他异常(真正的异常情况)不会被
// 捕获:500 页面。
if ($e->key === 'ERRORS.PATIENT_HAS_UPCOMING_APPOINTMENT' && $user->isPatient()) {
$this->flash->error('SCHEDULE.ALREADY_BOOKED_INFO');
} else {
$this->flash->error($e->key, $e->params);
}
}
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// POST /schedule/cancel 字段:appointmentId、doctorId、day
// (患者在“My area”而不是在这里取消自己的预约)
// -----------------------------------------------------------------------
#[Route('/cancel', name: 'schedule_cancel', methods: ['POST'])]
public function cancel(Request $request): Response
{
$this->checkCsrf($request);
[$doctorId, $day] = $this->requestedSchedule($request);
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
if ($doctorId === null || $appointmentId === null) {
throw new BadRequestHttpException('invalid schedule or appointment');
}
$appointment = $this->application->getAppointmentById($appointmentId);
if ($appointment === null) {
// 已经被取消(被其他人,或由于双击)
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirect($this->scheduleUrl($doctorId, $day));
}
// -----------------------------------------------------------------------
// 谁已登录,他们在此页面上被允许做什么?
// manager:ADMIN 或 DOCTOR;
// patient:已登录的客户(USER 角色),否则为 null;
// patientCanBook:没有即将到来的预约的 USER。
// -----------------------------------------------------------------------
private function rights(): array
{
if (! $this->utils->user()->isPatient()) {
return ['manager' => true, 'patient' => null, 'patientCanBook' => false];
}
$patient = $this->utils->connectedPatient();
$upcoming = $this->application->getClientUpcomingAppointments($patient->getId());
return ['manager' => false, 'patient' => $patient, 'patientCanBook' => $upcoming === []];
}
// -----------------------------------------------------------------------
// 医生的日程,为视图格式化,并根据权限过滤
// -----------------------------------------------------------------------
private function scheduleView(DoctorDaySchedule $doctorSchedule, array $rights, bool $bookableDay): ScheduleView
{
$doctorId = $doctorSchedule->doctor->getId();
$day = $doctorSchedule->day;
$rows = [];
foreach ($doctorSchedule->doctorDaySlots as $dds) {
$slot = $dds->slot;
$appointment = $dds->appointment;
$free = $appointment === null;
// 是已登录患者的预约吗?
$mine = $appointment !== null && $rights['patient'] !== null
&& $appointment->getClient()->getId() === $rights['patient']->getId();
$rows[] = new ScheduleRow(
slotId: $slot->getId(),
time: $slot->time(),
free: $free,
// 保密性的关键点:患者只会收到自己预约的姓名;
// 对于其他预约,为 null(视图显示“Booked”)
patient: $appointment !== null && ($rights['manager'] || $mine) ? $appointment->getClient()->label() : null,
mine: $mine,
bookable: $free && $bookableDay && ($rights['manager'] || $rights['patientCanBook']),
bookUrl: $this->scheduleUrl($doctorId, $day, $slot->getId()),
appointmentId: $appointment !== null && $rights['manager'] ? $appointment->getId() : null);
}
return new ScheduleView($doctorSchedule->doctor->label(), $this->utils->formatDay($day), $rows);
}
// ———————————————————————————————— 实用函数
// POST 表单的隐藏字段 doctorId / day;如果它们
// 无效则为 [null, null]
private function requestedSchedule(Request $request): array
{
$doctorId = Utils::positiveInteger($request->request->get('doctorId'));
$day = Utils::validDate($request->request->get('day'));
return $doctorId === null || $day === null ? [null, null] : [$doctorId, $day];
}
// /schedule?doctorId=1&day=2026-09-23[&book=7]:generateUrl 将不属于路径参数的参数
// 附加到 URL 的末尾(见示例 16)
private function scheduleUrl(int $doctorId, DateTimeImmutable $day, ?int $book = null): string
{
$params = ['doctorId' => $doctorId, 'day' => Utils::iso($day)];
if ($book !== null) {
$params['book'] = $book;
}
return $this->generateUrl('schedule', $params);
}
private static function option(Person $p, bool $selected): OptionView
{
return new OptionView($p->getId(), $p->label(), $selected);
}
// -----------------------------------------------------------------------
// 向已经有即将到来的预约的患者显示的提示消息
// (说明为什么没有“Book”按钮),或者为 null。如果其
// 预约出现在所显示的日程中(蓝色),则无需显示:这发生在
// 他们刚刚预订之后,此时该消息就显得不合时宜。
// array_any:是否至少有一个元素满足条件?
// -----------------------------------------------------------------------
private function patientInfo(array $rights, ?ScheduleView $schedule): ?string
{
if ($rights['patient'] === null || $rights['patientCanBook']) {
return null;
}
$appointmentShown = $schedule !== null && array_any($schedule->rows, fn (ScheduleRow $r) => $r->mine);
return $appointmentShown ? null : 'SCHEDULE.ALREADY_BOOKED_INFO';
}
}
|
应用程序的主页面。头部注释概述了每个用户能看到什么以及能做什么。类的 [#[Route('/schedule')]] 属性(第 66 行)为其所有路由指定了路径的开头(示例 02):路由 [''] 就是 [/schedule] 本身。
11.19.3.1. 页面上的 URL
整个页面由其 URL 描述:[/schedule?doctorId=1&day=2026-09-26] 显示 1 号医生在该日的日程;[&book=4] 还会打开 4 号时间段的预订窗口。无需一行 [JavaScript] 代码,就可以重新加载页面、将其加入书签或使用浏览器的“后退”按钮。页面顶部的表单(用于选择医生和日期)是一个 GET 表单(示例 17):它使用新的参数重新加载页面。预约预订窗口通过一个简单的链接打开,并通过指向同一页面但不带 [book] 参数的链接关闭。
11.19.3.2. GET /schedule
第 81–154 行:
- URL 的参数按原样读取([$request->query->get('day')]),不经过 [Symfony] 的验证:缺少参数([null])不是错误(系统默认使用今天或“无医生”);无效的日期是错误,显示在页面底部(医生和日期的选择仍然可见,但不显示日程表);不是正整数的医生或时间段编号会被直接忽略;
- 未选择医生的已登录用户会看到自己的日程:其医生通过其账户检索([getDoctorByUserId])。[?->getId()]:nullsafe 运算符在对象为 [null] 时返回 [null],而不是引发错误;
- 医生下拉列表:[array_map] 将每位医生转换为 [OptionView];
- 日程表,根据用户的权限进行格式化和过滤([scheduleView],见下文);
- 预订窗口,仅当所请求的时间段对该用户而言可预订 时才显示:试图为已被预订的时间段生成 URL [&book=2] 的患者将什么也得不到。[array_find] (示例 06)返回数组中第一个满足条件的元素,或者 [null]。患者列表只提供给管理员和医生;患者只会收到自己的姓名;
- 视图接收其变量([render],示例 13),包括 [pageTitle] 和 [error],它们由模板读取。
11.19.3.3. POST /schedule/book
第 167–215 行:
- 防 CSRF 令牌,以及预订表单中的隐藏字段(医生、日期、时间段)。如果这些字段无效,那一定是手工构造的请求:[BadRequestHttpException],即“无效请求”页面(400);
- 对于患者,字段 [clientId] 会被忽略:患者始终为自己预约([Utils::connectedPatient])。依赖浏览器发送的字段,会让恶意患者可以代表他人进行预订。对于管理员和医生,必须已选择一名患者;否则,预订窗口会重新打开并显示一条消息;
- 时间段必须属于页面上所列的医生;
- 业务规则(不能是过去的时间、只能有一个即将到来的预约、时间段可用)由业务逻辑层验证。[BusinessException] 会变成一条闪现错误消息;其公共属性 [key] 和 [params] 提供该消息。同一个拒绝原因——“一个即将到来的预约”——对患者本人用第二人称表述(“您已经有……”)。任何其他异常都不会被拦截:这是真正的错误(500 页面);
- 在所有情况下都采用 Post/Redirect/Get 模式(示例 20):弹出消息并重定向到日程表。
11.19.3.4. POST /schedule/cancel
第 221–239 行:管理员或医生取消预约(规则 [^/schedule/cancel$] 源自 [security.yaml])。已不存在的预约(已被其他人取消,或由于双击)不算错误:只是一条消息。
11.19.3.5. 权限、已格式化的日程表和实用函数
- 第 247–255 行:用户在页面上被授权执行的操作,以关联数组表示:用户是否为管理员(ADMIN 或 DOCTOR)?是否为患者(以及是哪一位)?该患者是否可以预订(没有即将到来的预约)?
- 第 260–285 行:医生的日程,被转换为供视图使用的行。隐私方面的考虑在第 278 行:患者只能看到与自己的预约关联的姓名。对于其他预约,属性 [patient] 被设置为 [null],视图显示“Booked”。姓名并不是由视图隐藏的:它从未传递给视图,因此不会出现在页面源代码中,否则很容易读取到它。对于可用的时间段,如果所在日期尚未过去,则向管理员或可以预订的患者显示“Book”按钮;“Cancel”按钮只向管理员显示。命名参数 ([slotId: $slot->getId()])使得构造一个具有八个属性的对象的代码易于阅读;
- 第 291–296 行:POST 表单的隐藏字段。[[$doctorId, $day] = ...] (第 171 和 225 行)将渲染得到的数组分解为两个变量;
- 第 300–307 行:医生在某一天的日程的 URL。[generateUrl('schedule', [...])] 会将不属于路径参数的值作为查询参数添加到 URL 的末尾:[/schedule?doctorId=1&day=2026-09-26];
- 第 321–328 行:向患者解释为什么没有“Book”按钮的消息(他们已经有一个即将到来的预约),除非该预约就在所显示的日程表中(预订后立即显示时,该消息会被移走)。[array_any] ([PHP] 8.4):是否至少有一个元素满足条件?
11.19.4. src/Controller/PersonsController.php
| <?php
// =========================================================================
// src/Controller/PersonsController.php:医生的管理和
// 客户的管理(仅限 ADMIN)是相同的:相同的列表、相同的表单、
// 相同的规则。与其把相同的操作写两遍,不如把它们
// 在这个抽象类中只写一次;DoctorsController 和 ClientsController
// 继承自它,只指定使它们不同的内容:部分的名称
// (doctors 或 clients)、翻译键,以及要调用的
// ApplicationModel 的方法。
//
// 这些操作的 #[Route] 属性也会被继承:每个子类的 #[Route] 属性
// 为它们提供路径的开头(/doctors 或
// /clients)和名称的开头(doctors_ 或 clients_)。这样,我们对每一个都得到:
//
// GET /doctors 列表 doctors_list
// GET /doctors/add 空表单 doctors_add
// POST /doctors/add 创建 doctors_add
// GET /doctors/{id}/edit 预先填充的表单 doctors_edit
// POST /doctors/{id}/edit 修改 doctors_edit
// POST /doctors/{id}/delete 删除 doctors_delete
//
// (/clients 下的 URL 也是如此)。视图也是共用的:
// templates/persons/list.html.twig 和 persons/form.html.twig。
//
// 安全:config/packages/security.yaml 的 access_control 规则 ^/(doctors|clients)
// 将所有这些 URL 保留给 ADMIN - 包括以后
// 可能添加的 URL。
// =========================================================================
namespace App\Controller;
use App\Entity\Person;
use App\Form\PersonFieldsType;
use App\Form\PersonType;
use App\Business\PersonData;
use App\Business\BusinessException;
use App\Views\PersonKeys;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
abstract class PersonsController extends BaseController
{
// 每种“输入”业务错误(重复)所涉及的表单字段:
// 它们会用红框标出,消息则位于页面底部
public const BUSINESS_ERROR_FIELDS = [
'ERRORS.LOGIN_TAKEN' => ['login'],
'ERRORS.DOCTOR_ALREADY_EXISTS' => ['first_name', 'last_name'],
'ERRORS.PATIENT_ALREADY_EXISTS' => ['first_name', 'last_name'],
];
public function __construct(protected ApplicationModel $application, protected Flash $flash)
{
}
// —— 每种人员类型必须提供的内容
// "doctors" 或 "clients":路由名称的开头
abstract protected function section(): string;
abstract protected function keys(): PersonKeys;
/** @return list<Person> */
abstract protected function all(): array;
abstract protected function find(int $id): ?Person;
abstract protected function create(PersonData $data): Person;
abstract protected function update(int $id, PersonData $data): Person;
abstract protected function erase(int $id): void;
// -------------------------------------------------------------------
// GET /doctors(或 /clients)
// -------------------------------------------------------------------
#[Route('', name: 'list', methods: ['GET'])]
public function list(): Response
{
return $this->render('persons/list.html.twig', ['pageTitle' => $this->keys()->title,
'keys' => $this->keys(), 'section' => $this->section(), 'persons' => $this->all()]);
}
// -------------------------------------------------------------------
// GET /doctors/add:空表单;POST:创建
// -------------------------------------------------------------------
#[Route('/add', name: 'add', methods: ['GET', 'POST'])]
public function add(Request $request): Response
{
$form = $this->createForm(PersonType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->create(PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, null);
}
$this->flash->success($this->keys()->added, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, null);
}
// -------------------------------------------------------------------
// GET /doctors/{id}/edit:预先填充的表单;POST:修改。
// {id<\d+>}:由数字组成的参数(见示例 02):
// /doctors/abc/edit 不匹配任何路由(404 页面)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/edit', name: 'edit', methods: ['GET', 'POST'])]
public function edit(Request $request, int $id): Response
{
$person = $this->find($id) ?? throw $this->createNotFoundException();
// 表单,预先填充了该人员的值(
// 而密码则从不显示)
$form = $this->createForm(PersonType::class, [
'title' => $person->getTitle(), 'first_name' => $person->getFirstName(),
'last_name' => $person->getLastName(), 'login' => $person->getAccount()->getLogin(),
'version' => $person->getVersion(),
], ['creation' => false]);
$form->handleRequest($request);
if ($form->isSubmitted() && $form->isValid()) {
try {
$person = $this->update($id, PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->businessError($e, $form, $person);
}
$this->flash->success($this->keys()->edited, self::params($person));
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person);
}
// -------------------------------------------------------------------
// POST /doctors/{id}/delete
// (在发送表单之前会先询问“Are you sure?”确认,
// 见 public/js/app.js)
// -------------------------------------------------------------------
#[Route('/{id<\d+>}/delete', name: 'delete', methods: ['POST'])]
public function delete(Request $request, int $id): Response
{
$this->checkCsrf($request);
$person = $this->find($id);
try {
$this->erase($id);
$this->flash->success($this->keys()->deleted, self::params($person));
} catch (BusinessException $e) {
$this->flash->error($e->key, $e->params);
}
return $this->redirectToRoute($this->section().'_list');
}
// ———————————————————————————————— 内部函数
// $person 为 null:创建表单;否则:修改表单。
// 被拒绝的表单(输入无效,或违反业务规则):422 状态码
private function page(FormInterface $form, ?Person $person, ?Message $error = null,
array $invalidFields = []): Response
{
$keys = $this->keys();
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('persons/form.html.twig', [
'pageTitle' => $person === null ? $keys->add : $keys->edit,
'form' => $form,
'error' => $error,
'invalidFields' => $invalidFields,
'listUrl' => $this->generateUrl($this->section().'_list'),
], new Response(status: $refused ? 422 : 200));
}
// 业务规则拒绝了写入:表单会再次显示,带有
// 用户的输入(不含密码)、业务层的消息
// (位于页面底部),以及相关字段(如果有的话)用红框
// 标出,使用户立即看到需要更正什么
private function businessError(BusinessException $e, FormInterface $form, ?Person $person): Response
{
if (in_array($e->key, ['ERRORS.DOCTOR_NOT_FOUND', 'ERRORS.PATIENT_NOT_FOUND'], true)) {
// 在此期间被另一位 ADMIN 删除:返回列表
$this->flash->error($e->key, $e->params);
return $this->redirectToRoute($this->section().'_list');
}
return $this->page($form, $person, new Message($e->key, $e->params),
self::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// “added / updated / deleted”消息的 {name} 和 {login}
private static function params(?Person $person): array
{
return $person === null ? ['name' => '', 'login' => '']
: ['name' => "{$person->getFirstName()} {$person->getLastName()}",
'login' => $person->getAccount()->getLogin()];
}
}
|
医生和客户的管理是相同的:相同的列表、相同的表单、相同的规则。这些操作只在一个抽象类中编写一次;[DoctorsController] 和 [ClientsController] 继承自它。每个子类都必须提供使其与众不同的部分:这就是第 64–77 行中抽象方法的作用,它们声明时没有代码;未实现这些方法的子类会被 [PHP] 拒绝。这就是被称为“模板方法”的设计模式:父类定义算法,子类提供细节。
这些操作的 [#[Route]] 属性也是继承的。[Symfony] 会忽略抽象类,但会检查每个子类的方法,包括继承的方法;子类的 [#[Route]] 属性指定其路径和名称的开头:操作 [list] 变成路由 [doctors_list]([/doctors])和 [clients_list]([/clients])。要向医生管理或客户管理模块添加操作,只需在这里编写即可。
- 第 51–55 行:业务逻辑层每种输入错误所影响的字段:重复的登录名影响“login”字段;姓名匹配影响“名”和“姓”字段。这些字段将以红色突出显示;
- 第 57 行:构造函数,由子类继承。其属性为 [protected]:对子类可见;
- 第 82–87 行:列表。该视图为两个部分所共用:它接收该部分的翻译键([keys])及其名称([section]),后者用于生成路由名称(视图中的 [section ~ '_add'] );
- 第 92–107 行:添加。一个操作同时处理 GET(空表单,称谓 [Mr] 已选中)和 POST(创建),如示例 19 所示。无效的输入会重新加载表单。有效的输入会进入业务层,业务层可能拒绝写操作(例如重名、登录名已被使用);否则显示成功消息,并返回列表(PRG 模式);
- 第 114–136 行:更新,针对已存在的人员:[?? throw $this->createNotFoundException()] (404 页面;[throw] 是一个表达式,可以用在 [??] 的右侧)。[{id<\d+>}] (第 114 行)对参数 [{id}] 只接受数字(示例:02)。表单预先填充了该人员的值及其版本;[handleRequest] 在 POST 时用输入的数据替换它们;
- 第 143–155 行:删除。表单在浏览器中要求确认(示例 21)。删除之前会先检索该人员的信息,以生成成功消息(“Doctor Paul TATOU has been deleted.”);
- 第 161–173 行:表单,用于创建([$person] 等于 [null])或修改。被拒绝的表单(输入无效或违反业务规则)会以状态码 422 返回(示例 19)。视图接收表单本身([render] 会将其转换为“表单视图”,示例 18);
- 第 179–188 行:业务层拒绝了写操作。如果某人在此期间已被删除(被另一位管理员删除),则用户会被返回到列表。否则,表单会直接重新显示(不重定向),与输入错误的情况一样:它已经包含用户的输入。此外还会加上业务层的消息(显示在页面底部的错误区域)以及需要以红色突出显示的字段。请注意,实体管理器在异常之后已关闭(如上文所述的业务层):此时操作只负责显示;
- 第 191–196 行:成功消息的参数 [{name}] 和 [{login}] 。
11.19.5. src/Controller/DoctorsController.php 和 ClientsController.php
| <?php
// src/Controller/DoctorsController.php:医生的管理(仅限 ADMIN 角色)。
// 所有操作都由 PersonsController 编写:这里
// 只需说明要调用什么以及要显示哪些标签。
namespace App\Controller;
use App\Entity\Person;
use App\Business\PersonData;
use App\Views\PersonKeys;
use Symfony\Component\Routing\Attribute\Route;
// 从 PersonsController 继承的所有路由的路径和名称的开头
#[Route('/doctors', name: 'doctors_')]
class DoctorsController extends PersonsController
{
protected function section(): string
{
return 'doctors';
}
// DOCTORS.TITLE、DOCTORS.ADD...(见 translations)
protected function keys(): PersonKeys
{
return PersonKeys::of('DOCTORS');
}
protected function all(): array
{
return $this->application->getAllDoctors();
}
protected function find(int $id): ?Person
{
return $this->application->getDoctorById($id);
}
protected function create(PersonData $data): Person
{
return $this->application->addDoctor($data);
}
protected function update(int $id, PersonData $data): Person
{
return $this->application->editDoctor($id, $data);
}
protected function erase(int $id): void
{
$this->application->deleteDoctor($id);
}
}
|
这里剩下的只是指定要调用哪些方法([ApplicationModel] 的方法)以及要显示哪些标签(字典中的 [DOCTORS.xxx] 键),并提供起始路径和路由名称(第 14 行)。[ApplicationModel] 位于 [$this->application] 属性中,该属性由父类的构造函数声明。[ClientsController] 与此相同,只是使用客户方法和 [CLIENTS.xxx] 键。
11.19.6. src/Controller/RegistrationController.php
| <?php
// =========================================================================
// src/Controller/RegistrationController.php:“创建患者账户”:尚无账户的患者
// 自行创建。公开路由(根据定义,此时还
// 没有账户):
//
// POST /register/access 登录页面的“创建患者账户”按钮:检查
// 该页面的验证码,然后
// 打开表单
// GET /register 表单
// POST /register 创建,然后返回登录页面
//
// 该路径由一个验证码(登录
// 页面的验证码)防范机器人:
// 1. “创建患者账户”按钮将登录表单发送到
// /register/access;如果验证码抄写正确,服务器会签发一张
// 通行证(见 src/Security/RegistrationPass.php);
// 2. 没有有效通行证时,/register 会送回登录
// 页面(#[RegistrationPassRequired] 属性,见
// src/EventListener/CheckRegistrationPass.php);
// 3. 通行证在创建时被消耗:一个已解答的验证码只允许创建
// 一个账户;
// 4. 此外,每小时每个 IP 地址创建的账户数量受到限制
// (见 src/Security/AttemptLimiter.php)。
//
// 所创建的账户与 ADMIN 在“Patients”页面创建的账户完全相同
// (使用业务层的同一个方法:addClient),只是患者
// 自己选择登录名和密码(必填,并需确认)。
// =========================================================================
namespace App\Controller;
use App\Form\PersonFieldsType;
use App\Form\RegistrationType;
use App\Business\BusinessException;
use App\Security\CaptchaService;
use App\Security\AttemptLimiter;
use App\Security\RegistrationPass;
use App\Security\RegistrationPassRequired;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
#[Route('/register')]
class RegistrationController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private CaptchaService $captchas,
private AttemptLimiter $limiter,
private RegistrationPass $passes,
private Flash $flash,
) {
}
// -----------------------------------------------------------------------
// POST /register/access 字段:captchaId、captcha(登录
// 页面的字段;同时发送的登录名和密码会被忽略)
// -----------------------------------------------------------------------
#[Route('/access', name: 'registration_access', methods: ['POST'])]
public function access(Request $request): Response
{
$this->checkCsrf($request);
$ip = (string) $request->getClientIp();
// 最近从该地址创建的账户过多:无需再继续
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
$this->flash->error('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]);
return $this->redirectToRoute('login');
}
// 验证码缺失或错误:返回登录页面,显示
// 新图像(失败计为一次登录失败)
if (! $this->captchas->verify($request->request->getString('captchaId'),
$request->request->getString('captcha'))) {
$this->limiter->loginFailure($ip, '');
$this->flash->error('ERRORS.CAPTCHA_BEFORE_ACCOUNT');
return $this->redirectToRoute('login');
}
// 验证码正确:签发通行证并打开表单
$response = $this->redirectToRoute('registration');
$response->headers->setCookie($this->passes->issue());
return $response;
}
// -----------------------------------------------------------------------
// GET /register:表单;POST /register:创建。通行证
// 在调用操作之前已被检查(#[RegistrationPassRequired])。
// 表单会验证所有输入(字段和密码确认):
// 用户一次就能更正所有错误
// -----------------------------------------------------------------------
#[Route('', name: 'registration', methods: ['GET', 'POST'])]
#[RegistrationPassRequired]
public function register(Request $request): Response
{
$form = $this->createForm(RegistrationType::class, ['title' => 'Mr']);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
$ip = (string) $request->getClientIp();
// 1. 最近从该地址创建的账户过多?
$minutes = $this->limiter->registrationBlockMinutes($ip);
if ($minutes > 0) {
return $this->page($form, new Message('ERRORS.TOO_MANY_ACCOUNTS', ['minutes' => $minutes]));
}
// 2. 创建(客户 + USER 账户,在一个事务中)
$data = PersonFieldsType::data($form->getData());
try {
$this->application->addClient($data);
} catch (BusinessException $e) {
// 登录名或名 + 姓已被占用:通行证仍然有效
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// 3. 通行证已被使用:它不能再用于创建第 2 个账户
$this->passes->consume($request->cookies->get(RegistrationPass::COOKIE));
$this->limiter->registrationSuccess($ip);
// 4. 返回登录页面,登录名已预先填充
$this->flash->success('REGISTRATION.DONE', ['login' => $data->login]);
return RegistrationPass::clearCookie($this->redirectToRoute('login', ['login' => $data->login]));
}
// 表单;被拒绝的表单:422 状态码
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('registration.html.twig', ['pageTitle' => 'REGISTRATION.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
}
|
患者自行创建患者账户。该流程受验证码保护,与登录页面上使用的是同一个验证码。
- 第 65–91 行:登录页面上的“创建患者账户”按钮会将登录表单提交到此地址(后面是视图 [login])。如果最近从该地址(IP)创建了过多账户,就无需再继续。如果验证码缺失或不正确:返回登录页面,显示新图片和一条消息;该失败计为一次登录失败尝试(用户名为空)。如果验证码正确:令牌存储在 Cookie 中,并将用户重定向到表单;
- 第 99–107 行:表单。[#[RegistrationPassRequired]] 属性(第 100 行)会使令牌在调用操作之前由监听器 [CheckRegistrationPass] 进行验证。表单会验证所有输入,包括密码确认:用户一次就能看到所有错误;
- 第 108–132 行:创建。客户及其账户使用与管理员相同的业务层方法([addClient])创建;只有用户名和密码由患者选择。如果用户名或同名者已被占用:返回表单,而不消耗通行证。创建账户会消耗该令牌(一次通过验证码对应一个账户),计入每小时限额,并重定向到登录页面,同时预填用户名([redirectToRoute('login', ['login' => ...])] 会添加参数 [?login=...]),并附带一条成功消息。通行证 Cookie 会被清除。
11.19.7. src/Controller/PatientAreaController.php
| <?php
// =========================================================================
// src/Controller/PatientAreaController.php:患者(USER 角色)的个人页面,
// 即他们登录后立即看到的页面:
//
// GET /my-area 主页:[Manage my account]、[View a
// schedule],以及其即将到来的预约
// POST /my-area/cancel 取消其本人的预约
// GET /my-account 其账户的修改表单
// POST /my-account 修改
// POST /my-account/delete 删除账户(及其预约)
//
// 该控制器的黄金法则:相关的患者始终是令牌中的那一位
// ($this->utils->connectedPatient()),绝不是浏览器发送的
// 标识符。因此,患者即使自己构造请求,也既不能查看、
// 也不能修改或取消属于其他患者的内容。
//
// 任何账户的修改或删除都需要当前密码:
// 发现会话未关闭的人既不能更改
// 密码,也不能删除账户。当前密码的错误会
// 计为登录失败(适用相同的限制)。
//
// 安全:所有这些 URL 都保留给 USER 角色(config/packages/security.yaml
// 中的规则 ^/my-)。
// =========================================================================
namespace App\Controller;
use App\Entity\Client;
use App\Entity\Appointment;
use App\Form\PersonFieldsType;
use App\Form\MyAccountType;
use App\Business\BusinessException;
use App\Security\AuthService;
use App\Security\AttemptLimiter;
use App\Views\AppointmentView;
use App\Web\ApplicationModel;
use App\Web\BaseController;
use App\Web\Flash;
use App\Web\Message;
use App\Web\Utils;
use Symfony\Component\Form\FormError;
use Symfony\Component\Form\FormInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\Translation\TranslatorInterface;
class PatientAreaController extends BaseController
{
public function __construct(
private ApplicationModel $application,
private AuthService $auth,
private AttemptLimiter $limiter,
private Utils $utils,
private Flash $flash,
private TranslatorInterface $translator,
) {
}
// -----------------------------------------------------------------------
// GET /my-area
// -----------------------------------------------------------------------
#[Route('/my-area', name: 'area', methods: ['GET'])]
public function area(): Response
{
$patient = $this->utils->connectedPatient();
$appointments = array_map(fn (Appointment $a) => new AppointmentView(
$a->getId(),
$this->utils->formatDay($a->getDay()),
$a->getSlot()->time(),
$a->getSlot()->getDoctor()->label(),
// 指向医生当天日程的链接:患者在那里看到自己的姓名
$this->generateUrl('schedule', ['doctorId' => $a->getSlot()->getDoctor()->getId(),
'day' => Utils::iso($a->getDay())])),
$this->application->getClientUpcomingAppointments($patient->getId()));
return $this->render('area.html.twig', ['pageTitle' => 'AREA.TITLE',
'patient' => $patient->label(), 'appointments' => $appointments]);
}
// -----------------------------------------------------------------------
// POST /my-area/cancel 字段:appointmentId
// -----------------------------------------------------------------------
#[Route('/my-area/cancel', name: 'area_cancel', methods: ['POST'])]
public function cancelAppointment(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$appointmentId = Utils::positiveInteger($request->request->get('appointmentId'));
$appointment = $appointmentId !== null ? $this->application->getAppointmentById($appointmentId) : null;
// 不存在的预约和另一位患者的预约会得到
// 相同的答复:不会透露任何有关他人预约的信息
if ($appointment === null || $appointment->getClient()->getId() !== $patient->getId()) {
$this->flash->error('ERRORS.APPOINTMENT_NOT_FOUND');
} else {
$this->application->deleteAppointment($appointment);
$this->flash->success('SCHEDULE.CANCELLED');
}
return $this->redirectToRoute('area');
}
// -----------------------------------------------------------------------
// GET /my-account:表单,预先填充了患者的值;
// POST /my-account:修改
// -----------------------------------------------------------------------
#[Route('/my-account', name: 'account', methods: ['GET', 'POST'])]
public function account(Request $request): Response
{
$patient = $this->utils->connectedPatient();
$form = $this->createForm(MyAccountType::class, [
'title' => $patient->getTitle(), 'first_name' => $patient->getFirstName(), 'last_name' => $patient->getLastName(),
'login' => $patient->getAccount()->getLogin(), 'version' => $patient->getVersion(),
]);
$form->handleRequest($request);
if (! $form->isSubmitted() || ! $form->isValid()) {
return $this->page($form);
}
// 当前密码;错误时:消息显示在字段下方(添加到该字段的
// 错误,FormError),以及页面底部
$error = $this->checkCurrentPassword($request, $patient,
$form->get('current_password')->getData());
if ($error !== null) {
$form->get('current_password')->addError(
new FormError($this->translator->trans($error->key, $error->params)));
return $this->page($form, $error);
}
try {
$client = $this->application->editClient($patient->getId(),
PersonFieldsType::data($form->getData()));
} catch (BusinessException $e) {
return $this->page($form, new Message($e->key, $e->params),
PersonsController::BUSINESS_ERROR_FIELDS[$e->key] ?? []);
}
// 登录名和显示的姓名包含在令牌中:会签发一个新的令牌,
// 否则导航栏会保留旧的姓名
$this->flash->success('MY_ACCOUNT.UPDATED');
$response = $this->redirectToRoute('area');
$response->headers->setCookie($this->auth->tokenCookie($client->getAccount()));
return $response;
}
// -----------------------------------------------------------------------
// POST /my-account/delete 字段:current_password
// 账户、客户及其所有预约会一起消失,然后
// 患者被注销。
// -----------------------------------------------------------------------
#[Route('/my-account/delete', name: 'account_delete', methods: ['POST'])]
public function deleteAccount(Request $request): Response
{
$this->checkCsrf($request);
$patient = $this->utils->connectedPatient();
$error = $this->checkCurrentPassword($request, $patient,
$request->request->getString('current_password'));
if ($error !== null) {
$this->flash->error($error->key, $error->params);
return $this->redirectToRoute('account');
}
$this->application->deleteClient($patient->getId());
$this->flash->success('MY_ACCOUNT.DELETED');
return AuthService::clearCookie($this->redirectToRoute('login'));
}
// ———————————————————————————————— 内部函数
// 账户页面;被拒绝的表单:422 状态码
private function page(FormInterface $form, ?Message $error = null, array $invalidFields = []): Response
{
$refused = $error !== null || ($form->isSubmitted() && ! $form->isValid());
return $this->render('account.html.twig', ['pageTitle' => 'MY_ACCOUNT.TITLE',
'form' => $form, 'error' => $error, 'invalidFields' => $invalidFields],
new Response(status: $refused ? 422 : 200));
}
// 如果当前密码正确则为 null;否则为错误消息
private function checkCurrentPassword(Request $request, Client $patient, ?string $password): ?Message
{
$ip = (string) $request->getClientIp();
$login = $patient->getAccount()->getLogin();
$minutes = $this->limiter->loginBlockMinutes($ip, $login);
if ($minutes > 0) {
return new Message('ERRORS.TOO_MANY_ATTEMPTS', ['minutes' => $minutes]);
}
if (! $password || $this->auth->validate($login, $password) === null) {
$this->limiter->loginFailure($ip, $login);
return new Message('ERRORS.WRONG_CURRENT_PASSWORD');
}
return null;
}
}
|
患者的个人页面。黄金法则适用于该控制器:相关的患者始终是与令牌关联的那一位([Utils::connectedPatient]),绝不是浏览器发送的标识符。因此,患者即使自行构造请求,也无法查看、修改或取消属于其他患者的信息。
- 第 64–79 行:我的专区:患者的姓名及其即将到来的预约,已格式化([AppointmentView]),每个预约都带有指向该医生当天日程的链接;
- 第 84–100 行:取消自己的预约。不存在的预约和其他患者的预约会得到相同的响应:不会泄露任何有关其他患者预约的信息(甚至包括它们是否存在);
- 第 106–117 行:“管理我的账户”表单,预先填充了患者的信息,及其提交;
- 第 119–142 行:修改。任何修改都需要当前密码:发现会话未关闭的人将无法更改密码,也无法做其他任何事情。如果当前密码不正确,表单会重新显示,并在字段下方和页面底部显示消息。[addError(new FormError(...))] 向某个字段添加错误,就像验证检测到了它一样(示例 18);其消息是已经翻译好的文本,因此构建器接收了翻译器([TranslatorInterface],示例 22)。修改之后,会生成新的令牌:登录名和显示的姓名包含在令牌中,否则导航栏在下次登录之前会一直保留旧的姓名;
- 第 149–163 行:删除账户、客户及其所有预约,使用与管理员相同的业务逻辑方法。页面上的第二个表单是手工编写的(只有一个字段,即当前密码),并带有应用程序的防 CSRF 令牌。然后患者会被注销(令牌 Cookie 被清除);
- 第 177–190 行:验证当前密码。它同样受尝试次数限制器的约束,就像登录一样:否则,持有已打开会话的人可以通过“管理我的账户”表单尝试成千上万个密码,并发现正确的那个。
11.20. 视图
[Twig] 视图位于 [templates] 文件夹中:一个模板、片段、宏和页面。
11.20.1. 模板和片段
11.20.1.1. templates/layout.html.twig
| <!doctype html>
{# =========================================================================
templates/layout.html.twig
─────────────────────────────────────────────────────────────────────────
所有页面共用的布局(见示例 15):每个页面
(schedule.html.twig、login.html.twig...)扩展(EXTENDS)它({% extends %}),并填充其
[content] 块。
Twig 会转义它用 {{ ... }} 显示的所有内容(字符 < > & " '
会变成 < >...):例如,防止通过输入的
姓名进行 HTML 注入。若要按原样插入 HTML,必须
显式请求(raw 过滤器,见 fragments/captcha.html.twig)。
消息:成功消息显示在页面顶部,错误消息显示在底部,背景为浅
粉色(errors 片段)。
布局共享页面的变量:[pageTitle](页面标题的键,
由操作传递)。页面的语言就是请求的语言
(app.request.locale,见 src/EventListener/SetLanguage.php)。
========================================================================= #}
<html lang="{{ app.request.locale }}">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
{# pageTitle|trans:键的翻译;这里,键是一个变量 #}
<title>{{ pageTitle|trans }} - {{ 'APP.TITLE'|trans }}</title>
{# asset():public 文件夹中某个文件的 URL #}
<link rel="stylesheet" href="{{ asset('lib/bootstrap/css/bootstrap.min.css') }}">
<link rel="stylesheet" href="{{ asset('css/styles.css') }}">
</head>
<body>
<div class="container py-4">
{% include 'fragments/navbar.html.twig' %}
{% include 'fragments/success.html.twig' %}
<main>
{% block content %}{% endblock %}
</main>
{% include 'fragments/errors.html.twig' %}
</div>
{# “Are you sure?”对话框,在需要之前一直隐藏 #}
{% include 'fragments/confirmation.html.twig' %}
<script src="{{ asset('js/app.js') }}"></script>
</body>
</html>
|
所有页面共用的模板(示例 15):每个页面都扩展它([{% extends 'layout.html.twig' %}]),并填充其 [content] 块(第 36 行)。
- 第 21 行:页面的语言,[fr] 或 [en]:请求的语言,由监听器 [SetLanguage] 设置。[app] 是 [Symfony] 提供给所有视图的全局变量(示例 15);
- 第 26 行:页面标题,已翻译:[pageTitle|trans] 翻译变量 [pageTitle] 中包含的键,每个操作都会将该变量传给其视图;
- 第 28–29 行:函数 [asset] 返回 [public] 文件夹中某个文件的 URL(示例 15);
- 第 33–38 行:导航栏、页面顶部的成功消息、页面内容,以及页面底部的错误区域。这些片段通过 [{% include %}] (示例 15)插入:它们可以访问页面的变量;
- 第 41–42 行:“Are you sure?”窗口,在需要之前隐藏,以及显示它的脚本。
[Twig] 会对所有通过 [{{ ... }}] 显示的内容进行转义(示例 13):包含 HTML 的输入姓名([<script>])会按原样显示,而不会被解释。这可以保护所有页面免受轻易的 HTML 注入(XSS)。
11.20.1.2. templates/fragments/navbar.html.twig
| {# =========================================================================
templates/fragments/navbar.html.twig - 导航栏。
标题、FR/EN、角色、姓名、注销 - 以及一个菜单,其条目取决于
角色:“Doctors”和“Patients”只对 ADMIN 显示。这
只是显示上的便利:真正的保护是访问规则
(输入 /doctors 的 USER 会得到 403 页面)。患者(USER)
还有其“My area”菜单。
user():已登录的用户,或 null(见 src/Twig/ViewsExtension.php)。
当前页面的菜单会突出显示(“active”类):当
URL 的路径(app.request.pathInfo)以条目的某个
前缀开头([starts with])时即是如此。菜单的条目:一个数组列表 [路由
名称,标签的键,该条目处于活动状态的路径前缀]。
========================================================================= #}
{% set user = user() %}
{% set menu = [] %}
{% if user %}
{% if user.isPatient %}
{# 对 /my-area 和 /my-account 处于活动状态 #}
{% set menu = menu|merge([['area', 'APP.MENU_MY_AREA', ['/my-']]]) %}
{% endif %}
{% set menu = menu|merge([['schedule', 'APP.MENU_SCHEDULE', ['/schedule']]]) %}
{% if user.isAdmin %}
{% set menu = menu|merge([['doctors_list', 'APP.MENU_DOCTORS', ['/doctors']],
['clients_list', 'APP.MENU_PATIENTS', ['/clients']]]) %}
{% endif %}
{% endif %}
<nav class="navbar navbar-expand-sm navbar-dark bg-primary rounded mb-4 px-3">
<span class="navbar-brand mb-0">{{ 'APP.TITLE'|trans }}</span>
<ul class="navbar-nav me-auto">
{# entry[0]:路由的名称;过滤器保留匹配的前缀 #}
{% for entry in menu %}
{% set active = entry[2]|filter(p => app.request.pathInfo starts with p) is not empty %}
<li class="nav-item">
<a class="nav-link{{ active ? ' active' }}" href="{{ path(entry[0]) }}">{{ entry[1]|trans }}</a>
</li>
{% endfor %}
</ul>
<div class="d-flex align-items-center gap-2">
{# FR / EN:简单的链接(GET /language/fr),当前语言突出显示 #}
<div class="btn-group btn-group-sm" role="group" aria-label="FR / EN">
{% for code in ['fr', 'en'] %}
<a class="btn {{ app.request.locale == code ? 'btn-light' : 'btn-outline-light' }}"
href="{{ path('language', {code: code}) }}">{{ code|upper }}</a>
{% endfor %}
</div>
{% if user %}
<span class="badge text-bg-light text-primary">{{ user.role.value }}</span>
<span class="text-white">{{ user.name }}</span>
{# 注销是 POST:一个只剩按钮(以及防 CSRF 令牌)的表单 #}
<form method="post" action="{{ path('logout') }}" class="m-0">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-light">{{ 'APP.LOGOUT'|trans }}</button>
</form>
{% endif %}
</div>
</nav>
|
导航栏。菜单项取决于角色:患者是“My area”,管理员是“Doctors”和“Patients”。这只是一个便利功能:真正的保护来自规则 [access_control] (手动输入 [/doctors] 的患者将收到 403 页面)。
- 第 16 行:已登录的用户,或 [null],由我们扩展中的 [user()] 函数返回;
- 第 17–28 行:菜单由 [{% set %}] 指令生成,这些指令产生一个条目列表:路由名称、标签键,以及该条目处于活动状态的路径前缀。过滤器 [merge] 返回一个新列表,由第一个列表的元素后接第二个列表的元素组成(对于两个关联数组,它会合并它们的键)。[user.isPatient]:[Twig] 调用方法 [isPatient()]。条目“My area”对 [/my-area] 和 [/my-account](前缀 [/my-])处于活动状态。这处于“视图中不含逻辑”规则的边缘:不过,这段逻辑只影响显示,并且仅在这里使用;
- 第 34–39 行:对于每个条目,[active] 为 true,如果所请求 URL 的路径([app.request.pathInfo])以该条目的某个前缀开头([starts with])。过滤器 [filter] 只保留列表中满足条件的元素,条件写成箭头函数([p => ...]);
- 第 44–49 行:FR / EN 按钮,它们是简单的链接([/language/fr]),并突出显示当前语言;
- 第 51–59 行:对于已登录的用户,显示其角色([user.role.value]:枚举成员的字符串)、姓名和注销按钮。注销是一个 POST 请求:一个只剩按钮的表单,带有其防 CSRF 令牌([csrf_token('rdvmedecins')],示例 21)。
11.20.1.3. templates/fragments/success.html.twig
| {# =========================================================================
templates/fragments/success.html.twig - 上一个操作留下的成功消息
(预约已预订、医生已添加...),只显示
一次,位于页面顶部(见 src/Web/Flash.php)。而错误闪现
消息则由 errors 片段显示在页面底部。
app.flashes('success'):该类型的闪现消息(见示例 20)。每条
消息都是一个 Message 对象:message.key|trans(message.params) 是键
的文本,其中的 {name}、{login}... 被替换为它们的值。
========================================================================= #}
{% for message in app.flashes('success') %}
<div class="alert alert-success" role="status">{{ message.key|trans(message.params) }}</div>
{% endfor %}
|
由上一个操作设置的成功闪现消息([Flash::success])由 [app.flashes('success')] 从会话中读取并移除(示例 20)。每条都是一个 [Message] 对象,在此被翻译为页面的语言:[message.key|trans(message.params)]。[role="status"]:屏幕阅读器会朗读该消息。
11.20.1.4. templates/fragments/errors.html.twig
| {# =========================================================================
templates/fragments/errors.html.twig - 错误区域,位于每个
页面的底部,背景为浅粉色(类 .error-zone,见 public/css/styles.css)。
它汇集了三种可能的错误来源:
- [error]:所显示页面的错误(无效的日期、验证码抄写错误、
登录名已被占用...),由操作传入;
- 错误闪现消息,由上一个操作在重定向
之前留下(时间段已被预订、删除被拒绝...);
- 无效表单的输入错误(见示例 19):它们的
消息显示在字段下方;在这里,如果没有其他
消息,则显示一句简单的话“The form contains errors.”。
error ?? null:该变量并非在所有页面中都存在。
role="alert":屏幕阅读器会在页面显示时立即朗读该消息,
即使它位于底部。
========================================================================= #}
{% set messages = app.flashes('errors') %}
{% if error ?? null %}
{% set messages = [error]|merge(messages) %}
{% endif %}
{% if messages is empty and form is defined and form.vars.submitted and not form.vars.valid %}
{% set messages = [{key: 'ERRORS.INVALID_FORM', params: []}] %}
{% endif %}
{% if messages is not empty %}
<div class="error-zone" role="alert">
{% for message in messages %}
<div>{{ message.key|trans(message.params) }}</div>
{% endfor %}
</div>
{% endif %}
|
错误区域,位于每个页面的底部,背景为浅粉色。它综合了三种可能的错误来源:
- 闪现错误消息,由上一个操作生成(时间段已被预订、会话过期等);
- 所显示页面上的错误([error]),由操作传入:无效的日期、拼写错误的验证码、已被使用的用户名等;放在列表顶部。[error ?? null]:并非所有页面上都存在这个变量;运算符 [??] 不会对不存在的变量报错——而是用 [null] 替换它;
- 无效表单中的输入错误(示例 19):其消息显示在字段下方;在这里,如果没有其他消息,就显示一个简单的短语:“The form contains errors.”对于较长的表单,这可以让用户知道需要向上滚动。[form.vars]:表单视图的属性,包括 [submitted] (是否已提交?)和 [valid] (是否有效?)。该消息写成关联数组,其键与 [Message] 的属性相同:对于 [Twig],[message.key] 既指数组的键,也指对象的属性。
[role="alert"]:屏幕阅读器会在页面显示时立即朗读该消息,即使它位于底部。当页面很长时,该区域固定在窗口底部(见下文的样式表)。
11.20.1.5. templates/fragments/confirmation.html.twig
| {# =========================================================================
templates/fragments/confirmation.html.twig - 模态对话框
“Are you sure?”(见示例 21)。
它取代了浏览器的 window.confirm() 对话框,后者既无法设置样式,
也无法翻译(其按钮保持浏览器的语言,而不是
页面的语言)。
整个页面只有一个对话框,起初是隐藏的(d-none)。它的标签
在这里由服务器翻译,与页面的其余部分一样;小脚本
public/js/app.js 只是显示它,把表单特有的消息
(data-confirmation 属性)放进去,并在
用户确认时发送表单。
========================================================================= #}
<div id="confirmation-modal" class="d-none">
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true"
aria-labelledby="confirmation-modal-title" aria-describedby="confirmation-modal-message">
<div class="modal-dialog modal-dialog-centered">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="confirmation-modal-title">{{ 'CONFIRMATION.TITLE'|trans }}</h5>
<button type="button" class="btn-close" data-action="no" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></button>
</div>
<div class="modal-body">
<p class="mb-0" id="confirmation-modal-message"></p>
</div>
<div class="modal-footer">
{# “No, go back”而不是“Cancel”:这个问题有时是
“Cancel this appointment?”,在那里“Cancel”按钮会有歧义 #}
<button type="button" class="btn btn-secondary" data-action="no">{{ 'CONFIRMATION.NO'|trans }}</button>
<button type="button" class="btn btn-danger" data-action="yes">{{ 'CONFIRMATION.YES'|trans }}</button>
</div>
</div>
</div>
</div>
</div>
|
示例 21 中的“Are you sure?”模态窗口,它取代了浏览器的 [window.confirm()] 对话框:该对话框格式显示不佳,并且其按钮使用浏览器的语言,而不是页面的语言。整个页面只有一个窗口,初始状态为隐藏(类 [d-none] 来自 [Bootstrap]);其标签由服务器翻译,与页面的其余部分一样。脚本 [public/js/app.js] 会显示它,将待确认表单中的消息(其 [data-confirmation] 属性)放入其中,并在用户确认时提交表单。“拒绝”按钮标为“No, go back”而不是“Cancel”:问题有时是“Cancel this appointment?”,在这种语境下,“Cancel”按钮会有歧义。
11.20.1.6. templates/fragments/booking.html.twig
| {# =========================================================================
templates/fragments/booking.html.twig - 日程的
预订对话框。
模态对话框的真实 Bootstrap 类(.modal、.modal-backdrop...),
通过“硬编码”(show d-block)使其可见,而不是通过 Bootstrap 的
JavaScript。由服务器决定是否显示它(URL 的参数 &book=...
),而关闭它相当于跟随一个指向同一页面但不带此
参数的链接。
该片段直接读取包含它的页面的变量
(booking、doctorId、day、backUrl)。
========================================================================= #}
<div class="modal-backdrop fade show"></div>
<div class="modal fade show d-block" tabindex="-1" role="dialog" aria-modal="true" aria-labelledby="booking-title">
<div class="modal-dialog modal-dialog-centered">
<form method="post" action="{{ path('schedule_book') }}" class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="booking-title">{{ 'BOOKING_DIALOG.TITLE'|trans }}</h5>
<a class="btn-close" href="{{ backUrl }}" aria-label="{{ 'BOOKING_DIALOG.CLOSE_ARIA'|trans }}"></a>
</div>
<div class="modal-body">
<p>{{ 'BOOKING_DIALOG.SLOT'|trans({time: booking.time}) }}</p>
{# 除了所选患者之外,服务器还必须知道的内容 #}
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<input type="hidden" name="slotId" value="{{ booking.slotId }}">
{# 患者为自己预订:没有可供选择的列表(并且
服务器无论如何都会忽略可能存在的 clientId) #}
{% if booking.patient %}
<p class="mb-0">
<span>{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</span>:
<strong>{{ booking.patient }}</strong>
</p>
{% else %}
<label class="form-label" for="clientId">{{ 'BOOKING_DIALOG.PATIENT_LABEL'|trans }}</label>
<select id="clientId" name="clientId" class="form-select" required autofocus>
<option value="">{{ 'BOOKING_DIALOG.CHOOSE_PATIENT'|trans }}</option>
{% for client in booking.clients %}
<option value="{{ client.id }}">{{ client.label }}</option>
{% endfor %}
</select>
{% endif %}
</div>
<div class="modal-footer">
<a class="btn btn-secondary" href="{{ backUrl }}">{{ 'BOOKING_DIALOG.CANCEL'|trans }}</a>
<button type="submit" class="btn btn-primary">{{ 'BOOKING_DIALOG.CONFIRM'|trans }}</button>
</div>
</form>
</div>
</div>
|
日程预订窗口。它使用了 [Bootstrap] 模态窗口的实际类([modal]、[modal-backdrop]……),但通过“硬编码”使其可见([show d-block]),而不是通过 [Bootstrap] 的 [JavaScript]:当 URL 包含 [&book=...] 时,是服务器决定显示它。关闭它(使用 X 或 Cancel 按钮)等同于跟随一个指向同一页面但不带该参数的链接([backUrl])。
- 第 27–30 行:防 CSRF 令牌,以及服务器需要知道的内容:医生、日期和时间段;
- 第 34–47 行:患者直接输入自己的姓名,而无需从列表中选择(服务器无论如何都会忽略任何 [clientId] 字段)。管理员和医生从列表中选择患者;[required] 和 [autofocus]:浏览器要求必须选择,并将光标置于列表中。
11.20.1.7. templates/fragments/captcha.html.twig
| {# =========================================================================
templates/fragments/captcha.html.twig - 登录
页面的验证码(见 src/Security/CaptchaService.php)。它既保护
登录,也保护创建账户的访问(“Create a patient
account”按钮)。它读取页面的 [captcha] 变量。
captcha.svg|raw:SVG 图像按原样插入页面,不
转义。这里是无害的,因为该 SVG 由服务器
自己构建,不包含任何来自用户的内容 - 对于用户输入,我们绝不会
这样做。
隐藏字段 captchaId 告诉服务器要检查哪个验证码;正确
答案本身绝不会发送到浏览器。“Another image”只是重新加载
页面(path('login'):页面的 URL,不带其参数)。
========================================================================= #}
<div class="mb-3">
<label class="form-label" for="captcha">{{ 'CAPTCHA.LABEL'|trans }}</label>
<div class="d-flex align-items-center gap-3 mb-2">
<div class="captcha-image" role="img" aria-label="{{ 'CAPTCHA.IMAGE_ALT'|trans }}">{{ captcha.svg|raw }}</div>
<a class="small" href="{{ path('login') }}">{{ 'CAPTCHA.NEW_IMAGE'|trans }}</a>
</div>
<input type="hidden" name="captchaId" value="{{ captcha.id }}">
<input id="captcha" name="captcha" type="text" maxlength="10" autocomplete="off" autocapitalize="off"
spellcheck="false" required class="form-control">
<div class="form-text">{{ 'CAPTCHA.HELP'|trans }}</div>
</div>
|
验证码(示例 27)。[captcha.svg|raw] 将 SVG 图像按原样插入,不对其进行转义:否则,浏览器会显示其 XML 代码。这在这里是安全的,因为该 SVG 由服务器生成,不包含任何由用户提供的内容:对于用户输入,我们绝不会这样做。隐藏字段 [captchaId] 告诉服务器要验证哪个验证码;答案本身绝不会发送到浏览器。“Another image”链接会重新加载登录页面,从而重新生成验证码。
11.20.2. 宏:templates/macros.html.twig
| {# =========================================================================
templates/macros.html.twig - 表单的宏(见示例 15)。
field(field, invalidFields):Form 组件表单的一个字段,
带有其标签、错误消息或帮助(form_row,由
Bootstrap 5 主题绘制,见示例 18)。如果该字段有输入错误(主题会处理),或者某个业务
错误指向它,它就会被红框标出(类
is-invalid):其名称在操作传入的 [invalidFields] 列表中
(登录名已被占用...),消息位于页面底部。
字段的属性(maxlength...)是补充的,而不是替换的:merge。
========================================================================= #}
{% macro field(field, invalidFields = []) %}
{% set attr = field.vars.attr %}
{% if field.vars.name in invalidFields %}
{% set attr = attr|merge({class: (attr.class|default('') ~ ' is-invalid')|trim}) %}
{% endif %}
{{ form_row(field, {attr: attr}) }}
{% endmacro %}
{# 身份字段(称谓、名、姓),三个表单共用:
ADMIN 的医生/客户、“Create a patient account”和“Manage my account” #}
{% macro identity(form, invalidFields = []) %}
{# import _self:此文件自身的宏,用于调用 field 宏 #}
{% import _self as m %}
{{ m.field(form.title, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.first_name, invalidFields) }}</div>
<div class="col-sm-6">{{ m.field(form.last_name, invalidFields) }}</div>
</div>
{% endmacro %}
|
两个宏(示例 15),供三个显示“人员”表单的页面使用。
- 第 12–18 行:Form 组件表单中的一个字段,由 [form_row] 生成(示例 18):其标签、输入字段、错误消息或提示,以及 [Bootstrap] 5 主题中的类,该主题在 [config/packages/twig.yaml] 中声明。该主题会将有输入错误的字段以红色突出显示(类 [is-invalid])。对于由业务层的错误所标识的字段,宏也会为其添加该类:列表 [invalidFields] 由操作传入([PersonsController::BUSINESS_ERROR_FIELDS])。已被占用的用户名不是输入错误(它的格式是正确的),但用户需要看到应该更正哪个字段。[field.vars]:字段视图的属性,包括其名称([name])及其 HTML 属性([attr]);这些属性是追加的([merge]),而不是替换:字段保留其 [maxlength]。[form_row] 的第二个参数会替换字段视图的属性;
- 第 22–30 行:身份字段,三个表单通用:称谓,后面是并排的名和姓(来自 [Bootstrap] 的网格:[row]、[col-sm-6])。宏看不到其文件中的其他宏:[{% import _self as m %}] (第 24 行)导入它们。
11.20.3. 页面
11.20.3.1. templates/login.html.twig
| {# =========================================================================
templates/login.html.twig - 登录表单(见 AuthController)。
一个普通的手写 HTML <form>:浏览器自己在 POST /login 中发送登录名、
密码和验证码答案,无需 JavaScript。失败时,
服务器会送回此页面,其中已填入输入的登录名、一个新的
验证码,以及由布局显示在页面底部的错误。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-sm-8 col-md-6 col-lg-5">
<div class="card p-4">
<h5 class="card-title mb-3">{{ 'LOGIN.TITLE'|trans }}</h5>
<form method="post" action="{{ path('login_submit') }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="mb-3">
<label class="form-label" for="login">{{ 'LOGIN.LOGIN_LABEL'|trans }}</label>
{# autofocus:布尔属性,条件为 true 时写出,否则省略。
光标会进入第一个要填写的字段 #}
<input id="login" name="login" type="text" class="form-control" autocomplete="username"
value="{{ login }}" required{{ login == '' ? ' autofocus' }}>
</div>
<div class="mb-3">
<label class="form-label" for="password">{{ 'LOGIN.PASSWORD_LABEL'|trans }}</label>
<input id="password" name="password" type="password" class="form-control"
autocomplete="current-password" required{{ login != '' ? ' autofocus' }}>
</div>
{% include 'fragments/captcha.html.twig' %}
<button type="submit" class="btn btn-primary w-100">{{ 'LOGIN.SUBMIT'|trans }}</button>
{# 还没有账户:患者可以自己创建。它不是
简单的链接:它是此表单的第二个提交按钮,
前往另一个地址(formaction)。服务器在那里先检查上面的
验证码,然后才打开账户创建页面(见
RegistrationController)。formnovalidate:浏览器不要求
填写登录名和密码(创建账户时用不到)。在
字段中按 Enter 总是触发表单的第一个按钮“Log in”。 #}
<button type="submit" class="btn btn-outline-primary w-100 mt-3"
formaction="{{ path('registration_access') }}" formnovalidate>{{ 'LOGIN.CREATE_ACCOUNT'|trans }}</button>
<div class="form-text text-center">{{ 'LOGIN.CREATE_ACCOUNT_HELP'|trans }}</div>
</form>
<div class="text-muted small mt-3">
<span>{{ 'LOGIN.DEMO_ACCOUNTS'|trans }}</span>
<ul class="mb-0 mt-1">
<li><code>admin</code> - <span>{{ 'LOGIN.DEMO_ADMIN'|trans }}</span></li>
<li><code>pelissier</code>, <code>tatou</code>, <code>dupont</code> - <span>{{ 'LOGIN.DEMO_DOCTOR'|trans }}</span></li>
<li><code>martin</code>, <code>durand</code>, <code>bistrou</code>, <code>german</code> - <span>{{ 'LOGIN.DEMO_USER'|trans }}</span></li>
</ul>
</div>
</div>
</div>
</div>
{% endblock %}
|
登录表单是手工编写的 [<form>],通过 POST 发送到 [/login] (路径 [login_submit])。
- 第 22–28 行:登录尝试失败后,会重新显示所输入的用户名([login])。属性 [autofocus] 将光标置于第一个需要填写的字段:用户名为空时是用户名,否则是密码(在尝试失败之后或创建账户之后)。[{{ login == '' ? ' autofocus' }}]:没有“else”的三元运算符在条件为 false 时返回空字符串;
- 第 31 行:验证码;
- 第 42–43 行:“创建患者账户”按钮不是链接;它是第二个按钮,将同一个表单提交到另一个地址(按钮属性 [formaction])。服务器会先在那里验证验证码,然后才打开账户创建页面([RegistrationController::access])。[formnovalidate]:浏览器不要求填写用户名和密码(属性 [required]),因为创建账户并不需要它们。在字段中按 Enter 键总是会触发第一个表单提交按钮:登录。
11.20.3.2. templates/schedule.html.twig
| {# =========================================================================
templates/schedule.html.twig - 主页面(见 ScheduleController)。
三个块:
1. 选择医生和日期;
2. 日程;
3. 预订对话框(booking 片段)。
可能出现的错误(无效的日期、未知的医生)由布局显示在
页面底部(errors 片段)。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
{# 1. 选择医生和日期:一个 GET 表单,它只是用 URL 中的 ?doctorId=...&day=...
重新加载此页面 #}
<form method="get" action="{{ path('schedule') }}" class="card p-3 mb-3">
<div class="row g-2 align-items-end">
<div class="col-sm-5">
<label class="form-label" for="doctorId">{{ 'DOCTOR_DAY_PICKER.DOCTOR_LABEL'|trans }}</label>
<select id="doctorId" name="doctorId" class="form-select" required>
<option value="">{{ 'DOCTOR_DAY_PICKER.CHOOSE_DOCTOR'|trans }}</option>
{% for doctor in doctors %}
<option value="{{ doctor.id }}"{{ doctor.selected ? ' selected' }}>{{ doctor.label }}</option>
{% endfor %}
</select>
</div>
<div class="col-sm-4">
<label class="form-label" for="day">{{ 'DOCTOR_DAY_PICKER.DAY_LABEL'|trans }}</label>
<input id="day" name="day" type="date" class="form-control" value="{{ day }}" required>
</div>
<div class="col-sm-3">
<button type="submit" class="btn btn-primary w-100">{{ 'DOCTOR_DAY_PICKER.VIEW_SCHEDULE'|trans }}</button>
</div>
</div>
</form>
{# 已经有即将到来的预约的患者:说明为什么没有“Book”按钮 #}
{% if info %}
<div class="alert alert-info">
<span>{{ info|trans }}</span>
<a href="{{ path('area') }}" class="alert-link">{{ 'APP.MENU_MY_AREA'|trans }}</a>
</div>
{% endif %}
{# 2. 日程 #}
{% if schedule %}
<div class="card p-3">
<h5>{{ 'SCHEDULE.TITLE_PREFIX'|trans }} {{ schedule.day }} - {{ schedule.doctor }}</h5>
{% if schedule.rows is not empty %}
<table class="table table-hover align-middle">
<thead>
<tr>
<th>{{ 'SCHEDULE.COLUMN_SLOT'|trans }}</th>
<th>{{ 'SCHEDULE.COLUMN_STATUS'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{% for row in schedule.rows %}
<tr{{ row.bookable ? ' class="free-slot"' }}>
<td>{{ row.time }}</td>
<td>
{# [patient] 仅在用户有权查看该姓名时才会设置
(ADMIN、DOCTOR,或患者查看其本人的预约)- 否则
只显示“Booked” #}
{% if row.free %}
<span class="badge text-bg-success">{{ 'SCHEDULE.FREE'|trans }}</span>
{% elseif row.patient %}
<span class="badge {{ row.mine ? 'text-bg-primary' : 'text-bg-secondary' }}">{{ row.patient }}</span>
{% else %}
<span class="badge text-bg-secondary">{{ 'SCHEDULE.BOOKED_BY_OTHER'|trans }}</span>
{% endif %}
</td>
<td>
{# 所显示的按钮由控制器根据用户的角色决定(bookable、
appointmentId)。“Book”是一个简单的
链接:它会重新打开此页面,并显示该时间段的预订对话框 #}
{% if row.bookable %}
<a class="btn btn-sm btn-outline-success" href="{{ row.bookUrl }}">{{ 'SCHEDULE.BOOK'|trans }}</a>
{% endif %}
{# “Cancel”会修改数据:因此它是一个 POST #}
{% if row.appointmentId %}
<form method="post" action="{{ path('schedule_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ row.appointmentId }}">
<input type="hidden" name="doctorId" value="{{ doctorId }}">
<input type="hidden" name="day" value="{{ day }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'SCHEDULE.CANCEL_APPOINTMENT'|trans }}</button>
</form>
{% endif %}
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ 'SCHEDULE.NO_SLOTS'|trans }}</p>
{% endif %}
</div>
{% else %}
<p class="text-muted">{{ 'SCHEDULE.EMPTY_STATE'|trans }}</p>
{% endif %}
{# 3. 预订对话框,仅当 URL 包含 &book=... 时 #}
{% if booking %}
{% include 'fragments/booking.html.twig' %}
{% endif %}
{% endblock %}
|
主页面。三个部分:选择医生和日期、日程表以及预订窗口。
- 第 15–34 行:选择医生和日期:一个 GET 表单(示例 17),它会重新加载页面,URL 中带有 [?doctorId=...&day=...] 。日期是一个 [type="date"] 字段:浏览器显示日历,并以 [yyyy-mm-dd] 格式发送日期,而不管它如何显示(法语中显示为 [26/09/2026] );
- 第 37–42 行:对于已经有即将到来的预约的患者,说明为什么没有“Book”按钮;
- 第 66–72 行:时间段状态:空闲(绿色)、患者姓名(已登录患者的预约为蓝色,其他为灰色),或“Booked”。视图不做任何决定:[row.patient] 仅在用户有权查看该姓名时才会填充;
- 第 78–80 行:“Book”是一个简单的链接:它会重新打开页面,并显示该时间段的预订窗口([row.bookUrl])。它不修改任何内容:GET 就足够了;
- 第 82–91 行:“Cancel”会修改数据:它是一个 POST 表单(示例 21),带有防 CSRF 令牌、要取消的预约,以及用于返回同一页面的信息(医生、日期)。[data-confirmation] 属性会使页面的脚本请求确认;
- 第 106–108 行:预订窗口,如果 URL 要求显示(并且该时间段可供预订)。
11.20.3.3. templates/persons/list.html.twig
| {# =========================================================================
templates/persons/list.html.twig - 医生或客户的列表
(ADMIN)。两者共用一个视图:每种类型特有的标签的键
通过 [keys] 传入,[section]("doctors" 或 "clients")给出
路由名称的开头(见 PersonsController):section ~ '_add' -> "doctors_add"。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="d-flex justify-content-between align-items-center mb-3">
<h4 class="mb-0">{{ keys.title|trans }}</h4>
<a class="btn btn-primary" href="{{ path(section ~ '_add') }}">{{ keys.add|trans }}</a>
</div>
<div class="card p-3">
{% if persons is not empty %}
<table class="table table-hover align-middle mb-0">
<thead>
<tr>
<th>{{ 'PERSONS.COLUMN_TITLE'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_FIRSTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LASTNAME'|trans }}</th>
<th>{{ 'PERSONS.COLUMN_LOGIN'|trans }}</th>
<th></th>
</tr>
</thead>
<tbody>
{# person.title:Twig 调用 getter getTitle()(见示例 13) #}
{% for person in persons %}
<tr>
<td>{{ person.title }}</td>
<td>{{ person.firstName }}</td>
<td>{{ person.lastName }}</td>
<td><code>{{ person.account.login }}</code></td>
<td class="text-end">
<div class="d-inline-flex gap-2">
<a class="btn btn-sm btn-outline-primary"
href="{{ path(section ~ '_edit', {id: person.id}) }}">{{ 'PERSONS.EDIT'|trans }}</a>
{# data-confirmation:在发送表单之前,会打开一个确认对话框
(见 public/js/app.js) #}
<form method="post" action="{{ path(section ~ '_delete', {id: person.id}) }}" class="m-0"
data-confirmation="{{ keys.confirmDelete|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<button type="submit" class="btn btn-sm btn-outline-danger">{{ 'PERSONS.DELETE'|trans }}</button>
</form>
</div>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p class="text-muted mb-0">{{ keys.empty|trans }}</p>
{% endif %}
</div>
{% endblock %}
|
医生或客户的列表:每一种所特有的标签都是翻译键([keys]),路由名称由部分名称生成([path(section ~ '_edit', {id: person.id})]:运算符 [~] 用于连接,得到 [doctors_edit] 或 [clients_edit])。[person.account.login]:账户登录名,随列表一起填充(DAO 层)。Delete 按钮是一个 POST 表单,需要确认。
| {# =========================================================================
templates/persons/form.html.twig - 创建或修改
医生或客户(ADMIN),使用 PersonType 表单。
当输入被拒绝时(空字段、登录名已被占用...),操作会
再次显示此页面,并且视图会显示:
- 已经输入的值(密码除外);
- 用红框标出的有问题的字段(Bootstrap 类 "is-invalid");
- 在被验证拒绝的字段下方,显示其消息;
- 页面的错误消息,位于页面底部(errors 片段)。
form_start 写出 <form> 标签(POST 方法,页面的 URL);form_end 写出
表单的结尾,以及尚未写出的字段:
防 CSRF 令牌,以及修改时的隐藏版本字段(乐观锁)。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-3">{{ pageTitle|trans }}</h5>
{{ form_start(form) }}
{# form_errors:表单本身的错误(防 CSRF 令牌错误) #}
{{ form_errors(form) }}
{# 称谓、名、姓:三个表单共用的宏 #}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# 从不预先填充:密码绝不会回到浏览器 #}
{{ m.field(form.password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ listUrl }}">{{ 'PERSONS.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
使用 [PersonType] 表单创建或编辑医生或客户。
- 第 16 行:以名称 [m] 导入宏;
- 第 24 行:[form_start] 写出标签 [<form>]:方法 POST、页面的 URL,以及属性 [novalidate] (类型选项 [attr]);
- 第 26 行:[form_errors(form)] 显示表单本身的、与任何特定字段无关的错误:无效的防 CSRF 令牌(“The page has expired...”);
- 第 28 行:称谓、名和姓,通过 [identity] 宏;
- 第 31–33 行:用户名和密码,它们从不预先填充。它们的提示在创建和修改时不同(类型选项);
- 第 39 行:[form_end] 在写出尚未写出的字段之后关闭表单:防 CSRF 令牌,以及编辑时的隐藏版本字段(乐观锁)。
11.20.3.5. templates/registration.html.twig
| {# =========================================================================
templates/registration.html.twig - “Create a patient account”(公开页面,见
RegistrationController),使用 RegistrationType 表单。身份
字段与 ADMIN 的表单相同(identity 宏),但登录名和
密码是必填的,并需确认。这里没有验证码:只有
在抄写了登录
页面的验证码(“Create a patient account”按钮)之后,才能进入此页面。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4">
<h5 class="card-title mb-1">{{ 'REGISTRATION.TITLE'|trans }}</h5>
<p class="text-muted small mb-3">{{ 'REGISTRATION.INTRO'|trans }}</p>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
{# 重复字段:它的两个输入,并排放置(first、second) #}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
<div class="d-flex gap-2 mt-3">
<button type="submit" class="btn btn-primary">{{ 'REGISTRATION.SUBMIT'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('login') }}">{{ 'REGISTRATION.BACK_TO_LOGIN'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
</div>
</div>
{% endblock %}
|
创建患者账户:身份字段,后面是用户名、密码和密码确认,它们都是必填的。重复字段中的两个字段是 [form.password.first] 和 [form.password.second] (第 27–28 行),并排放置。密码帮助文本指明了最小长度:“At least 6 characters.”这里没有验证码:只有在登录页面输入验证码之后,才能进入此页面。
11.20.3.6. templates/area.html.twig
| {# =========================================================================
templates/area.html.twig - “My area”:患者(USER
角色)的主页,在其登录后立即显示。
- 两个选项:[Manage my account] 和 [View a schedule];
- 其即将到来的预约(如果有的话),以及取消它的方式。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<h4 class="mb-3">{{ 'AREA.HELLO'|trans({name: patient}) }}</h4>
<div class="row g-3 mb-4">
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('account') }}">
<h5 class="mb-1">{{ 'AREA.MANAGE_ACCOUNT'|trans }}</h5>
<span class="text-muted">{{ 'AREA.MANAGE_ACCOUNT_HELP'|trans }}</span>
</a>
</div>
<div class="col-sm-6">
<a class="card p-4 h-100 text-decoration-none option-card" href="{{ path('schedule') }}">
<h5 class="mb-1">{{ 'AREA.VIEW_SCHEDULE'|trans }}</h5>
<span class="text-muted">{{ 'AREA.VIEW_SCHEDULE_HELP'|trans }}</span>
</a>
</div>
</div>
<div class="card p-3">
<h5>{{ 'AREA.MY_APPOINTMENT'|trans }}</h5>
{# 通常只有一个(规则“一次只能有一个即将到来的预约”),但
页面可以显示多个。{% for %} ... {% else %}:一个循环,以及
列表为空时显示的内容;loop.last:是否为最后一个元素? #}
{% for appointment in appointments %}
<div class="d-flex flex-wrap justify-content-between align-items-center gap-2 py-2{{ not loop.last ? ' border-bottom' }}">
<div>
<div class="fw-semibold">{{ appointment.day }}, {{ appointment.time }}</div>
<div class="text-muted">
<span>{{ appointment.doctor }}</span> -
<a href="{{ appointment.scheduleUrl }}">{{ 'AREA.SEE_IN_SCHEDULE'|trans }}</a>
</div>
</div>
<form method="post" action="{{ path('area_cancel') }}" class="m-0"
data-confirmation="{{ 'SCHEDULE.CANCEL_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<input type="hidden" name="appointmentId" value="{{ appointment.id }}">
<button type="submit" class="btn btn-outline-danger">{{ 'AREA.CANCEL_APPOINTMENT'|trans }}</button>
</form>
</div>
{% else %}
<p class="text-muted mb-0">{{ 'AREA.NO_APPOINTMENT'|trans }}</p>
{% endfor %}
</div>
{% endblock %}
|
“My area”,患者的主页:两张大卡片(“Manage my account”、“View a schedule”),以及其即将到来的预约。
- 第 32–50 行:[{% for %}] …… [{% else %}] (示例 14)是一个循环,后面是列表为空时要显示的内容。通常,患者最多有一个即将到来的预约;不过,该页面能够显示多个预约。[loop.last] (示例 14):最后一项没有分隔符;
- 每个预约都有一个取消表单(POST,需要确认),它只发送其 ID:服务器将验证它是否属于已登录的患者。
11.20.3.7. templates/account.html.twig
| {# =========================================================================
templates/account.html.twig - “Manage my account”(USER 角色)。
同一页面上的两个独立表单:
1. 修改(身份、登录名、可选的新密码),使用
MyAccountType 表单;
2. 删除账户 - 同时也会取消其预约:一个
手写的表单。
两者都需要当前密码(current_password 字段)。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% import 'macros.html.twig' as m %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
{# 1. 修改 #}
<div class="card p-4 mb-4">
<h5 class="card-title mb-3">{{ 'MY_ACCOUNT.TITLE'|trans }}</h5>
{{ form_start(form) }}
{{ form_errors(form) }}
{{ m.identity(form, invalidFields) }}
<h6 class="mt-4 text-muted">{{ 'PERSONS.ACCOUNT_SECTION'|trans }}</h6>
{{ m.field(form.login, invalidFields) }}
<div class="row g-3">
<div class="col-sm-6">{{ m.field(form.password.first) }}</div>
<div class="col-sm-6">{{ m.field(form.password.second) }}</div>
</div>
{{ m.field(form.current_password) }}
<div class="d-flex gap-2 mt-4">
<button type="submit" class="btn btn-primary">{{ 'PERSONS.SAVE'|trans }}</button>
<a class="btn btn-secondary" href="{{ path('area') }}">{{ 'MY_ACCOUNT.BACK'|trans }}</a>
</div>
{{ form_end(form) }}
</div>
{# 2. 删除。密码字段与第一个表单的密码字段名称相同
(current_password),但 id 不同:同一页面的
两个元素不能有相同的 id #}
<div class="card p-4 border-danger">
<h5 class="card-title text-danger mb-1">{{ 'MY_ACCOUNT.DELETE_TITLE'|trans }}</h5>
<p class="text-muted small">{{ 'MY_ACCOUNT.DELETE_HELP'|trans }}</p>
<form method="post" action="{{ path('account_delete') }}" class="d-flex flex-wrap gap-2 align-items-end"
data-confirmation="{{ 'MY_ACCOUNT.DELETE_CONFIRM'|trans }}">
<input type="hidden" name="_token" value="{{ csrf_token('rdvmedecins') }}">
<div class="flex-grow-1">
<label class="form-label" for="delete_password">{{ 'MY_ACCOUNT.CURRENT_PASSWORD_LABEL'|trans }}</label>
<input id="delete_password" name="current_password" type="password" maxlength="72"
autocomplete="current-password" required class="form-control">
</div>
<button type="submit" class="btn btn-danger">{{ 'MY_ACCOUNT.DELETE_SUBMIT'|trans }}</button>
</form>
</div>
</div>
</div>
{% endblock %}
|
“Manage my account”:同一页面上的两个独立表单。
- 第 18–38 行:更新,使用 [MyAccountType] 表单:身份字段、登录名、新密码及其确认(可选),以及当前密码(必填)。版本(乐观锁)由 [form_end] 设置;
- 第 43–56 行:删除账户,一个手写的表单,带有自己的当前密码字段和一个确认字段。该字段名为 [current_password] (第一个表单中的字段名为 [my_account[current_password]]:Form 组件会在其字段名前加上表单名作为前缀),并且有自己唯一的 ID:页面上的两个元素不能有相同的 ID,如标签的 [for] 属性所示。
11.20.3.8. templates/error.html.twig
| {# =========================================================================
templates/error.html.twig - 错误页面(400、403、404、405、419、
500...),由 src/EventListener/ErrorPage.php 构建。
========================================================================= #}
{% extends 'layout.html.twig' %}
{% block content %}
<div class="row justify-content-center">
<div class="col-md-8 col-lg-6">
<div class="card p-4 text-center">
<h1 class="display-4 text-danger">{{ code }}</h1>
<p class="lead">{{ message|trans }}</p>
<div><a class="btn btn-primary" href="{{ path('home') }}">{{ 'ERROR_PAGE.BACK'|trans }}</a></div>
</div>
</div>
</div>
{% endblock %}
|
错误页面,由 [ErrorPage] 监听器生成:HTTP 代码、消息,以及指向主页的链接([/],它会重定向到该角色的主页或登录页面)。
11.21. 静态文件
[public] 文件夹是站点的根目录:服务器会原样发送位于其中的文件(示例 15)。除了 [index.php] 之外,它还包含 [Bootstrap] ([lib/bootstrap])、一个样式表和一个脚本。
11.21.1. public/css/styles.css
| /* =========================================================================
public/css/styles.css - a few settings on top of Bootstrap
(the same as in the other versions of this application).
========================================================================= */
body {
background-color: #f5f7fa;
}
.free-slot:hover {
background-color: #e9f7ef;
}
/* -------------------------------------------------------------------------
.error-zone: the error messages, at the bottom of the page, on a light pink background
(see templates/fragments/errors.html.twig).
position: sticky + bottom: if the page is taller than the window (a
schedule of 12 slots, for example), the zone stays stuck to the bottom of the
window instead of disappearing below the fold - without ever
covering the content when the page is short.
z-index: above the grey background of the booking dialog (.modal-backdrop).
------------------------------------------------------------------------- */
.error-zone {
position: sticky;
bottom: 1rem;
z-index: 1060;
margin-top: 1.5rem;
padding: 0.75rem 1rem;
background-color: #fdecef; /* 浅粉色 */
border: 1px solid #f5c2c7;
border-radius: 0.375rem;
color: #842029;
}
/* 患者“My area”页面的两个大选项 */
.option-card {
transition: border-color 0.15s, box-shadow 0.15s;
}
.option-card:hover {
border-color: #0d6efd;
box-shadow: 0 0.25rem 0.75rem rgba(13, 110, 253, 0.15);
}
/* 验证码图像(150 x 50 像素的 SVG) */
.captcha-image svg {
display: block;
border: 1px solid #dee2e6;
border-radius: 0.375rem;
}
|
[Bootstrap] 的一些附加设置,与该应用程序其他版本中的相同。
- 第 10–12 行:当鼠标悬停在日程表中可预订的行上时,该行变为绿色;
- 第 23–33 行:页面底部的错误区域具有浅粉色背景。[position: sticky] 配合 [bottom: 1rem]:如果页面比窗口高(例如有 12 个时间段的日程表),该区域会保持固定在窗口底部,而不是消失在滚动条下方;如果页面较短,它会留在原位而不遮挡任何内容。[z-index]:它显示在预订窗口的灰色背景之上;
- 第 36–43 行:两张大的“My area”卡片,鼠标悬停在上面时会亮起;
- 第 46–50 行:验证码图像,带有边框。
11.21.2. public/js/app.js
| // =========================================================================
// public/js/app.js - 应用程序中唯一的 JavaScript。
// -------------------------------------------------------------------------
// 整个应用程序在没有 JavaScript 的情况下也能工作。该脚本增加了一项
// 便利功能:在发送带有属性
// data-confirmation="..." 的表单之前,一个模态对话框会询问“Are you sure?”
// (对话框本身在页面中:templates/fragments/confirmation.html.twig)。
// 如果 JavaScript 被禁用,表单将不经
// 确认直接发送 - 不会有任何问题(“渐进增强”原则)。
//
// 为什么不用 window.confirm()?它的对话框无法设置样式,并且其
// 按钮保持浏览器的语言,而不是页面的语言。
// =========================================================================
(() => {
const modal = document.getElementById('confirmation-modal');
if (!modal) {
return;
}
const message = document.getElementById('confirmation-modal-message');
const noButton = modal.querySelector('.modal-footer [data-action="no"]');
let pendingForm = null; // 用户确认时要发送的表单
let previousFocus = null; // 关闭时要把焦点交还给的元素
function open(form) {
pendingForm = form;
previousFocus = document.activeElement;
// textContent(而不是 innerHTML):消息作为文本显示,
// 绝不会被解释为 HTML
message.textContent = form.dataset.confirmation;
modal.classList.remove('d-none');
// 焦点落在“No”上:心不在焉地按下 Enter 不会删除任何内容
noButton.focus();
}
function close() {
modal.classList.add('d-none');
pendingForm = null;
if (previousFocus) {
previousFocus.focus();
}
}
// 1. 我们拦截需要确认的表单的发送
document.querySelectorAll('form[data-confirmation]').forEach((form) => {
form.addEventListener('submit', (event) => {
event.preventDefault();
open(form);
});
});
// 2. 对话框的按钮(Yes / No / 关闭叉号)
modal.addEventListener('click', (event) => {
const action = event.target.closest('[data-action]')?.dataset.action;
if (action === 'yes') {
const form = pendingForm;
close();
// form.submit() 发送表单而不会再次触发
// 'submit' 事件:不会有新的确认请求
form.submit();
} else if (action === 'no') {
close();
} else if (event.target.classList.contains('modal')) {
close(); // 点击对话框外灰色的背景
}
});
// 3. 键盘:Escape 关闭对话框;Tab 停留在对话框内部
// (否则焦点会跑到后面变灰的页面上)
modal.addEventListener('keydown', (event) => {
if (event.key === 'Escape') {
close();
} else if (event.key === 'Tab') {
const buttons = [...modal.querySelectorAll('button')];
const first = buttons[0];
const last = buttons[buttons.length - 1];
if (event.shiftKey && document.activeElement === first) {
event.preventDefault();
last.focus();
} else if (!event.shiftKey && document.activeElement === last) {
event.preventDefault();
first.focus();
}
}
});
})();
|
应用程序中唯一的 [JavaScript] ——即示例 21 中的那个——并做了一些补充。整个应用程序在没有 [JavaScript] 的情况下也能工作:该脚本通过在提交带有 [data-confirmation] 属性的表单之前提供确认,增加了便利性。如果 [JavaScript] 被禁用,表单将不经确认直接提交:不会有任何问题(这遵循渐进增强原则)。
- 第 15–19 行:该脚本是一个在定义后立即调用的函数([(() => { ... })()]);其变量对页面的其余部分不可见。如果页面上没有确认窗口,它什么也不做;
- 第 26–35 行:打开窗口:存储用户确认后要提交的表单,并在窗口中显示该表单的消息。[textContent],而不是 [innerHTML]:消息作为文本 显示,绝不会被解释为 HTML。焦点 移到“No”按钮上:意外按下 Enter 不会删除任何内容;
- 第 37–43 行:关闭窗口;焦点返回到之前拥有它的元素;
- 第 46–51 行:拦截每个需要确认的表单的提交([preventDefault] 阻止它),并打开窗口;
- 第 54–67 行:窗口的按钮。整个窗口只有一个处理程序:[closest('[data-action]')] 找到被点击的按钮或包含它的元素。“Yes”通过 [form.submit()] 提交表单,它不会触发 [submit] 事件:因此不会再发出新的确认请求。点击窗口外变灰的背景会关闭窗口;
- 第 71–86 行:键盘。Esc 关闭窗口;Tab 键将焦点从一个按钮移到另一个按钮,而不会离开窗口(否则,焦点会移到其后变灰的页面上):这正是使用键盘导航的用户和屏幕阅读器所期望的。