1. 简介
本文档的 PDF 在 |此处|。
本文档的代码在 |此处|。
本文档由 Anthropic 的 AI Claude 制作。它承接文档 “[Flask] Web 框架分步入门”(2026 年),而该文档又承接了文档 “[Spring MVC] Web 框架分步入门”、"[ASP.NET Core MVC] Web 框架分步入门" 和 "[NestJS] Web 框架分步入门"(2026 年)。本文档将 [Flask] 课程改编到 [PHP] 环境:
- [Flask] 框架和 [Python] 语言被 [Laravel] 13 框架和 [PHP] 语言(8.4 或更高版本)取代;
- [Jinja2] 视图被 [Blade] 视图取代,后者是 [Laravel] 的视图引擎;
- 由 [Pydantic] 和 [WTForms] 完成的验证被 [Laravel] 的验证取代:验证规则和 表单请求 ([FormRequest]);
- [Flask] 中几十行手写的安全代码 被 [Laravel] 的身份验证系统(守卫、中间件、[Gate]、[Hash] 门面、尝试次数限制器)取代,并辅以用于 JWT 令牌的 [firebase/php-jwt] 库;
- ORM 和 [SQLAlchemy] 被 [Laravel] 的 ORM [Eloquent] 取代,仍然基于 [MySQL]。
本文档紧密遵循 [Flask] 课程的结构:先是大量小项目,每个项目聚焦一个特定概念,随后是一个完整的案例研究——一个为医疗诊所安排预约的 Web 应用——所有文件都有完整注释。这些示例的编号和主题与 [Flask]、[Spring MVC] 和 [ASP.NET Core MVC] 课程相同:熟悉其中任何一门课程的读者都可以逐个示例地比较这些框架。不过这并非必需:本文档自成一体,不要求事先了解这些框架。唯一的先修知识是 Web 编程的基本概念(HTTP 协议、HTML 语言)和 [PHP] 语言的基础(变量、数组、函数、类)。课程 “通过示例介绍 PHP7 语言”(2019 年)为需要先学习该语言的读者介绍了语言本身;此处用到的 [PHP] 8 新特性(构造器属性提升、[readonly] 类、枚举、命名参数、空安全运算符等)会在首次出现时加以说明。
1.1. Laravel 在 Web 应用中的角色
Web 应用通常按层构建,每一层只与相邻的层通信:

- Web 层接收来自浏览器的 HTTP 请求,并向其返回 HTML 页面。这一层正是 [Laravel] 帮助我们编写的部分;
- 业务层包含应用的业务规则(例如“一位患者只能有一个即将到来的预约”)。它对 Web 一无所知:它同样可以为命令行应用提供服务;
- 数据访问层(DAO 层,即 *Data Access Object*)负责读写数据库。我们将使用 [Eloquent],即 [Laravel] 的 ORM(*Object Relational Mapper*),它把表中的行映射为 [PHP] 对象。
Web 层本身遵循 MVC(*Model-View-Controller*)模式:
- 控制器(C)是一个 [PHP] 类,其方法称为 动作,每个动作处理一种特定类型的请求(例如 [GET /schedule])。动作读取请求参数,通过业务层处理请求,然后选择要显示的视图;
- 模型(M)是动作传递给视图的数据集合;
- 视图(V)是一个 [Blade] 文件(扩展名 [.blade.php]):一个包含 [{{ ... }}] 表达式以及 [@if]、[@foreach] 等指令的 HTML 页面,[Blade] 引擎会用模板中的数据替换这些内容。
关于术语的说明,以避免混淆:在 [Laravel] 中,“模型” (*model*)通常指 [Eloquent] 模型,即表示数据库表的类(位于 [app/Models] 文件夹)。本文档在两种意义上使用这个词,并且每次都会指明是哪一种:视图模型 (传递给视图的数据)和 [Eloquent] 模型 (见数据访问一章)。词语 “模板” 指其他页面所继承的公共视图(视图一章)。
请求的处理过程遵循图中编号的步骤:
- 1:浏览器发送 HTTP 请求,例如 [GET /schedule?doctorId=1&day=2026-09-26];
- 2:Web 服务器接收请求,并通过 [Laravel] 应用的 [public/index.php] 文件将请求交给它。开发期间,这个服务器是 [PHP] 自带的服务器,通过命令 [php artisan serve] 启动;生产环境中则是 [nginx] 或 [Apache] 之类的服务器,并与 [PHP-FPM] 配合。请求会经过 中间件 组件——处理所有请求的类(Cookie、会话、安全等)——然后 [Laravel] 将请求的路径与应用的路由进行比较,并选择负责处理该请求的动作:这就是 路由;
- 3:动作向业务层请求所需的数据;必要时,业务层会联系 DAO 层,由 DAO 层通过 SQL 查询 [MySQL] 数据库;
- 4:动作构造视图的 M 模型,并指示 [Blade] 引擎生成页面(函数 [view]);
- 5:视图生成的 HTML 页面就是动作的响应,由 [Laravel] 返回给浏览器。
[Laravel] 是 [PHP] 世界中使用最广泛的 Web 框架,领先于 [Symfony] (顺带一提,它正是基于 Symfony 的组件构建的)。它免费开源,由 Taylor Otwell 于 2011 年创建,凡是能运行 [PHP] ([Windows]、[Linux]、[macOS])的地方都能运行,而且 [PHP] 几乎所有虚拟主机提供商都支持。它是一个 全功能 框架:路由、视图、验证、会话、缓存、身份验证、翻译、数据库访问、邮件发送、后台任务……一切都已提供,并且被设计为协同工作。这与上一课的微框架 [Flask] 正好相反,后者把组装组件的工作留给开发者自己:[Laravel] 自己就能完成很多事情,而且代码很少,本文档的目标之一就是揭示“幕后”发生了什么。[Laravel] 既可以创建向客户端返回 JSON 的服务器([JavaScript]、[Angular]、[React]、[Vue.js]、[Flutter]……),也可以创建传统的 Web 应用,即由服务器生成 HTML 页面、浏览器只负责显示。本文档讨论的正是第二种用法。
[PHP] 的一个特性很好地解释了 [Laravel] 的许多行为:应用会 在每次请求时重新构建 ,然后被丢弃(示例 01)。我们会经常回到这一点。
1.2. 所用工具
这些示例使用以下工具编写和测试(安装说明见附录):
- [PHP] 8.4(8.4 或更高的任何版本均可),带有扩展 [intl]、[mbstring]、[openssl]、和 [pdo_mysql];
- [Composer] 2,[PHP] 的库管理器;
- 编辑器 [Visual Studio Code],带有扩展 [PHP Intelephense] (代码分析)和 [Laravel] ([Blade] 视图);
- 较新的浏览器([Chrome]、[Firefox]、[Edge]);
- 命令行工具 [curl],可显示原始的 HTTP 响应([Windows] 10 和 11 已自带);
- 数据库管理系统 [MySQL] (或 [MariaDB]),例如 [Laragon] 在 [Windows] 下提供的那个,从数据访问一章开始使用,案例研究中也要用到。在 [Windows] 下,[Laragon] 可以一次性安装 [PHP]、[Composer]、和 [MySQL] 。
[Laravel] 和其他库并不属于 [PHP]:[Composer] 在安装时从 [Packagist] 仓库下载它们(因此当天必须联网),并将其放入 [vendor] 文件夹。每个项目在 [composer.json] 文件中描述自己的库。下表列出了主要的库及所用版本:
[laravel/framework] | 框架本身:路由、中间件、控制器、视图([Blade])、验证、会话、缓存、身份验证、翻译、[Eloquent]…… | 13.33.0 |
[symfony/*] | [Symfony] 组件,[Laravel] 基于它们构建(HTTP 请求和响应、路由、控制台),随 Laravel 一同安装 | 8.1 |
[nesbot/carbon] | 日期(例如示例 12),随 [Laravel] 一同安装 | 3.14.0 |
[brick/math] | 精确的十进制数(示例 06),随 [Laravel] 一同安装 | 1.0.0 |
[firebase/php-jwt] | JWT 令牌(身份验证一节) | 7.2.0 |
[Laravel] 通常通过以下命令创建一个完整项目来安装:
[Composer] 随后会下载 骨架 ,即一个 [Laravel] 应用的骨架(约五十个文件和文件夹:配置、服务提供者、迁移、测试、[JavaScript] 构建工具等),再下载其库,并创建加密密钥。真正的项目就是这样开始的。就学习而言,这个骨架有一个缺点:它包含许多你暂时还不理解其用途的文件。因此,本文档的示例从另一端开始:示例 01 是尽可能小的 [Laravel] 应用,每个示例只添加自己需要的文件。结尾的案例研究采用标准 [Laravel] 应用的结构。
1.3. 运行案例研究
1.3.1. 安装 Laragon
案例研究需要数据库管理系统 MySQL、PHP 解释器,以及 PHP 和 [composer] 包安装器。Laragon 可以提供这一切,甚至更多。截至 2026 年 9 月,Laragon 可通过 URL 获取,网址为 [Download Laragon – Fast & Modern Dev Environment ]。Laragon 自带的工具可以让你安装 PHP 服务器以及数据库管理系统 [MySQL]:

- 在 [1] 中,是 Apache Web 服务器;
- 在 [2] 中,是数据库管理系统 [MySQL];
- 在 [3] 中,是一个我们不会使用的邮件工具;
- [4] 启动所有服务(Apache、[MySQL]、MailPit);
- [5] 显示 URL [http://localhost] 对应的网页。默认情况下,该 URL 指向 <laragon-install>\www 文件夹,其中 <laragon-install> 是 Laragon 的安装文件夹;
- 在 [6] 中,启动 HeidiSQL 工具,用于管理 MySQL 数据库。我们将用这个工具创建 RdvMedecins 应用所使用的数据库;
- 在 [7] 中,打开终端;Laragon 所需的全部二进制文件都在 PATH 中;
- 在 [8] 中,打开一个 Windows 资源管理器窗口,指向与 URL [http://localhost] 关联的文件夹;
Laragon 的安装文件夹包含以下内容:
![]() |
- 在 [1] 中,[bin] 文件夹包含许多应用程序:
![]() |
- 在 [1] 中,Apache Web 服务器;
- 在 [2] 中,命令行终端;
- 在 [3] 中,[git] 客户端,可用于管理项目的不同版本;
- 在 [4] 中,数据库管理器;
- 在 [5] 中,邮件管理器;
- 在 [6] 中,数据库管理系统 [MySQL];
- [7],另一个 Web 服务器;
- 在 [8] 中,[node.js] 用于运行 JavaScript 脚本;
- [9],文本编辑器;
- [10],PHP 解释器;
- [11],[Python] 解释器;
- [12],缓存服务器;
Laragon 自带一个完整的开发环境。在本课程中,我们将使用:
- 数据库管理系统 [MySQL],[6],以及用于图形化管理的 [heidisql] 工具;
- PHP 8.5 解释器;
- [composer] 包安装器;
案例研究的 README 指出,必须在终端中输入以下命令:
以安装示例和案例研究所需的 PHP 包。
以运行某个示例或案例研究。如果你在 VSCode 中使用 [PowerShell] 终端,会遇到这样的问题:安装 Laragon 之后,Windows 机器的 PATH 目录中既没有 [composer] 也没有 [php]。因此,在 VSCode 终端中这些命令不会被识别。
要把 [composer] 和 [php] 加入 Windows 机器的 PATH,请以 [administrator] 模式打开 PowerShell 终端,然后输入以下命令:
[Environment]::SetEnvironmentVariable("Path",[Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\laragon\bin\composer","Machine")
[Environment]::SetEnvironmentVariable("Path",[Environment]::GetEnvironmentVariable("Path", "Machine") + ";C:\laragon\bin\php\php-8.5.11-nts-Win32-vs17-x64","Machine")
请根据你的环境调整两处高亮显示的路径。
需要重启 VSCode,这些更改才会生效。
要创建案例研究所需的 [MySQL] 数据库,请按以下步骤操作:
![]() |
- 在 [1] 中,必须启动所有服务;
- 在 [2] 中,[Database] 选项可用于管理数据库;
[Database] 选项会启动一个名为 HeidiSQL 的工具:
![]() |
- 在 [1] 中,可以选择各种数据库管理系统选项。默认值是 MySQL,这样就可以;
- 在 [2] 中,登录 HeidiSQL;
![]() | ![]() |
- 在 [1-2] 中,运行 SQL 文件,然后选择 [dbrdvmedecins2.sql] 文件,它位于 [laravel-sept-2026/rdvmedecins2-laravel/database] 文件夹中:

运行 [3] 文件会创建案例研究所使用的 [dbrdvmedecins2] 数据库。要查看它,请在 HeidiSQL 中按 F5 刷新显示:
编者注:以下截图显示的是名为 [dbrdvmedecins] 的数据库,而案例研究中的数据库名为 [dbrdvmedecins2]。这两个数据库几乎完全相同,因此我们认为没有必要重新截图。
注释结束

数据库 [dbrdvmedecins] 已创建。其内容如下:

- 在 [1-3] 中,表 [clients];
- [id] 是该表的主键;
- [version] 是行的版本号。每次修改该行,此编号都会递增;
- [titre, nom, prenom] 标识此人;

- 在 [1-3] 中,表 [medecins];
- [id] 是该表的主键;
- [version] 是行的版本号;
- [titre, nom, prenom] 标识此人;

- 在 [1-3] 中,医生的预约时间段表:
- [id]:主键;
- [version]:行的版本号;
- [id-medecin]:外键,引用医生的主键;
- [hdebut, mdebut]:预约开始时间的小时和分钟。因此,[8,20] 表示上午 8:20。
- [hfin, mfin]:诊疗结束时间的小时和分钟。

- 在 [1-3] 中,已安排预约的 [rv] 表;
- [id]:主键;
- [version]:版本号;
- [jour]:预约日期;
- [id_creneau]:外键,引用预约时间段的主键。由于时间段与某位医生关联,因此我们可以知道由哪位医生负责这次预约;
- [id_client]:外键,指向前来就诊的患者的编号(主键);

- 在 [1-3] 中,表 [users] 列出了获准使用该应用的用户;
- [id, version]:主键、版本号;
- [login, password]:用户凭据;
- [nom]:用户姓名;
- [role]:用户的角色。[ADMIN] 拥有全部访问权限。[USER] 只有只读访问权限。该用户可以查看医生的日程,但不能安排或取消预约;
1.3.2. 运行案例研究
审阅者注:我建议读者按下文所述立即运行案例研究。在充分理解这个预约应用的用途之后,可以请你喜欢的 AI 按如下方式修改应用:从现在起,每位医生都可以:
- 在两个日期之间设置自己的预约时间段,从而按需调整日程;
- 在某一天从日历中移除某些时间段——例如,因个人原因无法出诊时;
这一修改并不简单,因为它涉及数据库结构的变更。请让 AI 为你提供新的应用代码以及创建新数据库的 SQL 脚本。为此,你需要把包含完整项目的 ZIP 文件以及旧数据库的 SQL 脚本提供给它。
此外,我没有审阅 Claude 创建的这门课程。他之前已经制作了 [NestJS]、[ASP.NET Core MVC]、[Spring MVC] 和 [Flask] 课程,全都完美无缺,所以我假定这一门也是如此。如果你在理解某些内容时遇到问题,解决办法始终相同:请你喜欢的 AI 解释你不理解的地方。例如 Claude 就非常擅长这件事。你可能需要把不理解的示例“上传”给它。
注释结束。
本文档末尾的案例研究是一个完整的应用。读者在深入了解框架细节之前,很可能想先看看它的运行效果:运行方法如下。它位于 [rdvmedecins2-laravel] 文件夹中,与 [examples] 文件夹并列:
你必须已安装 [PHP] (8.4 或更高版本)、[Composer]、[Visual Studio Code]、以及 [MySQL] (见附录)。然后:
- 通过运行 [dbrdvmedecins2] 数据库 的创建脚本 [rdvmedecins2-laravel/database/dbrdvmedecins2.sql] 来创建该数据库。使用 [Laragon] 时,打开 [HeidiSQL] 工具(Database 按钮),然后通过 File / Run SQL 菜单运行该脚本。在命令行中,从 [rdvmedecins2-laravel] 文件夹执行:
- 在 [Visual Studio Code] 中 打开 [rdvmedecins2-laravel] 文件夹(File 菜单 / Open Folder),然后打开终端(Terminal 菜单 / New Terminal);
- 安装 应用的 库:[Composer] 读取 [composer.json] 文件,下载 [Laravel] 和其他库,并将它们放入应用的 [vendor] 文件夹(需要几十秒):
- 检查与数据库的连接。应用连接到 [MySQL] ,地址为 [127.0.0.1],端口 3306,使用用户 [root] ,无密码 (这是 [Laragon] 的默认设置)。如果你的 [root] 账户有密码,请把它填写在应用的 [.env] 文件中 [DB_PASSWORD=] 这一行(例如 [DB_PASSWORD=myPassword]);
- 运行应用:
- [Laravel] 显示:
开发服务器在地址 [127.0.0.1] (即 [localhost])的 8081 端口上监听。收到的每个请求都会记录在控制台中,同时记录它发送给数据库的 SQL 命令;
- 在浏览器中打开地址 [http://localhost:8081] :

- 使用某个演示账户登录,其密码与用户名相同:[admin] (管理员)、[pelissier]、[tatou]、[dupont] (医生)、[martin]、[durand]、[bistrou]、[german] (患者)。还必须输入图片中的字符,大小写均可。
名为 [PHP] 的应用启动时并不会读取数据库:只有在第一个查询数据库的页面上——也就是建立连接时——才会出现连接错误。[Laravel] 随后会显示其调试页面,并把错误记录在 [storage/logs/laravel.log] 文件中。如果消息是 [SQLSTATE[HY000] [2002] Connection refused],说明 [MySQL] 尚未启动;如果是 [[1045] Access denied for user 'root'@'localhost'],说明密码不正确;如果是 [[1049] Unknown database 'dbrdvmedecins2'],说明 SQL 脚本没有执行;如果是 [could not find driver],说明 [pdo_mysql] 这个 [PHP] 扩展没有启用。如果 [php artisan serve] 命令本身失败并显示消息 [Failed opening required '.../vendor/autoload.php'],说明 [composer install] 没有执行;如果是 [Failed to listen on 127.0.0.1:8081 (reason: Address already in use)],说明 8081 端口已被占用(例如被应用的另一个版本占用)。应用的 [README.md] 文件还描述了其他情形。在终端中用 [Ctrl-C] 停止应用。
文档末尾的案例研究介绍了如何使用该应用,然后逐个文件加以讲解。
1.4. 示例
示例存放在 [examples] 文件夹中,每个示例对应一个子文件夹:
每个示例都是一个可独立运行的小型应用([Laravel])。所有示例使用相同的库,这些库在文件 [examples/composer.json] 中描述:
- 第 6–12 行:示例所需的内容:[PHP] 8.4 或更高版本,扩展 [intl] (按语言区域格式化数字,示例 16)和 [pdo_mysql](访问 [MySQL],示例 28),[Laravel],以及 [firebase/php-jwt] (JWT 令牌,示例 25)。[^13.33] 读作“13.33 版本,或主版本 13 中更新的版本”;
- 其余各行配置 [Composer] 的行为:优化类加载器,库按名称排序,并且只接受稳定版本。
要运行示例,首先要在 [examples] 文件夹下打开的终端窗口中安装它们的库(一劳永逸):
[Composer] 会创建 [examples/vendor] 文件夹,由全部 28 个示例共享 ,并创建 [composer.lock] 文件,它记录了所安装的确切版本(见案例研究)。[common] 文件夹包含 CSS 框架 [Bootstrap]([common/bootstrap]),由需要格式化页面的示例共享(从示例 15 开始),以及提供该框架的路由([common/bootstrap.php];见示例 15)。
几乎所有示例都具有相同的结构——即精简到只剩必要部分的标准 [Laravel] 应用的结构。例如示例 13 中的这个:
- [public/index.php]:所有请求的入口点;[bootstrap/app.php]:应用的结构;[artisan]:[Laravel] 的命令行工具(示例 01);
- [routes/web.php]:路由,将 URL 与动作关联起来(示例 02);
- [app]:应用的类:控制器([app/Http/Controllers])、模型、服务等;
- [resources/views]:[Blade] 视图(从视图一章开始);
- [.env]:该示例特有的设置(示例 01);[storage] 和 [bootstrap/cache]:由 [Laravel] 自己写入的文件(编译后的视图、缓存、会话、日志)。
要运行某个示例,请在其文件夹中打开终端(在 [Visual Studio Code] 中:右键单击示例文件夹,然后选择“在集成终端中打开”),并输入:
所有示例都监听 8000 端口:同一时间只能运行一个示例(或者必须更改端口:[php artisan serve --port=8001])。在终端中输入 [Ctrl-C] 即可停止服务器。修改 [PHP] 文件或视图之后无需重启服务器:更改会在下一次请求时生效(示例 01)。
在 [examples] 文件夹于 [Visual Studio Code] 中打开时,[PHP Intelephense] 扩展会分析所有文件,包括 [Laravel] 位于 [vendor] 文件夹中的文件:在每个文件中,你都可以使用代码补全、跳转到类或方法的定义([F12] 键)以及错误提示。由于所有示例的类都位于 [App] 命名空间中,扩展可能会标出“重复”的类:这不影响执行,因为每个示例都是独立运行的。要避免这些警告,只需直接打开示例自己的文件夹。
1.5. 文档内容
文档的结构如下:
动作、路由、响应 | 从请求到动作:路由、控制器、响应、重定向、共享服务 | 01 至 06 |
动作模型 | 请求参数:绑定、转换、验证、POST 表单 | 07 至 12 |
视图及其模板 | [Blade]、模板、组件、表单、验证、PRG、CSRF 防护 | 13 至 21 |
国际化 | 法语和英语的应用 | 22 |
数据作用域 | 请求、会话、缓存、Cookie | 23 |
请求的生命周期 | 中间件、参数绑定、异常处理器 | 24 |
身份验证与授权 | Cookie 中的 JWT、守卫、角色、验证码、尝试次数限制 | 25–27 |
分层架构与数据访问 | 使用 [Eloquent] 和 [MySQL] 的 Web / 业务 / DAO | 28 |
案例研究 | RdvMedecins 应用,逐个文件讲解 | - |
每个示例只引入少量新概念,各章前后衔接:最好按顺序阅读。而案例研究则运用了 前面各章的所有 概念:在相关之处,它的讲解会指向引入该概念的示例。附录介绍如何安装这些工具:[PHP]、[Composer]、[Visual Studio Code] 及其扩展、[MySQL] 以及 [Laragon],还有 [curl]。





