Skip to content

17. Web 服务

注意:这里所说的“Web 服务”,指的是任何提供原始数据并由客户端使用的 Web 应用程序——在下面的示例中,客户端是一个控制台脚本。我们并不关心某种特定的技术——例如 REST(REpresentational State Transfer,表述性状态传递)或 SOAP(Simple Object Access Protocol,简单对象访问协议),它们以明确定义的格式传递数据:REST 通常使用 JSON,SOAP 使用 XML。这些技术中的每一种都精确地描述了客户端必须如何查询服务器,以及服务器响应必须采用的格式。在本课程中,对于客户端请求和服务器响应的性质,我们将灵活得多。不过,所编写的脚本和所使用的工具与 REST 技术相似。

17.1. 简介

由于 PHP 程序可以由 Web 服务器执行,这样的程序就成为能够为多个客户端提供服务的服务器程序。从客户端的角度来看,调用一个 Web 服务就相当于请求该服务的 URL。客户端可以用任何语言编写,包括 PHP。我们还需要知道如何与 Web 服务“通信”,也就是理解 Web 服务器与其客户端之间的 HTTP 通信协议。这正是上一章的目的,上一章向我们介绍了该协议的一部分。

Image

在最简单的形式下,客户端/服务器之间的交互过程如下:

  • 客户端打开到 Web 服务器 80 端口的连接;
  • 客户端发送一个文档请求;
  • Web 服务器发送所请求的文档并关闭连接;
  • 然后客户端关闭连接。

文档可以是各种类型:HTML 格式的文本、图像、视频等。它可以是现有的文档(静态文档),也可以是由脚本即时生成的文档(动态文档)。后一种情况称为 Web 编程。动态生成文档的脚本可以用多种语言编写:PHP、Python、Java、JavaScript、C#、Ruby……

接下来,我们将使用 PHP 脚本来动态生成文本文档。

Image

  • 在 [1] 中,客户端与服务器建立连接,请求一个 PHP 脚本,并且可以向该脚本发送参数,也可以不发送;
  • 在 [2] 中,Web 服务器让 PHP 解释器执行该 PHP 脚本。脚本生成一个文档,并将其发送给客户端 [3];
  • 服务器关闭连接。客户端也同样关闭连接。

Web 服务器可以同时处理多个客户端。

在 [Laragon] 中,Web 服务器是 [Apache],这是 Apache 基金会的开源服务器(https://httpd.apache.org)。在接下来的应用中,必须启动 [Laragon] 并启动其服务([Start All] 按钮位于 [Laragon] 窗口中)。这会启动 [Apache] Web 服务器以及 [MySQL] 数据库管理系统。[Laragon] 的 [Apache] 服务器使用在 [Laragon] 中所选 PHP 版本(此处为 PHP 8.5)的 [mod_php] 模块来执行 PHP 脚本。

到目前为止,我们编写的 PHP 脚本都是在控制台环境中运行的:

Image

用户使用控制台(VS Code 终端)请求执行 PHP 脚本并接收其结果。

在下面介绍的客户端/服务器应用中:

  • 客户端脚本在控制台环境中执行;
  • 服务器脚本在 Web 环境中执行。

Image

PHP 服务器脚本不能放在文件系统中的任意位置。这是因为 Web 服务器会在配置所指定的位置查找它被请求提供的静态和动态文档。[Laragon] 的默认配置会在 [<laragon>/www] 文件夹中查找文档,其中 [<laragon>] 是 [Laragon] 的安装文件夹(例如 [C:\laragon])。因此,如果 Web 客户端使用 URL [http://localhost/D] 请求文档 D,Web 服务器将从路径 [<laragon>/www/D] 提供文档 D。

本课程的代码文件夹 [php8-oct-2026] 已放置在 [<laragon>/www] 文件夹中(参见安装一章)。本章的服务器脚本位于 [php8-oct-2026/scripts-web] 文件夹中。如果某个服务器脚本名为 [S.php],则将使用 URL [http://localhost/php8-oct-2026/scripts-web/S.php] 向 Web 服务器发起请求。随后将提供文档 [<laragon>/www/php8-oct-2026/scripts-web/S.php]。

客户端脚本位于 [php8-oct-2026/scripts-console/web-clients] 文件夹中。下面是这两个文件夹的结构(每个带编号的文件夹对应本章的一个小节):

php8-oct-2026
├── scripts-console
│   └── web-clients
│       ├── 02      date / time client
│       ├── 03      JSON client
│       ├── 04      server environment client
│       ├── 05      GET / POST clients
│       ├── 06      client with a session (examples 1 and 2)
│       └── 08      client with authentication
├── scripts-web
│   ├── 01          static and dynamic pages
│   ├── 02          date / time server
│   ├── 03          JSON server
│   ├── 04          server environment
│   ├── 05          GET / POST server
│   ├── 06          sessions - example 1
│   ├── 07          sessions - example 2
│   └── 08          authentication
└── vendor          libraries installed by Composer

在 VS Code 中,打开 [php8-oct-2026] 文件夹([File / Open Folder] 菜单)。这样,所有 Web 脚本和控制台脚本文件都可以在 VS Code 的资源管理器中访问,[PHP Intelephense] 扩展会分析这两类脚本中的代码。无需创建“Web 项目”:对于 [Apache] 服务器来说,Web 脚本就是位于 [.php] 文件夹 [<laragon>/www] 中的一个文件。

本章使用的 HTTP 客户端有:

  • Web 浏览器(Chrome、Firefox、Edge 等);
  • 命令行工具 [curl],在 Windows 11 中可用(在 [Laragon] 终端中也可用)。在 [PowerShell] 终端中,必须输入 [curl.exe] 而不是 [curl],因为在 Windows PowerShell 中,[curl] 是命令 [Invoke-WebRequest] 的别名,而该命令的选项与之不同。在 [Command Prompt] (cmd)终端或 [Laragon] 终端中,直接使用 [curl] 即可;
  • 使用 Symfony [HttpClient] 库的 PHP 控制台脚本。

我们将使用 [curl] 的几个选项:

选项
作用
[-i]
在文档之前显示 HTTP 响应头
[-v]
详细模式:同时显示 [curl] 所发送的 HTTP 头
[-d name=value]
通过 POST 请求发送参数
[--data-urlencode "name=value"]
同上,并对值进行 URL 编码
[-u login:password]
[Basic] 身份验证
[-c file] / [-b file]
保存 / 回传从服务器收到的 Cookie

17.2. 编写静态页面

注意:在接下来的过程中,[Laragon] 必须保持运行。

我们将演示如何用 HTML(HyperText Markup Language,超文本标记语言)创建一个静态页面。在 VS Code 中,创建文件夹 [scripts-web/01] ,然后在该文件夹中创建文件 [example-01.html]。在空的 HTML 文件中,VS Code 提供了页面模板:只需输入 [!] ,然后按 [Tab] 键(VS Code 的 [Emmet] 功能)。我们按如下方式补全该模板:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>
  • 第 6 行:页面标题;
  • 第 9 行:页面内容。

现在让我们用 [Laragon] 的 [Apache] 服务器来显示这个 HTML 页面。在浏览器中,我们请求 URL [http://localhost/php8-oct-2026/scripts-web/01/example-01.html]:

Image

  • 顶部的标签页显示页面标题,地址栏显示所请求的 URL;
  • 下方是页面内容。

所显示的页面是静态页面:你可以在浏览器中任意多次重新加载它(F5),显示的内容始终相同。

大多数浏览器都提供了查看客户端与服务器之间交换的数据的功能,如上一章所述:按 F12 打开开发者工具,然后选择 [Network] 选项卡并重新加载页面(F5)。点击所加载的文档,就可以看到发送给服务器的命令、浏览器请求的头、服务器响应的头,以及接收到的文档。

[curl] 工具可以让你在终端中查看同样的信息。使用 [-i] 选项时,它会显示服务器响应的 HTTP 头,随后是接收到的文档:

> curl -i http://localhost/php8-oct-2026/scripts-web/01/example-01.html
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
Last-Modified: Thu, 01 Oct 2026 14:29:23 GMT
ETag: "12b-65cc83df75105"
Accept-Ranges: bytes
Content-Length: 299
Vary: Accept-Encoding
Content-Type: text/html

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>
  • 第 2 行:响应状态行:HTTP 协议版本、状态码 [200] 及其描述 [OK];
  • 接下来是 HTTP 响应头。其中尤其包括响应日期 [Date]、服务器标识 [Server]、文档最后修改日期 [Last-Modified]、以字节为单位的大小 [Content-Length] 以及其类型 [Content-Type];
  • 随后是一个空行,用于分隔头部和文档;
  • 最后是我们创建的 HTML 文档。浏览器解释这段代码,以显示上面所示的页面。

17.3. 用 PHP 创建动态页面

现在我们来编写一个 PHP 动态页面。在 [scripts-web/01] 文件夹中,创建如下文件 [example-01.php]:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Example of a dynamic page</title>
    </head>
    <body>
        <?php
        // time():自 1970 年 1 月 1 日 00:00:00 UTC 以来经过的秒数
        // 日期和时间的显示格式
        // d:日,2 位数字
        // m:月,2 位数字
        // y:年,2 位数字
        // H:小时 00-23
        // i:分钟
        // s:秒
        print "<b>Today's date and time: </b>" . date("d/m/y H:i:s", time());
        ?>
    </body>
</html>

说明

  • 第 5 行:页面标题;
  • 第 8 行:PHP 代码放在标签 [<?php] 和 [?>] 之间。这些标签之外的所有内容都是 HTML;
  • 第 17 行:写出当前日期和时间。[time] 函数返回自 1970 年 1 月 1 日 0:00 UTC 以来经过的秒数。函数 [date] 按其第一个参数指定的格式对该数字进行格式化,这里的格式为 日/月/年 时:分:秒。

从本质上讲,上面的 PHP 脚本是把当前时间写到控制台。然而,当它由 Web 服务器执行时,[print] 语句的输出流——通常被定向到脚本的执行控制台——会被重定向到服务器与其客户端之间的连接。因此,在 Web 环境中,上面的脚本会把当前时间以文本形式发送给客户端——这里是浏览器。

让我们试试 URL [http://localhost/php8-oct-2026/scripts-web/01/example-01.php]:

Image

这是一个动态页面,因为如果在浏览器中多次重新加载页面(F5),其内容会发生变化(时间在变)。

浏览器收到的是一段 HTML 数据流。要查看它,可以在浏览器中显示页面的源代码(在页面上右键单击,选择 [View page source] 选项,或按 Ctrl-U),也可以使用 [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/01/example-01.php
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Vary: Accept-Encoding
Content-Length: 222
Content-Type: text/html; charset=UTF-8

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>Example of a dynamic page</title>
    </head>
    <body>
        <b>Today's date and time: </b>01/10/26 17:31:46    </body>
</html>
  • 空行之后是接收到的 HTML 代码。PHP 代码已经消失:它被其生成的文本(包括日期和时间)所取代;
  • 在各个头中,请求静态页面时不存在头 [X-Powered-By] 。它表明服务器的响应是由 PHP 脚本生成的。而头 [Last-Modified] 和 [ETag] 则消失了:该文档并不存在于磁盘上,而是在请求时生成的。[Content-Length] 头仍然存在:由于文档很短,[Apache] 能够在发送头之前完整接收它,从而计算出它的大小。

因此需要记住,打算由 Web 服务器执行并供浏览器使用的 PHP 脚本必须生成 HTML 数据流。我们将看到,脚本还可以生成 HTTP 头以及服务器响应的几乎所有元素。

17.4. HTML 语言基础

本章不会深入探讨 PHP 的 Web 编程。本课程后面会开发一个 MVC Web 应用。本章的重点是 Web 服务:即通过 Web 服务器向其他 PHP 客户端提供数据的 PHP 页面。不过,我们认为向读者介绍一些 HTML 的基础知识是有益的。

Web 浏览器可以显示各种文档,最常见的是 HTML 文档(HyperText Markup Language)。这是一种带格式的文本,包含形如 [<tag>text</tag>] 的标签。例如,文本 [<b>important</b>] 会以粗体显示 important 文本。还有独立标签,例如 [<hr>] 标签,它显示一条水平线。我们不会逐一介绍 HTML 文本中可能出现的所有标签。一个很好的参考资料是 Mozilla 文档网站: https://developer.mozilla.org/en-US/docs/Web/HTML。掌握 HTML 语言是必不可少的,因为动态 Web 应用必须自己生成要发送给 Web 客户端的 HTML 代码。

简而言之,开始 Web 编程并不需要掌握整个 HTML 语言。了解 HTML 语言各种细节的一种方法是浏览网页,并查看那些具有你尚不熟悉的有趣特性的页面的源代码。

请看下面的 [tags.html] 示例,它包含 Web 文档中常见的一些元素,例如:

  • 表格;
  • 图像;
  • 链接。

Image

HTML 文档通常具有如下格式:

<!DOCTYPE html>
<html>
    <head>
        <title>A title</title>
        ...
    </head>
    <body attributes>
        ...
    </body>
</html>

整个文档由 [<html>…</html>] 标签括起来。它由两部分组成:

  • [<head>…</head>]:这是文档中不可显示的部分。它向将要显示该文档的浏览器提供信息。它通常包含 [<title>…</title>] 标签,用于指定将出现在浏览器标签页中的文本。其他标签也可能出现,包括定义文档关键字的标签——这些关键字随后会被搜索引擎使用。这一部分还可以包含用 JavaScript 编写的脚本,它们将由浏览器执行;
  • [<body attributes>…</body>]:这是将由浏览器显示的部分。该部分包含的 HTML 标签向浏览器说明文档“期望的”视觉布局。

我们示例文档的 HTML 代码如下:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>A few HTML tags</title>
    </head>

    <body style="background-image: url(images/standard.jpg)">
        <h1 style="text-align: left">A few HTML tags</h1>
        <hr>

        <table border="1">
            <thead>
                <tr>
                    <th>Column 1</th>
                    <th>Column 2</th>
                    <th>Column 3</th>
                </tr>
            </thead>
            <tbody>
                <tr>
                    <td>cell(1,1)</td>
                    <td style="text-align: center;">cell(1,2)</td>
                    <td>cell(1,3)</td>
                </tr>
                <tr>
                    <td>cell(2,1)</td>
                    <td>cell(2,2)</td>
                    <td>cell(2,3)</td>
                </tr>
            </tbody>
        </table>
        <br><br>
        <table border="0">
            <tr>
                <td>An image</td>
                <td><img src="images/cherry-tree.jpg" alt="a cherry tree"></td>
            </tr>
            <tr>
                <td>The PHP language website</td>
                <td><a href="https://www.php.net/">here</a></td>
            </tr>
        </table>
    </body>
</html>
元素
HTML 标签和示例
  
文档标题
[<title>A few HTML tags</title>] (第 5 行):文本 [A few HTML tags] 将显示在显示该文档的浏览器标签页中
  
水平线
[<hr>]:显示一条水平线(第 10 行)
  
表格
[<table attributes>….</table>]:用于定义表格(第 12 行);
[<thead>…</thead>]:用于定义列标题({{L:<thead>
</thead>}});
[<tbody>…</tbody>]:用于定义表格内容({{L:<tbody>
</tbody>}});
[<tr attributes>…</tr>]:用于定义一行(第 21 行);
[<td attributes>…</td>]:用于定义一个单元格(第 22 行);
示例:
[<table border="1">…</table>]:属性 [border] 定义表格边框的粗细;
[<td style="text-align: center;">cell(1,2)</td>] (第 23 行):定义一个单元格,其内容为 [cell(1,2)]。该内容将水平居中([text-align: center])
图像
[<img src="images/cherry-tree.jpg" alt="a cherry tree">] (第 37 行):定义一幅图像,其源文件位于 Web 服务器上的 [images/cherry-tree.jpg]。属性 [alt] 提供替代文本,在图像无法显示时显示。这个标签出现在使用 URL [http://localhost/php8-oct-2026/scripts-web/01/tags.html] 生成的 Web 文档中。因此,浏览器将请求 URL [http://localhost/php8-oct-2026/scripts-web/01/images/cherry-tree.jpg] 来获取这里引用的图像
  
链接
[<a href="https://www.php.net/">here</a>] (第 41 行):使文本 [here] 成为指向 URL [https://www.php.net/] 的链接
  
页面背景
[<body style="background-image: url(images/standard.jpg)">] (第 8 行):指明用作页面背景的图像位于 Web 服务器上的 URL [images/standard.jpg] 。在我们的示例中,浏览器将请求 URL [http://localhost/php8-oct-2026/scripts-web/01/images/standard.jpg] 来获取这幅背景图像
  

这个简单的示例表明,为了构建整个文档,浏览器必须向服务器发出三个请求:

  • [http://localhost/php8-oct-2026/scripts-web/01/tags.html] 用于获取文档的 HTML 源码;
  • [http://localhost/php8-oct-2026/scripts-web/01/images/cherry-tree.jpg] 用于获取图像 [cherry-tree.jpg];
  • [http://localhost/php8-oct-2026/scripts-web/01/images/standard.jpg] 用于获取背景图像 [standard.jpg]。

浏览器开发者工具(F12)中的 [Network] 选项卡显示了这一点:它列出了浏览器发出的三个请求。

注意:在 Windows 上,文件名不区分大小写:[Cherry-tree.jpg] 和 [cherry-tree.jpg] 指的是同一个文件。而在大多数网站托管所用的 Linux 服务器上则并非如此。因此,你应该养成习惯,严格按照磁盘上的名称书写文件名,包括在 URL 中。

17.5. 让静态页面变为动态

让我们演示如何使 HTML 页面 [example-01.html] 变为动态。把它的内容复制到名为 [page-00.php] 的文件中。这个 PHP 脚本不含任何 PHP 代码——只有 HTML。让我们向服务器请求它:

> curl http://localhost/php8-oct-2026/scripts-web/01/page-00.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <title>PHP 8 by example</title>
    </head>
    <body>
        <div><b>This is an example of a static page</b></div>
    </body>
</html>

PHP 解释器处理了 [page-00.php] 脚本,并生成了与静态页面 [example-01.html] 相同的 HTML 输出。这告诉我们一件事:当 PHP 解释器在 PHP 脚本中遇到 HTML 时,它会保持其不变,并原样发送给客户端。

现在让我们在下面的 [page-01.php] 脚本中添加几条 PHP 指令,让 PHP 解释器有事可做:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title><?= $page->title ?></title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b><?= $page->contents ?></b></div>
    </body>
</html>
  • 第 4 行和第 9 行:我们添加了 PHP 代码来动态生成页面的标题和内容。这里我们假设变量 [$page] 是一个包含待显示数据的对象。[<?= expression ?>] 标签是 [<?php print expression ?>] 的简写。它专为这类页面设计:HTML 中夹杂少量由 PHP 计算出的值。

如果我们直接调用这个脚本,会得到如下结果:

> curl http://localhost/php8-oct-2026/scripts-web/01/page-01.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <title><br />
<b>Warning</b>:  Undefined variable $page in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>4</b><br />
<br />
<b>Warning</b>:  Attempt to read property "title" on null in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>4</b><br />
</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b><br />
<b>Warning</b>:  Undefined variable $page in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>9</b><br />
<br />
<b>Warning</b>:  Attempt to read property "contents" on null in <b>.../php8-oct-2026/scripts-web/01/page-01.php</b> on line <b>9</b><br />
</b></div>
    </body>
</html>
  • 第 5–8 行:页面标题无法计算,因为变量 [$page] 没有定义。PHP 在 HTML 流中插入了两条警告信息:变量 [$page] 不存在,并且无法读取 [null] 的属性 [title] ;
  • 第 14–17 行:内容方面存在同样的问题。

注意:从 PHP 8.0 开始,使用未定义的变量以及读取 [null] 的属性会触发 [Warning] 警告,而不是像 PHP 7 中那样只是一个 [Notice] 通知。这些信息会显示在页面上,是因为 [Laragon] 的 PHP 配置是开发配置([display_errors=On])。在生产服务器上,我们使用 [display_errors=Off],并将错误写入日志文件。

现在,让我们编写如下 [example-02.php] Web 脚本:

<?php

declare(strict_types=1);

// 我们定义要显示的页面元素
$page = new stdClass();
$page->title = "A new title";
$page->contents = "A new dynamically generated content";
// 我们让 [page-01.php] 显示出来
require_once __DIR__ . "/page-01.php";
  • 第 3 行:与本课程中所有 PHP 脚本一样,该脚本要求严格类型检查;
  • 第 6–8 行:我们定义 [$page] 对象。预定义类 [stdClass] 是唯一仍可在不产生警告的情况下添加未声明属性的类(还有带有 [#[\AllowDynamicProperties]] 属性(注解)的类):从 PHP 8.2 开始,在其他类的对象上创建动态属性已被弃用;
  • 第 10 行:包含脚本 [page-01.php]。该脚本中的代码随后将被解释执行:
    • 变量 [$page] 现在已经定义,PHP 解释器将使用它;
    • [page-01.php] 中的 HTML 代码将原样发送给客户端;
    • [<?= … ?>] 中表达式的结果将被包含在发送给客户端的文本流中。

现在,如果我们请求 Web 脚本 [example-02.php],在浏览器中会得到如下内容:

Image

下面是浏览器收到的文本:

> curl http://localhost/php8-oct-2026/scripts-web/01/example-02.php
<!DOCTYPE html>
<html lang="en">
    <head>
        <title>A new title</title>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
    </head>
    <body>
        <div><b>A new dynamically generated content</b></div>
    </body>
</html>
  • 第 5 行和第 10 行:PHP 代码以及 [page-01.php] 中的代码已被表达式 [$page->title] 和 [$page->contents] 的值所取代。

从这个例子中,我们可以得出两个要点:

  • 面向浏览器的 HTML 页面可以隔离成 PHP 脚本,其中只包含这些 HTML 代码和少量由 PHP 代码生成的动态部分。这些页面中的 PHP 应当尽可能少;
  • 所有生成 HTML 页面中所含动态数据的逻辑,都必须隔离到纯 PHP 脚本中,其中不含任何页面展示代码(HTML、CSS、JavaScript……)。

这样就可以实现任务分离:

  • 生成待显示 Web 页面的任务(HTML、CSS、JavaScript……);
  • 实现所构建 Web 应用逻辑的任务。这种逻辑可以采用分层架构来实现,与我们处理控制台脚本时完全一样。

注意:插入到 HTML 页面中的值通常应当用 [htmlspecialchars] 函数加以保护,该函数会把 HTML 中的特殊字符([<]、[>]、[&]、["])替换为相应的 HTML 代码。否则,如果用户提供的值包含诸如 [<script>] 这样的标签,就会被浏览器执行(XSS 漏洞)。在编写 HTML 页面时,我们还会回到这个问题。

接下来,我们将构建一些专用的 Web 脚本:

  • 它们只向客户端发送数据,而不发送任何格式(HTML、CSS、JavaScript)。因此它们是数据服务器,而不是网页;
  • 这些 Web 脚本的客户端将是控制台脚本,用于获取服务器发送的数据并对其进行处理。

17.6. 日期和时间的客户端/服务器应用

我们现在来看如下配置:

Image

我们将编写:

  • 一个 Web 脚本 [1],它向客户端发送当前的日期和时间;
  • 一个控制台脚本 [2] ,它充当该 Web 脚本的客户端:获取 Web 脚本发送的日期和时间,并在控制台上显示。
php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 02
│           ├── config-date-time-client-2.json
│           ├── config-date-time-client.json
│           ├── config-spy.json
│           ├── date-time-client.php
│           └── spy-server.php
└── scripts-web
    └── 02
        ├── date-time-server-2.php
        └── date-time-server.php

17.6.1. 服务器端脚本

我们已经编写过一个生成当前日期和时间的 Web 脚本:上一节中的 [example-01.php] 脚本。我们说过要编写数据服务器:不带格式(HTML)的原始数据。因此,服务器脚本 [date-time-server.php] 如下:

<?php

declare(strict_types=1);

// 日期函数使用的时区
date_default_timezone_set('Europe/Paris');
// 我们设置 HTTP [Content-Type] 头
header('Content-Type: text/plain; charset=UTF-8');
//
// 我们发送日期和时间
// time():自 1970 年 1 月 1 日 00:00:00 UTC 以来经过的秒数
// 日期和时间的显示格式
// d:日,2 位数字
// m:月,2 位数字
// y:年,2 位数字
// H:小时 00-23
// i:分钟
// s:秒
print date("d/m/y H:i:s", time());
  • 第 6 行:日期函数使用 [date.timezone] 指令在 [php.ini] 文件中设置的时区。为了避免依赖服务器配置,脚本自己设置了时区——这里是巴黎;
  • 第 8 行:[header] 函数向响应添加一个 HTTP 头。这里设置了 HTTP 和 [Content-Type] 头,它们告知客户端将要收到的文档的性质。对于 [example-01.php] 页面,[Content-Type] 是 [text/html; charset=UTF-8]。这里,我们告知客户端该文档是纯文本(不是 HTML)。这对我们的控制台客户端并不重要,它不会尝试使用这个头。而对于会使用这个头的 Web 浏览器来说则更为重要。HTTP 头位于服务器响应中的文档之前:因此必须在脚本写出任何内容之前调用 [header] 函数;
  • 第 19 行:发送给客户端的文档:日期和时间,不带 HTML 标签。

让我们用浏览器请求这个脚本:

Image

浏览器显示接收到的纯文本。使用 [curl] 时,我们可以看到脚本设置的 HTTP 头 [Content-Type] ,以及空行之后接收到的文本文档:

1
2
3
4
5
6
7
8
9
> curl -i http://localhost/php8-oct-2026/scripts-web/02/date-time-server.php
HTTP/1.1 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Content-Length: 17
Content-Type: text/plain; charset=UTF-8

01/10/26 17:31:46

17.6.2. 客户端脚本

在上一章中,我们编写了几个 HTTP 客户端。可以用它们来获取服务器脚本 [date-time-server.php] 发送的文本文档。不过我们不这样做。与处理 SMTP 和 IMAP 协议时一样,我们将使用第三方库,具体来说是 Symfony 框架的 [HttpClient] 组件,其文档位于 URL https://symfony.com/doc/current/http_client.html。

与前面的库一样,[HttpClient] 组件使用 [Composer] 工具安装。在 [php8-oct-2026] 文件夹中打开的终端窗口里,命令如下:

composer require symfony/http-client

这里不需要这样做:[php8-oct-2026] 文件夹中的 [composer.json] 文件已经声明了这一依赖(版本 8),以及我们很快将要用到的 [HttpFoundation] 组件的依赖。安装课程代码时运行的 [composer install] 命令已将它们安装到 [php8-oct-2026/vendor] 文件夹中。

控制台脚本 [date-time-client.php] 将处理如下 JSON 文件 [config-date-time-client.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/02/date-time-server.php"
}
  • 第 2 行:服务器脚本的 URL。

客户端脚本 [date-time-client.php] 如下:

<?php

declare(strict_types=1);

// 日期 / 时间服务的客户端

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 配置文件:命令行的第 1 个参数(如果存在)
$configFileName = $argv[1] ?? "config-date-time-client.json";

// 获取配置
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create();

try {
    // 我们发出请求
    $response = $httpClient->request('GET', $config['url']);
    // 响应的状态
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // 我们获取头部
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // 我们获取响应的正文
    $content = $response->getContent();
    // 我们显示它
    print "---Server response: [$content]\n";
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 8 行:与前面的库一样,我们加载 [vendor/autoload.php] 由 [Composer] 生成的文件。其路径基于常量 [__DIR__] 计算,该常量是脚本所在的文件夹:无论 [php8-oct-2026] 文件夹位于何处,脚本都能正常工作;
  • 第 10 行:我们声明将要使用的 [HttpClient] 类;
  • 第 11 行:[ExceptionInterface] 接口由 Symfony HTTP 客户端可能抛出的所有异常实现;
  • 第 14 行:配置文件的名称可以作为参数传递给脚本:[php date-time-client.php other-config.json]。否则使用文件 [config-date-time-client.json]。数组 [$argv] 包含命令行参数,其中 [$argv[0]] 是脚本的名称。运算符 [??] 在其左操作数存在且不是 [null] 时返回左操作数,否则返回右操作数;
  • 第 17–25 行:脚本的配置被读取到数组 [$config] 中。名为 [flags: JSON_THROW_ON_ERROR] 的参数指示 [json_decode] 在 JSON 不正确时抛出 [JsonException] 异常,而不是悄悄地返回 [null];
  • 第 29 行:创建一个 HTTP 客户端。静态方法 [create] 会选择最合适的实现:这里是 [CurlHttpClient] 类,它使用 PHP 的 [curl] 扩展;
  • 第 33 行:使用 GET 命令请求服务器脚本的 URL:[GET URL HTTP/1.1]。这个操作是异步的:执行会继续进入下一行,而不等待响应;
  • 第 35 行:获取响应状态码。它位于服务器响应的第一行。因此,如果这一行是 [HTTP/1.1 200 OK],则响应状态为 200。这个操作是阻塞的:直到客户端收到服务器响应的头之后,执行才会继续;
  • 第 39 行:获取 HTTP 响应头。我们得到一个关联数组,其键是头的名称(小写),其值是数组:因为同一个头确实可能在响应中出现多次。这里我们显示每个头的第一个值;
  • 第 43 行:获取服务器返回的文档;我们知道这个文档是文本;
  • 第 46 行:如果发生错误,则显示错误消息。PHP 7 的脚本捕获的是异常 [TypeError | RuntimeException];更精确的做法是捕获 HTTP 客户端异常,它们都实现了 [ExceptionInterface]。请注意,当响应状态码表示错误(300 到 599 的状态码)时,[getHeaders] 和 [getContent] 会抛出异常。我们将在关于身份验证的部分讨论这一点。

客户端在打开了相应目录的终端中运行(必须保持 [Laragon] 运行,服务器脚本才能被访问):

1
2
3
4
5
6
7
8
9
> php date-time-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
content-length: 17
content-type: text/plain; charset=UTF-8
---Server response: [01/10/26 18:55:26]

最后一行正确获取了当前日期和时间。显示的头与我们用 [curl] 看到的相同,只是名称为小写。

你可能很想知道客户端脚本向服务器发送了什么。在上一章中,我们为此使用了一个通用的 TCP 服务器,它会显示收到的文本行。这里,我们将编写一个小型 TCP“间谍”服务器 [spy-server.php],它做同样的事情,然后向客户端返回一个最简的 HTTP 响应:

<?php

declare(strict_types=1);

// 一个“间谍”TCP 服务器:它显示 HTTP 客户端发给它的内容
// 然后向其回送一个最小的 HTTP 响应
// 用法:php spy-server.php [port]

$port = (int) ($argv[1] ?? 100);
// 监听服务
$server = stream_socket_server("tcp://127.0.0.1:$port", $errorCode, $errorMessage);
if ($server === false) {
    print "Unable to create the service on port $port: $errorMessage\n";
    exit(1);
}
print "Spy server waiting for a client on port $port\n";
// 我们等待一个客户端(最多 5 分钟)
$client = stream_socket_accept($server, 300, $clientName);
if ($client === false) {
    print "No client showed up\n";
    exit(1);
}
print "Client connected: $clientName\n";
print "--- lines received\n";
// 读取 HTTP 头,直到空行
$contentLength = 0;
while (($line = fgets($client)) !== false) {
    $line = rtrim($line, "\r\n");
    print "$line\n";
    if ($line === "") {
        // 头部结束
        break;
    }
    // 头部之后的文档的大小
    if (preg_match('/^content-length:\s*(\d+)$/i', $line, $fields)) {
        $contentLength = (int) $fields[1];
    }
}
// 读取可能存在的文档
if ($contentLength > 0) {
    print stream_get_contents($client, $contentLength) . "\n";
}
// 最小的 HTTP 响应:状态行、头部、空行、文档
$document = "response of the spy server";
fwrite($client, "HTTP/1.1 200 OK\r\n"
    . "Content-Type: text/plain; charset=UTF-8\r\n"
    . "Content-Length: " . strlen($document) . "\r\n"
    . "Connection: close\r\n"
    . "\r\n"
    . $document);
// 通信结束
fclose($client);
fclose($server);
print "--- end of the communication\n";
  • 第 9 行:监听端口作为参数传入;默认值为 100;
  • 第 11 行:在本机的端口 [port] 上创建一个 TCP 服务;
  • 第 18 行:等待客户端;
  • 第 27 行:读取并显示收到的各行,直到结束 HTTP 头的空行为止。在此过程中,它会记下 [Content-Length] 头的值,该头指定了可能跟在头之后的文档的大小;
  • 第 40–41 行:读取并显示这个文档;
  • 第 45–50 行:发送一个最简的 HTTP 响应:状态行、头、空行、文档;
  • 第 52 行:关闭与客户端的连接,使其检测到已经收到完整的响应。

我们在第一个终端中启动间谍服务器:

php spy-server.php 100

配置文件 [config-spy.json] 指定本机的 100 端口:

1
2
3
{
    "url": "http://localhost:100/php8-oct-2026/scripts-web/02/date-time-server.php"
}

这一次,客户端连接到端口 100 上的服务器 [localhost] 。因此,将由我们的间谍服务器来处理请求。在第二个终端中,我们使用这个配置运行客户端:

1
2
3
4
5
6
7
> php date-time-client.php config-spy.json
---Response with status: 200
---Headers of the response
content-type: text/plain; charset=UTF-8
content-length: 26
connection: close
---Server response: [response of the spy server]
  • 第 7 行:客户端成功收到了间谍服务器发送的文档。

在第一个终端中,间谍服务器显示了它收到的内容:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:49512
--- lines received
GET /php8-oct-2026/scripts-web/02/date-time-server.php HTTP/1.1
Host: localhost:100
Accept: */*
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • 第 5 行:客户端脚本生成的 HTTP GET 命令;
  • 第 6 行:头 [Host] 指定目标机器和端口;
  • 第 8 行:Symfony 客户端标识 [HttpClient];
  • 第 9 行:客户端表明它接受 [gzip] 格式的压缩响应;
  • 第 10 行:结束头部的空行。GET 请求没有文档。

17.6.3. 服务器脚本——第 2 版

默认情况下,编写 Web 脚本的函数不是面向对象的。在服务器端,这意味着你最终会把类和传统的 PHP 函数混在一起使用。为了获得更一致的编码风格,我们将使用 Symfony 框架的 [HttpFoundation] 库。它把 Web 脚本的所有标准 PHP 函数封装到一套类和接口体系中:[Request] 类表示客户端请求,[Response] 类表示服务器响应。该库的文档位于 https://symfony.com/doc/current/components/http_foundation.html。

与 [HttpClient] 一样,[HttpFoundation] 库(版本 8)也已安装在 [vendor] 文件夹中。它很可能是用如下命令安装的:

composer require symfony/http-foundation

服务器的第二个版本 [date-time-server-2.php] 如下:

<?php

declare(strict_types=1);

// 使用 Symfony 的 [HttpFoundation] 库

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Response;

// 日期函数使用的时区
date_default_timezone_set('Europe/Paris');

// 响应:内容、状态码、HTTP 头
$response = new Response(
    content: date("d/m/y H:i:s", time()),
    status: Response::HTTP_OK,
    headers: ['Content-Type' => 'text/plain'],
);
// 发送的文本采用 UTF-8 编码
$response->setCharset('UTF-8');

// 我们发送响应
$response->send();

说明

  • 第 8 行:加载由 [Composer] 安装的库。脚本位于 [scripts-web/02] 文件夹中:[vendor] 文件夹在其上两级;
  • 第 10 行:[Response] 类位于 [HttpFoundation] 库中,负责处理对 Web 服务客户端的全部响应;
  • 第 16–20 行:创建响应。[Response] 类的构造函数有三个参数:发送给客户端的文档(这里是日期和时间)、响应状态码(这里是常量 [Response::HTTP_OK],其值为 200),以及一个 HTTP 头数组。我们使用 PHP 8.0 的命名参数([content:]、[status:]、[headers:]):它们使调用更易读,并且无需再遵循参数顺序;
  • 第 22 行:响应是 UTF-8 文本。[HttpFoundation] 会添加 [charset=UTF-8] 到头 [Content-Type] 中;
  • 第 25 行:响应被发送给客户端:状态行、头,然后是文档。[send] 方法使用函数 [http_response_code]、[header] 和 [print],这些正是我们自己本来要使用的函数。

使用 [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/02/date-time-server-2.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/plain;charset=UTF-8

01/10/26 17:31:46
  • 第 2 行:响应码 200;
  • 头 [Cache-Control] 是由 [HttpFoundation] 添加的。它表明该响应不得被中间节点(代理)缓存;
  • 头 [Content-Type] 是脚本设置的那个,并补充了字符集;
  • 最后一行是文档。

17.6.4. 客户端脚本——第 2 版

客户端脚本保持不变。只是给它换了一个配置文件 [config-date-time-client-2.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/02/date-time-server-2.php"
}

结果与第 1 版相同:

> php date-time-client.php config-date-time-client-2.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/plain;charset=UTF-8
---Server response: [01/10/26 18:55:26]

17.7. JSON 数据服务器

Web 脚本的响应可以由多个数据元素组成,这些元素可以组织成数组和对象。脚本随后可以把这些不同的元素放在一个 JSON 字符串中发送,由客户端对其解码。

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 03
│           ├── config-json-client.json
│           ├── json-client.php
│           └── Person.php
└── scripts-web
    └── 03
        ├── json-server.php
        └── Person.php

17.7.1. 服务器端脚本

[json-server.php] 脚本使用如下 [Person] 类:

<?php

declare(strict_types=1);

namespace Models;

class Person implements \JsonSerializable
{
    // 带属性提升的构造函数
    // 这些属性可以在任何地方读取,但只能在类内部修改
    public function __construct(
        public private(set) string $lastName = "",
        public private(set) string $firstName = "",
        public private(set) int $age = 0,
    ) {
    }

    // 将关联数组转换为 [Person] 对象
    public static function fromArray(array $assoc): static
    {
        // 数组的键成为构造函数的命名参数
        return new static(...$assoc);
    }

    // 年龄的 setter
    public function setAge(int $age): static
    {
        $this->age = $age;
        return $this;
    }

    // toString
    public function __toString(): string
    {
        return "Person [$this->firstName, $this->lastName, $this->age]";
    }

    // 实现 JsonSerializable 接口
    public function jsonSerialize(): array
    {
        // 我们返回一个关联数组,其键是对象的属性
        // 然后可以将该数组编码为 JSON
        return get_object_vars($this);
    }

    // 将 JSON 字符串转换为 [Person] 对象
    public static function jsonUnserialize(string $json): static
    {
        return static::fromArray(json_decode($json, true, flags: JSON_THROW_ON_ERROR));
    }
}

说明

  • 第 5 行:该类属于 [Models] 命名空间;
  • 第 7 行:该类实现了 PHP 的 [JsonSerializable] 接口。这要求它实现 [jsonSerialize] 方法(第 39–43 行)。该方法必须返回一个将被序列化为 JSON 的值,这里是一个关联数组。当使用表达式 [json_encode($person)] 时,函数 [json_encode] 会检查类 [Person] 是否实现了接口 [JsonSerializable]。如果是,该表达式就变为 [json_encode($person->jsonSerialize())];
  • 第 11–15 行:构造函数使用 PHP 8.0 的属性提升:每个前面带有可见性修饰符的参数都会声明一个属性并对其初始化。三个参数都有默认值;
  • 第 12 行:非对称可见性,随 PHP 8.4 引入:该属性可以从任何地方读取([public]),但只能在类内部修改([private(set)])。因此我们可以写 [$person->lastName] 来读取,无需 getter,但在类外部不能写 [$person->lastName = "x"] 。2019 年的 PHP 7 要求我们声明私有属性,并为每个属性编写一个 getter;
  • 第 19–22 行:基于关联数组创建 [Person] 对象的构造方法(也称为工厂方法)。表达式 [new static(...$assoc)] 将数组的元素传递给构造函数。自 PHP 8.1 起,[...] 运算符接受带字符串键的数组:每个键都成为一个命名参数。因此,[Person::fromArray(["lastName" => "x", "age" => 3])] 等价于 [new Person(lastName: "x", age: 3)]。不是构造函数参数的键会导致错误。该类的 PHP 7 版本把数组元素复制到名称任意的属性中,这可能会创建动态属性——该特性自 PHP 8.2 起已被弃用;
  • 第 26–29 行:该类唯一的 setter。它返回对象本身(返回类型 [static]),从而允许链式调用;
  • 第 43 行:函数 [get_object_vars] 返回对象的关联数组 [property => value];
  • 第 47 行:静态函数 [jsonUnserialize] 可以根据 JSON 字符串创建 [Person] 对象。

脚本 [json-server.php] 如下:

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpFoundation\Response;

// 我们创建一个 Person 对象
$person = new Person(lastName: "de la Hûche", firstName: "jean-paul", age: 27);
// 一个关联数组
$assoc = [
    "attr1" => "value1",
    "attr2" => [
        "firstName" => "Jean-Paul",
        "lastName" => "de la Hûche",
    ],
];
// 响应是一个数组的 JSON 字符串
$response = new Response(
    content: json_encode([$person, $assoc], JSON_THROW_ON_ERROR),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// 发送响应
$response->send();

说明

  • 第 7 行和第 9 行:导入 [Person] 类;
  • 第 13 行:使用命名参数创建一个 [Person] 对象;
  • 第 15–21 行:创建一个两级关联数组;
  • 第 24 行:发送给客户端的文档是数组的 JSON 字符串:
    • 元素 [$person] 将通过其方法 [jsonSerialize] 序列化为 JSON;
    • 元素 [$assoc] 将被原生序列化为 JSON;
    • 选项 [JSON_THROW_ON_ERROR] 使 [json_encode] 在出错时(例如字符串不是 UTF-8 格式)抛出异常,而不是返回 [false];
  • 第 25 行:它指定文档的类型为 [application/json]。收到这个头之后,浏览器会渲染这个 JSON 字符串。

如果使用浏览器(这里是 Chrome)请求这个脚本,会得到如下响应:

Image

请注意带重音字符的编码:默认情况下,[json_encode] 会把所有非 ASCII 字符替换为其 Unicode 序列 [\uXXXX]([û] 变为 [û])。Chrome 中的 [Pretty-print] 字段会显示带缩进的 JSON。使用 [curl]:

> curl -i http://localhost/php8-oct-2026/scripts-web/03/json-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

[{"lastName":"de la H\u00fbche","firstName":"jean-paul","age":27},{"attr1":"value1","attr2":{"firstName":"Jean-Paul","lastName":"de la H\u00fbche"}}]
  • 头 [Content-Type] 将文档类型指定为 [application/json];
  • 最后一行是接收到的 JSON 字符串。

17.7.2. 客户端

客户端 [json-client.php] 由如下 JSON 文件 [config-json-client.json] 配置:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/03/json-server.php"
}

它使用位于其文件夹中的服务器 [Person] 类的一份副本。脚本 [json-client.php] 如下:

<?php

declare(strict_types=1);

// JSON 服务的客户端

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 客户端的配置
const CONFIG_FILE_NAME = "config-json-client.json";

// 获取配置
if (!file_exists(CONFIG_FILE_NAME)) {
    print "The configuration file [" . CONFIG_FILE_NAME . "] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents(CONFIG_FILE_NAME), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [" . CONFIG_FILE_NAME . "]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create();

try {
    // 我们发出请求
    $response = $httpClient->request('GET', $config['url']);
    // 响应的状态
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // 我们获取头部
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // 我们将响应的 JSON 正文取回为 PHP 数组
    [$person, $assoc] = $response->toArray();
    // 我们用属性数组实例化一个人
    $person = Person::fromArray($person);
    // 我们显示服务器的响应
    print "---Server response\n";
    print "$person\n";
    print "array=" . json_encode($assoc, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE) . "\n";
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 9 行和第 11 行:导入 [Person] 类;
  • 第 16 行:该客户端始终使用同一个配置文件,其名称是一个常量;
  • 第 31 行:创建 HTTP 客户端;
  • 第 45 行:响应的 [toArray] 方法对收到的 JSON 文档解码,并返回相应的 PHP 数组。如果文档不是 JSON 类型,它会抛出异常。我们知道被编码的是一个包含两个元素的数组。[[$person, $assoc] = …] 解构赋值(也称为 destructuring)把这两个元素赋给两个变量。它取代了旧的语法 [list($person, $assoc) = …];
  • 第 47 行:根据其属性数组创建一个 [Person] 对象,以便稍后显示(第 50 行)。该对象通过其方法 [__toString] 转换为字符串;
  • 第 51 行:显示第二个关联数组。[print] 语句不能显示数组。因此,这个数组被转换为 JSON 字符串。为了原样保留带重音的字符,必须添加选项 [JSON_UNESCAPED_UNICODE]。我们已经看到,没有这个选项时,带重音的字符会在 JSON 字符串中被编码。

运行客户端脚本得到如下结果:

> php json-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:26 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response
Person [jean-paul, de la Hûche, 27]
array={"attr1":"value1","attr2":{"firstName":"Jean-Paul","lastName":"de la Hûche"}}

在最后两行中,带重音的字符被正确获取。

17.8. 从 Web 服务获取环境变量

服务器端脚本运行在一个它可以访问的 Web 环境中。这个环境存放在数组 [$_SERVER] 中,这是 PHP 的一个超全局变量。如果使用 [HttpFoundation] 库,这个环境位于 [Request] 对象的 [server] 属性中,该对象表示 Web 脚本所处理的 HTTP 请求。

1
2
3
4
5
6
7
8
9
php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 04
│           ├── config-env-client.json
│           └── env-client.php
└── scripts-web
    └── 04
        └── env-server.php

17.8.1. 服务器端脚本

我们要编写一个服务器应用,它把自己的执行环境发送给客户端。Web 脚本 [env-server.php] 如下:

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// 我们获取请求
$request = Request::createFromGlobals();
// 响应是脚本环境的 JSON 字符串
$response = new Response(
    content: json_encode($request->server->all(), JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');
// 发送响应
$response->send();
  • 第 12 行:我们创建一个 [Request] 类型的对象,它封装了 Web 脚本收到的 HTTP 请求的所有可用信息及其执行环境。静态方法 [createFromGlobals] 根据 PHP 的全局变量构造该对象:[$_GET]、[$_POST]、[$_COOKIE]、[$_FILES] 和 [$_SERVER];
  • 第 15 行:发送给客户端的信息是对象 [$request->server] 的 JSON 字符串,它表示 Web 脚本的运行环境。它是 [ServerBag] 类型的对象,是一种字典。[$request->server->all()] 则是一个真正的关联数组——即 [ServerBag] 的内容。如果没有 [HttpFoundation],我们会写 [json_encode($_SERVER)]。[JSON_UNESCAPED_SLASHES] 选项可防止路径中的 [/] 字符被编码为 [\/];
  • 第 20 行:发送响应。

如果使用浏览器请求这个脚本,它会显示环境变量的 JSON 字典。

17.8.2. 客户端脚本

客户端脚本 [env-client.php] 由如下 JSON 文件 [config-env-client.json] 配置:

{
    "url": "http://localhost/php8-oct-2026/scripts-web/04/env-server.php",
    "display": [
        "HTTP_HOST", "HTTP_USER_AGENT", "HTTP_ACCEPT_ENCODING",
        "SERVER_SOFTWARE", "SERVER_NAME", "SERVER_ADDR", "SERVER_PORT",
        "REMOTE_ADDR", "REMOTE_PORT", "REQUEST_SCHEME", "SERVER_ADMIN",
        "SCRIPT_FILENAME", "SERVER_PROTOCOL", "REQUEST_METHOD", "QUERY_STRING",
        "REQUEST_URI", "SCRIPT_NAME", "PHP_SELF", "REQUEST_TIME_FLOAT"
    ]
}
  • 第 2 行:服务器脚本的 URL;
  • 第 3–9 行:客户端将显示的环境变量的名称。没有这个键时,它会显示所有变量。

客户端脚本 [env-client.php] 如下:

<?php

declare(strict_types=1);

// 服务器脚本的环境

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 客户端的配置
const CONFIG_FILE_NAME = "config-env-client.json";

// 获取配置
if (!file_exists(CONFIG_FILE_NAME)) {
    print "The configuration file [" . CONFIG_FILE_NAME . "] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents(CONFIG_FILE_NAME), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [" . CONFIG_FILE_NAME . "]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create();
try {
    // 我们向服务器发出请求
    $response = $httpClient->request('GET', $config['url']);
    // 响应的状态
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // 我们获取头部
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // 我们显示服务器的响应
    print "---Server response\n";
    $env = $response->toArray();
    // 我们只保留配置中列出的变量(如果没有列表,则保留全部)
    if (isset($config['display'])) {
        $env = array_filter($env, fn(string $key): bool => in_array($key, $config['display'], true), ARRAY_FILTER_USE_KEY);
    }
    foreach ($env as $key => $value) {
        print "[$key]=>$value\n";
    }
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 43 行:对服务器的 JSON 响应进行解码。得到一个关联数组;
  • 第 45–46 行:环境信息很长。如果配置文件包含变量名列表([display]),则只保留这些名称。函数 [array_filter] 保留关联数组中那些使作为参数传入的函数返回 [true] 的元素。使用选项 [ARRAY_FILTER_USE_KEY] 时,该函数接收的是元素的键而不是值;
  • 第 48–49 行:显示这个关联数组的所有值。

得到如下控制台输出([php8-oct-2026] 文件夹的路径被缩写为 [.../php8-oct-2026]):

> php env-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 15:31:46 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response
[HTTP_HOST]=>localhost
[HTTP_USER_AGENT]=>Symfony HttpClient (Curl)
[HTTP_ACCEPT_ENCODING]=>gzip
[SERVER_SOFTWARE]=>Apache/2.4.58 (Ubuntu)
[SERVER_NAME]=>localhost
[SERVER_ADDR]=>127.0.0.1
[SERVER_PORT]=>80
[REMOTE_ADDR]=>127.0.0.1
[REQUEST_SCHEME]=>http
[SERVER_ADMIN]=>webmaster@localhost
[SCRIPT_FILENAME]=>.../php8-oct-2026/scripts-web/04/env-server.php
[REMOTE_PORT]=>54922
[SERVER_PROTOCOL]=>HTTP/1.1
[REQUEST_METHOD]=>GET
[QUERY_STRING]=>
[REQUEST_URI]=>/php8-oct-2026/scripts-web/04/env-server.php
[SCRIPT_NAME]=>/php8-oct-2026/scripts-web/04/env-server.php
[PHP_SELF]=>/php8-oct-2026/scripts-web/04/env-server.php
[REQUEST_TIME_FLOAT]=>1790868706.5464

下面是这些变量以及服务器还发送的其他几个变量的含义:

变量
含义
HTTP_HOST
客户端发送的 HTTP 头 [Host: xxx] 的值“xxx”
HTTP_USER_AGENT
客户端发送的 HTTP 头 [User-Agent: xxx] 的值 xxx
HTTP_ACCEPT_ENCODING
客户端发送的 HTTP 头 [Accept-Encoding: xxx] 的值 xxx
PATH
运行服务器脚本的机器上可执行文件的路径
SERVER_SIGNATURE
Web 服务器的签名,由 [Apache] 添加到它自己生成的页面(错误页面、文件列表)中
SERVER_SOFTWARE
Web 服务器的类型
SERVER_NAME
Web 服务器的主机名
SERVER_PORT
Web 服务器的监听端口
SERVER_ADDR
Web 服务器所在机器的 IP 地址
REMOTE_ADDR
客户端的 IP 地址。在这里,客户端与服务器在同一台机器上
REMOTE_PORT
客户端发出请求所使用的端口
DOCUMENT_ROOT
Web 服务器所提供文档的目录树的根目录,在 [<laragon>/www] 中,同 [Laragon]
REQUEST_SCHEME
所请求 URL 的协议:[http] 或 [https]
SERVER_ADMIN
Web 服务器管理员的电子邮件地址
SCRIPT_FILENAME
服务器脚本的完整路径
SERVER_PROTOCOL
Web 服务器使用的 HTTP 协议版本
REQUEST_METHOD
客户端使用的 HTTP 方法:GET、POST、PUT、DELETE……
QUERY_STRING
URL 中发送的参数:GET /url?parameters
REQUEST_URI
客户端请求的 URL。如果客户端请求 URL [http://machine:port/uri],则 REQUEST_URI=/uri
SCRIPT_NAME
脚本相对于服务器根目录的路径:[$_SERVER['SCRIPT_FILENAME']] = [$_SERVER['DOCUMENT_ROOT'] . $_SERVER['SCRIPT_NAME']]
REQUEST_TIME_FLOAT
请求的时间,以自 1970 年 1 月 1 日以来的秒数表示,精度为微秒

17.9. 服务器获取客户端发送的参数

17.9.1. 简介

在 HTTP 协议中,客户端有两种方法向 Web 服务器传递参数:

  • 它以如下形式请求服务的 URL
GET url?param1=val1&param2=val2&param3=val3… HTTP/1.1

其中的 [vali] 值必须事先编码,使某些保留字符被替换为它们的十六进制值;

  • 它以如下形式请求服务的 URL
POST url HTTP/1.1

然后在发送给服务器的 HTTP 头中,包含如下头:

Content-Length: N

客户端发送的其余头以一个空行结束。然后客户端可以按如下形式发送其数据

param1=val1&param2=val2&param3=val3…

其中的值 [vali] 与 GET 方法一样,必须事先编码。发送给服务器的字节数必须是 N,其中 N 是 [Content-Length] 头中声明的值。

Web 服务的 PHP 脚本要获取客户端发送的 [parami] 参数,需从下列数组中取得它们的值:

  • [$_GET['parami']] 用于 URL 的参数;
  • [$_POST['parami']] 用于 POST 命令的文档中发送的参数;

这适用于 PHP 的基本函数。如果使用 [HttpFoundation] 库,这些参数位于:

  • [$request->query->get('parami')] 用于 URL 的参数;
  • [$request->request->get('parami')] 用于与 POST 命令相关联的文档的参数;

其中 [$request] 是 [Request] 对象,它表示 Web 脚本所收到请求的全部信息。

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 05
│           ├── config-parameters-client.json
│           ├── config-spy.json
│           ├── parameters-get-client-2.php
│           ├── parameters-get-client.php
│           ├── parameters-mixed-get-client.php
│           ├── parameters-mixed-post-client.php
│           └── parameters-post-client.php
└── scripts-web
    └── 05
        ├── parameters-server-native.php
        └── parameters-server.php

17.9.2. GET 客户端——第 1 版

客户端脚本由如下 JSON 文件 [config-parameters-client.json] 配置:

1
2
3
4
{
    "url-get": "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php",
    "url-post": "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php"
}
  • 第 2 行:GET 客户端所针对的 Web 脚本的 URL;
  • 第 3 行:POST 客户端所针对的 Web 脚本的 URL。

客户端向服务器发送三个参数 [firstName, lastName, age]。客户端 [parameters-get-client.php] 如下:

<?php

declare(strict_types=1);

// Web 服务器的 GET 客户端 - 参数由脚本编码

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 配置文件:命令行的第 1 个参数(如果存在)
$configFileName = $argv[1] ?? "config-parameters-client.json";

// 获取配置
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create();

try {
    // 要发送的参数
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // 我们对参数进行编码
    $parameters = "firstName=" . urlencode($firstName)
        . "&lastName=" . urlencode($lastName)
        . "&age=$age";
    // 我们发出请求
    $response = $httpClient->request("GET", $config["url-get"] . "?$parameters");
    // 响应的状态
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // 我们获取头部
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // 我们显示服务器的响应
    print "---Server response [{$response->getContent()}]\n";
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 14 行:与日期/时间客户端一样,配置文件的名称可以作为参数传入;
  • 第 33 行:通过解包数组来为这三个参数赋值;
  • 第 35–37 行:对发送给服务器的参数进行编码。参数 [$firstName] 和 [$lastName]可以包含任意字符,使用函数 [urlencode] 对它们编码:除 ASCII 字母和数字以及字符 [-_.] 之外的所有字符都被替换为 [%xx],其中 [xx] 是该字节的十六进制值;UTF-8 字符([û])用两个字节编码,因此变为 [%C3%BB]。空格被替换为字符 [+];
  • 第 39 行:所请求的 URL 是 [URL?parameters],其中 [parameters] 的形式为 [firstName=val1&lastName=val2&age=val3];
  • 第 49 行:客户端只是简单地显示服务器的响应。

注意:PHP 的 [http_build_query] 函数可以根据关联数组构造同样的字符串:[http_build_query(["firstName" => $firstName, "lastName" => $lastName, "age" => $age])]。

你可能想看看,当发送一个已配置的 GET 请求时,服务器收到了什么。为此,我们在打开了 [spy-server.php] 嗅探服务器所在目录 [web-clients/02] 的终端窗口中,在 100 端口上启动我们的嗅探服务器:

php spy-server.php 100

文件 [config-spy.json] 为 GET 和 POST 客户端指定了这个服务器:

1
2
3
4
{
    "url-get": "http://localhost:100/php8-oct-2026/scripts-web/05/parameters-server.php",
    "url-post": "http://localhost:100/php8-oct-2026/scripts-web/05/parameters-server.php"
}

我们使用命令 [php parameters-get-client.php config-spy.json] 运行客户端。间谍服务器显示如下信息:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34944
--- lines received
GET /php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45 HTTP/1.1
Host: localhost:100
Accept: */*
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • 第 5 行:客户端发送的已配置的 GET 命令。某些字符的编码清晰可见。

17.9.3. GET / POST 服务器

服务器脚本 [parameters-server.php] 如下:

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// 我们获取请求
$request = Request::createFromGlobals();
// 我们获取请求的参数
$getParameters = $request->query->all();
$bodyParameters = $request->request->all();

// 响应:以 JSON 编码的数组
$response = new Response(
    content: json_encode([
        "method" => $request->getMethod(),
        "uri" => $request->getRequestUri(),
        "getParameters" => $getParameters,
        "bodyParameters" => $bodyParameters,
    ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');
// 发送响应
$response->send();

说明

  • 第 12 行:根据 Web 脚本创建 [Request] 对象。该对象封装了 Web 脚本从客户端收到的所有信息;
  • 第 14 行:[$request->query] 对象的类型是 [InputBag] ,包含 URL 的参数。表达式 [$request->query->get('X')] 从 [firstName=val1&lastName=val2&age=val3] 参数中获取名为 X 的参数。表达式 [$request->query->all()] 获取所有这些参数组成的数组;
  • 第 15 行:对象 [$request->request] 的类型同样是 [InputBag],它收集客户端文档中发送的参数。这些参数也称为“已提交的(posted)”参数。表达式 [$request->request->get('X')] 返回名为 X 的已提交参数,表达式 [$request->request->all()] 返回所有已提交参数组成的数组;
  • 第 20–23 行:服务器向客户端返回它收到的所有参数、客户端所用的 [GET / POST / …] 方法(通过 [$request->getMethod()] 获得)以及所请求的 URI(通过 [$request->getRequestUri()] 获得)。发送给客户端的文档是一个关联数组的 JSON 字符串,其中一些值本身也是关联数组。选项 [JSON_UNESCAPED_UNICODE] 指定 Unicode 字符(例如带重音的字符)按原样发送,不进行编码;
  • 第 25 行:通知客户端将要发送的是 JSON;
  • 第 29 行:响应被发送给客户端。

使用默认配置运行客户端脚本 [parameters-get-client.php] ,得到如下结果:

> php parameters-get-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}]
  • 最后一行:
    • [method]:方法是 GET;
    • [uri]:GET 请求中经 URL 编码的参数在所请求的 URI 中清晰可见;
    • [getParameters]:来自 URL 的参数数组,已由 PHP 解码;
    • [bodyParameters]:已提交参数的数组;它是空的。

也可以用 [curl] 测试服务器。URL 两侧的引号是必需的,因为字符 [&] 对命令解释器有特殊含义:

> curl -i "http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45"
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}

17.9.3.1. 不使用 HttpFoundation 的版本

脚本 [parameters-server-native.php] 仅使用 PHP 的函数完成同样的任务:

<?php

declare(strict_types=1);

// 与 [parameters-server.php] 相同,但只使用 PHP 自身的函数

// 一个特定的、经过过滤的参数:GET 参数 [age] 必须是整数
// 参数缺失时 filter_input 返回 null,参数无效时返回 false
$age = filter_input(INPUT_GET, 'age', FILTER_VALIDATE_INT);

// 响应是 JSON
header('Content-Type: application/json');
print json_encode([
    "method" => $_SERVER['REQUEST_METHOD'],
    "uri" => $_SERVER['REQUEST_URI'],
    "getParameters" => $_GET,
    "bodyParameters" => $_POST,
    "age" => $age,
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
  • 第 8 行:数组 [$_GET] 和 [$_POST] 包含的是字符串,无论期望的值是什么类型。[filter_input] 函数读取一个参数并对其进行验证:这里,URL 的 [age] 参数([INPUT_GET])必须是整数([FILTER_VALIDATE_INT])。如果参数有效,它返回该整数;如果无效,返回 [false] ;如果缺失,则返回 [null];
  • 第 12 行:响应中的 [Content-Type] 头;
  • 第 14 行:请求中的 HTTP 方法;
  • 第 15 行:所请求的 URI;
  • 第 16 和 17 行:URL 的参数和文档的参数。

使用 [curl] 发出的两个请求:

> curl "http://localhost/php8-oct-2026/scripts-web/05/parameters-server-native.php?firstName=jean-paul&age=45"
{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server-native.php?firstName=jean-paul&age=45","getParameters":{"firstName":"jean-paul","age":"45"},"bodyParameters":[],"age":45}
> curl -d firstName=jean-paul "http://localhost/php8-oct-2026/scripts-web/05/parameters-server-native.php?age=4x"
{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server-native.php?age=4x","getParameters":{"age":"4x"},"bodyParameters":{"firstName":"jean-paul"},"age":false}
  • 在第一个请求中,参数 [age] 为 [45]:它被表示为整数 45,而不是字符串 ["45"];
  • 在第二个请求中,选项 [-d] 使该请求以 POST 方式发出:参数 [firstName] 位于 [$_POST] 中,而来自 URL 的参数 [age] 位于 [$_GET] 中。它的值 [4x]不是整数:[filter_input] 的结果为 [false]。

在本课程的其余部分,我们将使用 [HttpFoundation],它的代码更加一致。但了解其背后的原理也是有益的。

17.9.4. GET 客户端——第 2 版

在客户端脚本的上一版本中,出于教学目的,我们自己对发送给服务器的参数进行了 URL 编码。[HttpClient] 对象可以自行完成这项工作。这就是 [parameters-get-client-2.php] 脚本,除了下面几行之外,它与上一个脚本完全相同:

try {
    // 要发送的参数
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // 我们向服务器发出请求
    $response = $httpClient->request("GET", $config["url-get"], [
        // URL 的参数(查询字符串)
        "query" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
    ]);
  • 第 37–41 行:[request] 方法的第三个参数是一个选项数组。[query] 选项是要添加到 URL 的参数数组。[HttpClient] 对象自行负责它们的编码。

结果:

> php parameters-get-client-2.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName=jean-paul&lastName=de%20la%20h%C3%BBche&age=45","getParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"},"bodyParameters":[]}]
  • 最后一行:请注意,[HttpClient] 使用 [%20] 而不是 [+] 对空格进行编码。PHP 接受这两种编码。

17.9.5. POST 客户端

HTTP 客户端向 Web 服务器发送如下文本序列:HTTP 头、空行、文档。在前面的客户端中,这个序列如下:

1
2
3
GET /url?parameters HTTP/1.1
… other HTTP headers
empty line

当时没有文档。还有另一种传递参数的方式,称为 POST 方法。在这种情况下,发送给 Web 服务器的文本序列如下:

1
2
3
4
POST /url HTTP/1.1
… other HTTP headers
empty line
parameters

这一次,在 GET 客户端中包含在请求第一行里的参数,在 POST 客户端中成为头之后所发送文档的一部分。

POST 客户端的脚本 [parameters-post-client.php] 与 GET 客户端(第 2 版)相比,只有下面几行不同:

try {
    // 要发送的参数
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // 我们向服务器发出请求
    $response = $httpClient->request("POST", $config["url-post"], [
        // 文档的参数(请求体)
        "body" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
    ]);
  • 第 35 行:我们现在发出的是 POST 类型的 HTTP 请求;
  • 第 37–41 行:选项 [body] 是 POST 请求的主体:这是客户端发送给服务器的文档。当这个选项是数组时,[HttpClient] 会对其进行 URL 编码,并添加头 [Content-Type: application/x-www-form-urlencoded]。这里发送了三个参数:[firstName, lastName, age]。

执行客户端脚本的结果如下:

> php parameters-post-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php","getParameters":[],"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}]
  • 最后一行:方法是 [POST] ,参数的类型是 [bodyParameters]。没有 [getParameters] 参数,正如 [uri] 所示。

使用 [curl] 时,[-d] 选项通过 POST 请求发送参数,[--data-urlencode] 选项做同样的事,并对其值进行 URL 编码:

> curl -i -d firstName=jean-paul --data-urlencode "lastName=de la hûche" -d age=45 http://localhost/php8-oct-2026/scripts-web/05/parameters-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php","getParameters":[],"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}

让我们看看服务器在 POST 请求期间收到了什么。我们在 100 端口上重新启动间谍服务器,并使用 [php parameters-post-client.php config-spy.json] 命令运行客户端。间谍服务器显示如下信息:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34950
--- lines received
POST /php8-oct-2026/scripts-web/05/parameters-server.php HTTP/1.1
Host: localhost:100
Accept: */*
Content-Type: application/x-www-form-urlencoded
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip
Content-Length: 52

firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45
--- end of the communication
  • 第 5 行:POST 命令;
  • 第 8 行:HTTP 头 [Content-Type] 指定客户端所发送文档的类型。类型 [application/x-www-form-urlencoded] 表示经 URL 编码的文本;
  • 第 11 行:HTTP 头 [Content-Length] 指定客户端将发送给服务器的文档的字节数;
  • 第 12 行:空行,标志着 HTTP 头的结束和 52 字节文档的开始;
  • 第 13 行:文档:经 URL 编码的参数字符串。读者可以验证它确实有 52 个字符。

17.9.6. 混合式 POST 客户端

在 POST 中,可以把编码在 URL 中的参数与编码在客户端于 HTTP 头之后发送的文档中的参数混合使用。下面是一个 [parameters-mixed-post-client.php] 的示例:

try {
    // 要发送的参数
    [$firstName, $lastName, $age] = ["jean-paul", "de la hûche", 45];
    // 我们向服务器发出请求
    $response = $httpClient->request("POST", $config["url-post"], [
        // 文档的参数(请求体)
        "body" => [
            "firstName" => $firstName,
            "lastName" => $lastName,
            "age" => $age,
        ],
        // URL 的参数(查询字符串)
        "query" => [
            "firstName2" => $firstName,
            "lastName2" => $lastName,
            "age2" => $age,
        ],
    ]);

说明

  • 第 35 行:一个 POST 请求;
  • 第 37–41 行:请求主体(文档)中经 URL 编码的参数;
  • 第 43–47 行:URL 中经 URL 编码的参数。

执行时会产生如下控制台输出:

> php parameters-mixed-post-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"POST","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45","getParameters":{"firstName2":"jean-paul","lastName2":"de la hûche","age2":"45"},"bodyParameters":{"firstName":"jean-paul","lastName":"de la hûche","age":"45"}}]
  • 最后一行:可以看到服务器能够获取这两种类型的参数。

17.9.7. 混合式 GET 客户端

我们来尝试用 GET 请求做同样的事情。脚本 [parameters-mixed-get-client.php] 与上一个脚本只有方法不同:

    // 我们向服务器发出请求
    $response = $httpClient->request("GET", $config["url-get"], [

执行时,我们得到如下控制台输出:

> php parameters-mixed-get-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
connection: close
content-type: application/json
---Server response [{"method":"GET","uri":"/php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45","getParameters":{"firstName2":"jean-paul","lastName2":"de la hûche","age2":"45"},"bodyParameters":[]}]
  • 最后一行:可以看到服务器没有处理客户端所发送文档中经 URL 编码的参数。

然而,服务器嗅探器显示客户端确实发送了一个 52 字节的文档:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:34952
--- lines received
GET /php8-oct-2026/scripts-web/05/parameters-server.php?firstName2=jean-paul&lastName2=de%20la%20h%C3%BBche&age2=45 HTTP/1.1
Host: localhost:100
Accept: */*
Content-Type: application/x-www-form-urlencoded
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip
Content-Length: 52

firstName=jean-paul&lastName=de+la+h%C3%BBche&age=45
--- end of the communication

PHP 只有从 POST 请求的文档开始,才会填充数组 [$_POST](因此也才会填充 [HttpFoundation] 和对象 [$request->request])。GET 请求的文档会被忽略。

最后,应该使用哪种方法向服务器发送信息呢?

  • [GET URL?param1=val1&param2=val2&…] 方法使用一个已配置好的 URL,它可以充当链接。这是它的主要优点:用户可以把这样的链接加入书签。它适用于读取数据而不对服务器做任何修改的请求;
  • 在其他应用中,你可能不希望在 URL 中显示发送给服务器的参数。例如出于安全原因:URL 会被保存在浏览器历史记录和服务器日志文件中。在这种情况下,请使用 [POST] 方法,并把经 URL 编码的参数放在发送给服务器的文档中。对于修改服务器上数据的请求,也应使用这种方法。

17.10. Web 会话管理

在前面的客户端/服务器示例中,过程是这样进行的:

  • 客户端打开到 Web 服务器 80 端口的连接;
  • 它发送如下文本序列:HTTP 头、空行、[document];
  • 作为回应,服务器发送一个同类型的序列;
  • 服务器关闭与客户端的连接;
  • 客户端关闭与服务器的连接。

如果同一个客户端不久之后向 Web 服务器发出新的请求,客户端与服务器之间会建立一个新的连接。服务器无法判断来连接的客户端以前是否访问过,还是这是第一次请求。在两次连接之间,服务器会“忘记”它的客户端。因此,HTTP 协议被称为无状态协议。然而,让服务器记住它的客户端是很有用的。例如,如果某个应用是受保护的,客户端会向服务器发送用户名和密码来验证自己的身份。如果服务器在两次连接之间“忘记”了它的客户端,客户端就必须在每次新的连接时重新验证身份,这是不可行的。

为了跟踪客户端,服务器采取如下做法:当客户端第一次发出请求时,服务器在其响应中包含一个标识符,客户端此后在每次请求中都必须把它发送回来。借助这个对每个客户端都唯一的标识符,服务器就能识别客户端。然后,它可以以内存条目的形式为该客户端维护一份记录,该条目与客户端的标识符唯一关联。

从技术上讲,其工作方式如下:

  • 在对新客户端的响应中,服务器包含 HTTP 头 [Set-Cookie: Keyword=Identifier]。它只在第一次请求时这样做;
  • 在后续请求中,客户端会通过 HTTP 头 [Cookie: Keyword=Identifier] 发送其标识符,以便服务器能够识别它。

有人可能会问,服务器如何知道它面对的是新客户端还是回头客。这是由客户端的 HTTP 头中是否存在 HTTP 头 [Cookie] 来表明的。对于新客户端,这个头是缺失的。

某个客户端建立的所有连接统称为一个会话。

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 06
│           ├── config-session-client-07.json
│           ├── config-session-client-native.json
│           ├── config-session-client.json
│           └── session-client.php
└── scripts-web
    ├── 06
    │   ├── phpinfo.php
    │   ├── session-config.php
    │   ├── session-server-native.php
    │   └── session-server.php
    └── 07
        ├── Person.php
        └── session-server.php

17.10.1. 配置文件 [php.ini]

要使会话管理在 PHP 中正常工作,必须确认其配置正确。它的配置文件是 [php.ini]。根据执行环境(控制台、Web)的不同,所使用的 [php.ini] 配置文件可能不同。要确定使用的是哪一个,请运行如下 [phpinfo.php] 脚本:

1
2
3
4
5
6
<?php

declare(strict_types=1);

// 关于运行该脚本的 PHP 解释器的信息
phpinfo();

[phpinfo] 函数提供有关执行该脚本的 PHP 解释器的信息。特别是,在 [Loaded Configuration File] 一行中,它给出所使用的 [php.ini] 配置文件的路径。我们在安装 PHP 时已经在控制台环境中用过这个函数。在 Web 环境中,只需用浏览器请求 URL [http://localhost/php8-oct-2026/scripts-web/06/phpinfo.php] 。使用 [Laragon] 时,[Apache] 服务器所用的 [php.ini] 是所选 PHP 版本文件夹中的那一个([<laragon>/bin/php/<version>/php.ini])。可以通过 [Laragon] 菜单打开它:[PHP / php.ini]。

这个文件包含一个名为 [Session] 的部分。我们不直接复制它,而是用下面的脚本 [session-config.php] 显示我们所关心的各项指令的实际值:

<?php

declare(strict_types=1);

// Web 服务器的 PHP 解释器的会话配置
$config = ini_get_all('session', details: false);
// 我们只显示课程中介绍过的指令
$keys = [
    'session.save_handler', 'session.save_path', 'session.use_strict_mode',
    'session.use_cookies', 'session.use_only_cookies', 'session.name',
    'session.auto_start', 'session.cookie_lifetime', 'session.cookie_path',
    'session.cookie_domain', 'session.cookie_httponly', 'session.cookie_samesite',
    'session.serialize_handler', 'session.gc_probability', 'session.gc_divisor',
    'session.gc_maxlifetime', 'session.cache_limiter', 'session.cache_expire',
    'session.use_trans_sid',
];
header('Content-Type: text/plain; charset=UTF-8');
foreach ($keys as $key) {
    print "$key = " . var_export($config[$key], true) . "\n";
}
  • 第 6 行:[ini_get_all] 函数返回 PHP 某个扩展的配置指令的值——这里是 [session] 扩展。使用 [details: false] 时,我们得到一个数组 [directive => value];
  • 第 19 行:函数 [var_export] 以 PHP 表达式的形式显示一个值。因此空字符串显示为 ['']。

结果:

> curl http://localhost/php8-oct-2026/scripts-web/06/session-config.php
session.save_handler = 'files'
session.save_path = ''
session.use_strict_mode = '0'
session.use_cookies = '1'
session.use_only_cookies = '1'
session.name = 'PHPSESSID'
session.auto_start = '0'
session.cookie_lifetime = '0'
session.cookie_path = '/'
session.cookie_domain = ''
session.cookie_httponly = '0'
session.cookie_samesite = ''
session.serialize_handler = 'php'
session.gc_probability = '1'
session.gc_divisor = '100'
session.gc_maxlifetime = '1440'
session.cache_limiter = 'nocache'
session.cache_expire = '180'
session.use_trans_sid = '0'
  • 第 2 行:客户端会话的数据被保存到文件中;
  • 第 3 行:保存会话数据的文件夹。如果为空,则指系统的临时文件夹。在 [Laragon] 的配置中,它指向一个名为 [Laragon] 的文件夹(形式为 [<laragon>/tmp])。如果这个文件夹不存在,会话管理将无法工作;
  • 第 4 行:在严格模式下,服务器会拒绝任何不是它自己创建的会话 ID。这可以防范所谓的会话固定攻击。建议启用该模式;
  • 第 5–6 行:表示会话 ID 仅通过 HTTP 头 [Set-Cookie]、和 [Cookie] 来管理;
  • 第 7 行:[Set-Cookie] 头的形式将是 [Set-Cookie: PHPSESSID=session_id];
  • 第 8 行:客户端会话不会自动启动。服务器脚本必须使用 [session_start()] 命令显式地请求启动;
  • 第 9 行:会话 Cookie 在客户端浏览器关闭之前一直有效;
  • 第 10 行:会话 Cookie 必须被回传的路径。如果 [session.cookie_path = /xxx],那么浏览器每次请求 [/xxx/yyy/zzz] 类型的 URL 时,都必须回传该 Cookie。这里,路径 [/] 表示对该站点上的任何 URL 都必须回传该 Cookie;
  • 第 12–13 行:Cookie 的 [HttpOnly] 属性使页面上的 JavaScript 代码无法访问它;[SameSite] 属性则阻止它在响应来自其他站点的请求时被发送。这两个属性可保护会话 ID;
  • 第 14 行:会话中的对象必须先序列化,才能存储到文件中。PHP 负责这种序列化和反序列化;
  • 第 15–17 行:每次会话启动时,PHP 都会以 [gc_probability / gc_divisor] 的概率发起一次清理,清除超过 [gc_maxlifetime] 秒的会话文件:不活动时间超过该值的会话将会丢失。

注意:2019 年的 [Session] 部分的 [php.ini] 中包含指令 [session.sid_bits_per_character = 5]。指令 [session.sid_length] 和 [session.sid_bits_per_character] 用于指定会话 ID 的长度和字符集,它们自 PHP 8.4 起已被弃用:PHP 现在使用 32 个字符的十六进制标识符,其安全性已经足够。不应再使用这些指令。

所有这些设置也可以在会话启动时由脚本自行配置,我们将在后面看到。

17.10.2. 示例 1

17.10.2.1. 服务器

会话 ID 的管理对 Web 服务是透明的。这个 ID 由 PHP 管理。Web 服务使用 [session_start()] 语句访问客户端的会话。从那时起,Web 服务就可以通过数组 [$_SESSION] 读写客户端的会话。如果使用 [HttpFoundation] 库,会话则由 [Session] 类型的对象表示。

下面的代码 [session-server.php] 演示了基于会话的三个计数器的管理。每收到一个新请求,Web 脚本就递增这些计数器,并将它们存储在会话中,以便在下一次请求时取回。

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;

// 客户端的会话
$session = new Session();
$session->start();
// 我们在会话中管理三个计数器
if ($session->has("N1")) {
    // 计数器 N1 递增
    $session->set("N1", $session->get("N1") + 1);
} else {
    // 计数器 N1 不在会话中 - 我们创建它
    $session->set("N1", 0);
}
if ($session->has("N2")) {
    // 计数器 N2 递增
    $session->set("N2", $session->get("N2") + 1);
} else {
    // 计数器 N2 不在会话中 - 我们创建它
    $session->set("N2", 10);
}
if ($session->has("N3")) {
    // 计数器 N3 递增
    $session->set("N3", $session->get("N3") + 1);
} else {
    // 计数器 N3 不在会话中 - 我们创建它
    $session->set("N3", 100);
}
// 响应是包含三个计数器的数组的 JSON
$response = new Response(
    content: json_encode([
        "N1" => $session->get("N1"),
        "N2" => $session->get("N2"),
        "N3" => $session->get("N3"),
    ], JSON_THROW_ON_ERROR),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// 发送响应
$response->send();
  • 第 12–13 行:创建并激活一个会话。对象 [Session] 封装了与客户端所发送的会话 Cookie 相对应的会话数据。如果客户端没有发送这样的 Cookie,则 [Session] 中不存储任何数据。Web 脚本会在其第一次响应中包含 HTTP 头 [Set-Cookie: PHPSESSID=xxx]。在后续请求中,客户端会发送 HTTP 头 [Cookie: PHPSESSID=xxx] ,以表明它想使用哪个会话的内容。会话就是客户端的记忆;
  • 第 15–20 行:我们检查会话中是否有名为 [N1] 的键。这将是我们第一个计数器的名称。如果它不存在,就给它赋值 0 并存入会话。如果它存在,我们就:
    • 从会话中取出它;
    • 将其值加 1;
    • 再把它放回会话中;
  • 第 22–34 行:我们对另外两个计数器 N2 和 N3 做同样的处理;
  • 第 37–44 行:响应将是 JSON 字符串,它是一个包含三个计数器的数组;
  • 第 48 行:响应被发送给客户端。在脚本结束时,PHP 会把会话数据保存到会话文件中。

在客户端与服务器的关系中,服务器上客户端会话的管理取决于双方,即客户端和服务器:

  • 服务器负责在客户端第一次请求时向其发送一个标识符;
  • 客户端负责在每次新请求时把这个标识符发送回来。如果它没有这样做,服务器就会认为这是一个新客户端,并为新会话生成一个新的标识符。

结果

我们使用 Web 浏览器作为客户端。默认情况下,浏览器确实会把服务器发给它的会话标识符回传给服务器。随着请求的进行,浏览器会收到服务器发送的三个计数器,并看到它们的值递增。第一次请求得到:

Image

重新加载页面三次(F5)之后,我们得到:

Image

第四次请求表明计数器确实已被递增。计数器的值确实在多次请求之间被保存了下来。

浏览器的开发者工具(F12,[Network] 选项卡)会显示所交换的 HTTP 头。让我们用 [curl] 来检查它们。使用 [-c cookies.txt] 选项时,[curl] 会把从服务器收到的 Cookie 保存到 [cookies.txt] 文件中;使用 [-b cookies.txt] 选项时,它会把该文件中的 Cookie 发送回服务器。这样它的行为就像浏览器一样。第一次请求:

> curl -i -c cookies.txt -b cookies.txt http://localhost/php8-oct-2026/scripts-web/06/session-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Set-Cookie: PHPSESSID=403de000aa6b2ee9ad770f2a00ffb773; path=/
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"N1":0,"N2":10,"N3":100}
  • 头 [Set-Cookie] 包含服务器在对客户端第一次请求的响应中发送的会话 ID;
  • 第一个头 [Cache-Control] 是由 [HttpFoundation] 在会话开始时设置的:这个专属于该客户端的响应不得被中间节点缓存([private]),并且必须重新向服务器请求([max-age=0]);
  • 最后一行包含三个已初始化的计数器。

文件 [cookies.txt] 现在包含会话 Cookie:

1
2
3
4
5
6
> type cookies.txt
# Netscape HTTP Cookie File
# https://curl.se/docs/http-cookies.html
# This file was generated by libcurl! Edit at your own risk.

localhost    FALSE    /    FALSE    0    PHPSESSID    403de000aa6b2ee9ad770f2a00ffb773

第 2 次请求:

> curl -i -c cookies.txt -b cookies.txt http://localhost/php8-oct-2026/scripts-web/06/session-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: max-age=0, private, must-revalidate
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json

{"N1":1,"N2":11,"N3":101}
  • [curl] 通过 HTTP 头 [Cookie: PHPSESSID=…] 回传了会话 ID;
  • 在其响应中,Web 服务不再包含 [Set-Cookie] 头。现在由客户端负责在每次请求中发送该标识符;
  • 最后一行:计数器已被递增。

17.10.2.2. 客户端

现在我们基于前面的服务器端脚本编写一个客户端脚本。在管理会话方面,它的行为必须像 Web 浏览器一样:

  • 在服务器对其第一次请求的响应中,它必须找到服务器发给它的会话 ID。它知道可以在 HTTP 头 [Set-Cookie] 中找到它;
  • 在随后的每次请求中,它都必须把收到的会话 ID 发送回服务器。它将使用 HTTP 头 [Cookie] 来完成。

客户端 [session-client.php] 由如下 JSON 文件 [config-session-client.json] 配置:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/06/session-server.php"
}

客户端 [session-client.php] 的代码如下:

<?php

declare(strict_types=1);

// 带会话的 Web 服务客户端

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 配置文件:命令行的第 1 个参数(如果存在)
$configFileName = $argv[1] ?? "config-session-client.json";

// 获取配置
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create();
// 会话 Cookie(尚未获得)
$sessionCookie = null;
try {
    // 我们将发出 10 个请求
    for ($i = 0; $i < 10; $i++) {
        // 我们向服务器发出请求
        if ($sessionCookie === null) {
            // 不带会话 Cookie
            $response = $httpClient->request('GET', $config['url']);
        } else {
            // 带会话 Cookie
            $response = $httpClient->request('GET', $config['url'], [
                'headers' => ['Cookie' => $sessionCookie],
            ]);
        }
        // 响应的状态
        $statusCode = $response->getStatusCode();
        print "---Response with status: $statusCode\n";
        // 我们获取头部
        print "---Headers of the response\n";
        $headers = $response->getHeaders();
        foreach ($headers as $name => $values) {
            print "$name: $values[0]\n";
        }
        // 我们在 [Set-Cookie] 头中查找会话 Cookie
        foreach ($headers['set-cookie'] ?? [] as $cookie) {
            if (preg_match('/^PHPSESSID=(.+?);/', $cookie, $fields)) {
                $sessionCookie = "PHPSESSID=$fields[1]";
            }
        }
    }
    // 我们显示服务器最后一个 JSON 响应
    print "---Server response: {$response->getContent()}\n";
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 29 行:创建 HTTP 客户端;
  • 第 31 行:变量 [$sessionCookie] 将包含会话 Cookie,形式为 [PHPSESSID=xxx]。在服务器发送它之前,其值为 [null];
  • 第 34 行:我们将向服务器发送 10 次相同的请求:[session-server.php];
  • 第 36–38 行:如果会话 Cookie 尚未获知,我们发送不带 [GET] 头 [Cookie] 的命令;
  • 第 39–43 行:否则,我们发送带有 [GET] 头 [Cookie] 的命令。[request] 方法的 [headers] 选项是要添加到请求中的 HTTP 头数组;
  • 第 55 行:Web 服务器可能发送多个 [Set-Cookie] 头。会话 Cookie 只是其中之一。它的格式是唯一的:[PHPSESSID=xxx; …]。如果响应中没有 [Set-Cookie] 头,表达式 [$headers['set-cookie'] ?? []] 会返回一个空数组,循环什么也不做;
  • 第 56 行:使用正则表达式查找会话 Cookie;
  • 第 62 行:10 次请求完成后,显示服务器的最后一个响应(JSON)。

注意:Symfony 客户端 [HttpClient] 不会自行在请求之间管理 Cookie,这就是为什么要包含这段代码。会话 Cookie 的管理将在使用会话的税额计算应用版本中处理。

结果

运行客户端脚本产生如下输出(我们只显示开头和结尾):

> php session-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
set-cookie: PHPSESSID=2dd2d2c53266ff4fb3eff4b943564f74; path=/
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Server response: {"N1":9,"N2":19,"N3":109}
  • 在第一次响应中,服务器发送会话 ID(头 [set-cookie])。在后续响应中,它不再发送;
  • 最后一行:三个计数器 [N1, N2, N3] 确实被递增了 9 次。它们是在第 1 次请求时被初始化的。

17.10.2.3. 不使用 HttpFoundation 的版本

脚本 [session-server-native.php] 仅使用 PHP 的函数完成同样的任务:

<?php

declare(strict_types=1);

// 与 [session-server.php] 相同,但只使用 PHP 自身的函数

// 启动会话 - 这些选项会覆盖 php.ini 中的 [session.*] 指令
session_start([
    // 我们拒绝服务器并非自己创建的会话 id
    'use_strict_mode' => true,
    // 浏览器的 JavaScript 无法访问会话 Cookie
    'cookie_httponly' => true,
    // 来自其他站点的请求不会携带该 Cookie
    'cookie_samesite' => 'Lax',
]);
// 三个计数器及其初始值
foreach (["N1" => 0, "N2" => 10, "N3" => 100] as $counter => $initialValue) {
    // 如果计数器在会话中则递增,否则创建
    $_SESSION[$counter] = isset($_SESSION[$counter]) ? $_SESSION[$counter] + 1 : $initialValue;
}
// 响应是包含三个计数器的数组的 JSON
header('Content-Type: application/json');
print json_encode([
    "N1" => $_SESSION["N1"],
    "N2" => $_SESSION["N2"],
    "N3" => $_SESSION["N3"],
], JSON_THROW_ON_ERROR);
  • 第 8–15 行:会话启动。从 PHP 7.0 开始,[session_start] 函数接受一个选项数组:这些是 [session.*] 指令,来自 [php.ini] 文件,去掉了它们的 [session.] 前缀。它们只对当前请求生效。这里,我们启用严格模式以及会话 Cookie 的 [HttpOnly] 和 [SameSite] 属性,如在 [php.ini] 文件一节中所述;
  • 第 17–19 行:我们遍历数组 [counter => initial value]。对于每个计数器,如果它在会话 [$_SESSION] 中,就将其递增;否则,就以其初始值把它加入会话;
  • 第 22 行:响应的 [Content-Type] 头;
  • 第 23 行:发送给客户端的 JSON 文档。

我们使用配置 [config-session-client-native.json] 运行同一个客户端,该配置指向这个脚本:[php session-client.php config-session-client-native.json]。显示的开头部分:

> php session-client.php config-session-client-native.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
set-cookie: PHPSESSID=f2bf0d3a4e234d04ccc9e8900a2f83be; path=/; HttpOnly; SameSite=Lax
expires: Thu, 19 Nov 1981 08:52:00 GMT
cache-control: no-store, no-cache, must-revalidate
pragma: no-cache
content-length: 25
content-type: application/json
  • 会话 Cookie 现在带有属性 [HttpOnly] 和 [SameSite=Lax];
  • PHP 在会话开始时设置的头 [Expires]、[Cache-Control] 和 [Pragma],可防止响应被缓存(指令 [session.cache_limiter = nocache])。

显示的最后一行与之前相同:

---Server response: {"N1":9,"N2":19,"N3":109}

17.10.3. 示例 2

17.10.3.1. 服务器

下面的示例表明,也可以把数组或对象的值保存到会话中。我们将把一个 [Person] 对象放入会话。[scripts-web/07] 文件夹中的 [Person] 类与 [scripts-web/03] 文件夹中 JSON 示例里的那个类相同。

文件夹 [scripts-web/07] 中的服务器脚本 [session-server.php] 如下:

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';
// [Person] 类必须在会话启动之前就已知
require_once __DIR__ . '/Person.php';

use Models\Person;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\Session\Session;

// 客户端的会话
$session = new Session();
$session->start();

// 我们在会话中管理各种数据
// 一个数组
if ($session->has("array")) {
    // 该数组在会话中 - 我们将其所有值递增
    $array = array_map(fn(int $value): int => $value + 1, $session->get("array"));
} else {
    // 该数组不在会话中 - 我们创建它
    $array = [0, 10, 100];
}
// 我们把该数组放入会话
$session->set("array", $array);

// 一个字典
if ($session->has("assoc")) {
    // [assoc] 在会话中 - 我们将其所有元素递增
    $assoc = $session->get("assoc");
    foreach ($assoc as $key => $value) {
        $assoc[$key] = $value + 1;
    }
} else {
    // [assoc] 不在会话中 - 我们创建它
    $assoc = ["one" => 0, "two" => 10, "three" => 100];
}
// 我们把 [assoc] 放入会话
$session->set("assoc", $assoc);

// 一个 Person 对象
if ($session->has("person")) {
    // [person] 在会话中 - 我们增加其年龄
    $person = $session->get("person");
    $person->setAge($person->age + 1);
} else {
    // [person] 不在会话中 - 我们创建它
    $person = new Person(firstName: "Léonard", lastName: "Hûche", age: 0);
    // 我们把 [person] 放入会话
    $session->set("person", $person);
}

// 响应是 JSON
$response = new Response(
    content: json_encode([
        "array" => $array,
        "assoc" => $assoc,
        "person" => $person,
    ], JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE),
    headers: ['Content-Type' => 'application/json'],
);
$response->setCharset('UTF-8');

// 发送响应
$response->send();

说明

  • 第 8 行:[Person] 类必须在会话启动之前加载:启动时,PHP 会对先前请求中放入会话的对象进行反序列化,因此它必须知道这些对象的类;
  • 第 15–16 行:获取并激活当前会话;
  • 第 20–28 行:我们管理一个已放入会话的数组 [array] 。每收到一个新请求,其元素就加 1。函数 [array_map] 对数组的每个元素应用一个函数,并返回结果数组。这里的函数是一个箭头函数,随 PHP 7.4 引入:[fn(int $value): int => $value + 1];
  • 第 31–42 行:我们管理一个会话范围内的关联数组 [assoc] 。每收到一个新请求,其元素就加 1;
  • 第 45–53 行:我们管理一个会话范围内的 [Person] 对象。每收到一个新请求,这个人的年龄就加 1。请注意,修改对象之后并不需要把它再放回会话中:会话中包含的是对该对象的引用,脚本结束时保存的就是被修改后的对象;
  • 第 57–64 行:我们向客户端发送一个 JSON 响应:一个关联数组的 JSON 字符串。

让我们用浏览器请求这个脚本。前两次请求返回如下结果(第二次在浏览器中按 F5):

Image

Image

可以看到,在第二次请求时,所有计数器都已递增。

17.10.3.2. 客户端

客户端与示例 1 中的相同。我们只为它提供配置文件 [config-session-client-07.json]:

1
2
3
{
    "url": "http://localhost/php8-oct-2026/scripts-web/07/session-server.php"
}

执行命令 [php session-client.php config-session-client-07.json] 产生如下结果(开头和结尾):

> php session-client.php config-session-client-07.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
set-cookie: PHPSESSID=f5aad2acfda0f0a514b4134ffdc9e066; path=/
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: max-age=0, private, must-revalidate
connection: close
content-type: application/json
---Server response: {"array":[9,19,109],"assoc":{"one":9,"two":19,"three":109},"person":{"lastName":"Hûche","firstName":"Léonard","age":9}}
  • 最后一行:可以看到所有计数器都已被递增 9 次。

17.11. 身份验证

我们现在来关注仅面向特定用户的 Web 服务。客户端必须先向 Web 服务进行身份验证,才能收到响应。

php8-oct-2026
├── scripts-console
│   └── web-clients
│       └── 08
│           ├── auth-client.php
│           ├── config-auth-client-https.json
│           ├── config-auth-client-https-verify.json
│           ├── config-auth-client-ko.json
│           ├── config-auth-client.json
│           └── config-spy.json
└── scripts-web
    └── 08
        └── auth-server.php

17.11.1. 客户端

客户端 [auth-client.php] 由如下 JSON 文件 [config-auth-client.json] 配置:

1
2
3
4
5
{
    "url": "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}
  • 第 2 行:Web 服务的 URL;
  • 第 3–4 行:用户凭据。

客户端代码 [auth-client.php] 如下:

<?php

declare(strict_types=1);

// 带身份验证的 Web 服务客户端

// 依赖
require_once __DIR__ . '/../../../vendor/autoload.php';

use Symfony\Component\HttpClient\HttpClient;
use Symfony\Contracts\HttpClient\Exception\ExceptionInterface;

// 配置文件:命令行的第 1 个参数(如果存在)
$configFileName = $argv[1] ?? "config-auth-client.json";

// 获取配置
if (!file_exists($configFileName)) {
    print "The configuration file [$configFileName] does not exist\n";
    exit(1);
}
try {
    $config = json_decode(file_get_contents($configFileName), true, flags: JSON_THROW_ON_ERROR);
} catch (JsonException $ex) {
    print "Error while using the JSON configuration file [$configFileName]: {$ex->getMessage()}\n";
    exit(1);
}

// 我们创建一个 HTTP 客户端
$httpClient = HttpClient::create([
    // 用户的凭据
    'auth_basic' => [$config['user'], $config['password']],
    // 是否应检查服务器证书 (HTTPS)?默认检查
    'verify_peer' => $config['verify_peer'] ?? true,
    'verify_host' => $config['verify_host'] ?? true,
]);

try {
    // 我们向服务器发出请求
    $response = $httpClient->request('GET', $config['url']);
    // 响应的状态
    $statusCode = $response->getStatusCode();
    print "---Response with status: $statusCode\n";
    // 我们获取头部
    print "---Headers of the response\n";
    foreach ($response->getHeaders() as $name => $values) {
        print "$name: $values[0]\n";
    }
    // 我们显示服务器的响应
    print "---Server response: [{$response->getContent()}]\n";
} catch (ExceptionInterface $ex) {
    // 我们显示错误
    print "Error communicating with the server: {$ex->getMessage()}\n";
    exit(2);
}

说明

  • 第 29–35 行:向静态方法 [HttpClient::create] 传递了一个参数——一个选项关联数组,这些选项将适用于该客户端发出的所有请求;
  • 第 31 行:选项 [auth_basic] 的值是一个包含两个元素的数组 [user, password]。客户端将使用这些元素向 Web 服务进行身份验证。选项 [auth_basic] 指定一种名为 [Basic] 的身份验证类型,这个名称来自客户端将发送的 HTTP 头 [Authorization] 的值。还有其他身份验证类型;
  • 第 33–34 行:针对 HTTPS 协议的两个有用选项,我们稍后再介绍。如果配置文件没有另行指定,它们默认为 [true] ;
  • 除这段代码之外,该客户端与前面的客户端相同。

为了查看客户端发送的 HTTP 头,我们使用如下 [config-spy.json] 配置,把它连接到运行在 100 端口上的监视服务器:

1
2
3
4
5
{
    "url": "http://localhost:100/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}

命令 [php auth-client.php config-spy.json] 在间谍服务器的终端中产生如下输出:

> php spy-server.php 100
Spy server waiting for a client on port 100
Client connected: 127.0.0.1:50388
--- lines received
GET /php8-oct-2026/scripts-web/08/auth-server.php HTTP/1.1
Host: localhost:100
Accept: */*
Authorization: Basic YWRtaW46YWRtaW4=
User-Agent: Symfony HttpClient (Curl)
Accept-Encoding: gzip

--- end of the communication
  • 第 8 行:我们看到客户端发送的头 [Authorization: Basic XXX] 。字符串 XXX 是字符串 [user:password] 的 Base64 编码版本。

要验证这一点,可以使用 PHP 的 [base64_decode] 函数对收到的字符串解码。[-r] 选项让 [php] 命令执行其后的 PHP 代码:

> php -r "echo base64_decode('YWRtaW46YWRtaW4='), PHP_EOL;"
admin:admin

Base64 编码不是加密:任何人都可以对该字符串解码。

17.11.2. 服务器

服务器 [auth-server.php] 如下:

<?php

declare(strict_types=1);

// 依赖
require_once __DIR__ . '/../../vendor/autoload.php';

use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

// 授权用户:login => password
$users = ["admin" => "admin"];
//
// 我们获取当前请求
$request = Request::createFromGlobals();
// 客户端发送的凭据(如果它没有发送则为 null)
$requestUser = $request->getUser();
$requestPassword = $request->getPassword();
// 用户存在吗?
$found = $requestUser !== null && $requestPassword !== null
    && array_key_exists($requestUser, $users)
    && hash_equals($users[$requestUser], $requestPassword);
// 准备响应
$response = new Response();
// 我们设置响应的状态码
if (!$found) {
    // 未找到 - 代码 401
    $response->setStatusCode(Response::HTTP_UNAUTHORIZED);
    $response->headers->set("WWW-Authenticate", 'Basic realm="PHP 8 by example"');
} else {
    // 已找到 - 代码 200
    $response->setStatusCode(Response::HTTP_OK);
}
// 响应没有内容,只有 HTTP 头
$response->send();

说明

  • 第 12 行:授权用户——这里只有一个——登录名为 [admin] ,密码为 [admin];
  • 第 17 行:[getUser] 方法属于对象 [Request],它返回用户 ID,该 ID 由 PHP 从客户端发送的 [Authorization: Basic …] 头中提取;如果客户端没有发送该头,则返回 [null] 。没有 [HttpFoundation] 时,可以在 [$_SERVER['PHP_AUTH_USER']] 中找到它;
  • 第 18 行:密码同理([$_SERVER['PHP_AUTH_PW']]);
  • 第 20–22 行:我们在授权用户列表中查找尝试登录的用户。密码使用函数 [hash_equals] 而不是运算符 [===] 进行比较:其执行时间不取决于两个字符串在何处出现差异,这可以防止攻击者通过测量响应时间逐个字符地猜出密码;
  • 第 26–29 行:如果用户未通过身份验证,则向客户端发送以下内容:
    • 状态码 [401 Unauthorized];
    • 一个 [WWW-Authenticate: Basic realm="something"] 头。浏览器会识别这个头,并显示一个身份验证窗口,提示用户登录。HTTP 头只能使用 ASCII 字符书写。PHP 7 的脚本使用 [utf8_decode] 函数把 UTF-8 字符串转换为 ISO-8859-1;该函数自 PHP 8.2 起已被弃用。如果需要,我们会使用 [mb_convert_encoding($text, 'ISO-8859-1', 'UTF-8')]。我们的文本 [PHP 8 by example] 只使用 ASCII 字符;
  • 第 30–32 行:如果用户已被识别,则向客户端发送状态码 [200 OK];
  • 第 35 行:响应不包含文档,只有状态行和头。

让我们用浏览器请求 URL [http://localhost/php8-oct-2026/scripts-web/08/auth-server.php] :浏览器会显示一个登录窗口。如果输入了错误的凭据,浏览器会一直显示这个窗口,直到输入正确的凭据为止:每次都会与服务器往返一次,总是返回相同的响应,从而触发浏览器的身份验证窗口。下面是服务器在没有凭据时的响应:

1
2
3
4
5
6
7
8
9
> curl -i http://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 401 Unauthorized
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
WWW-Authenticate: Basic realm="PHP 8 by example"
Connection: close
Content-Type: text/html; charset=UTF-8
  • 第 2 行:响应的状态码 [401 Unauthorized] ;
  • HTTP 头 [WWW-Authenticate] 提示客户端进行身份验证;
  • 响应主体为空。

使用 [-u admin:admin] 选项时,[curl] 会发送凭据 [admin, admin]:

1
2
3
4
5
6
7
8
9
> curl -i -u admin:admin http://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=UTF-8
  • 第 2 行:响应状态码 [200 OK];
  • 响应主体为空。

让我们用授权用户 [auth-client.php] 运行客户端 [admin, admin]。服务器的响应如下:

> php auth-client.php
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/html; charset=UTF-8
---Server response: []
  • 第 2 行:服务器的响应是 [200 OK];
  • 最后一行:响应没有内容。

现在让我们使用配置文件 [config-auth-client-ko.json],用错误的密码运行客户端:

1
2
3
4
5
{
    "url": "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "x"
}

响应如下:

1
2
3
4
> php auth-client.php config-auth-client-ko.json
---Response with status: 401
---Headers of the response
Error communicating with the server: HTTP/1.0 401 Unauthorized returned for "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php".
  • 第 2 行:客户端成功收到了 401 状态码;
  • 第 4 行:客户端中抛出了一个异常。它是由 Symfony 客户端 [HttpClient] 抛出的:当 HTTP 响应的状态码表示错误,并且客户端试图读取响应头或内容时,它会抛出 [ClientExceptionInterface] (4xx 状态码)或 [ServerExceptionInterface] (5xx 状态码)类型的异常。异常消息表明服务器以 [401 Unauthorized] 作出响应,表示用户未被识别。如果想读取包含错误的响应的头或主体,请使用 [$response->getHeaders(false)] 或 [$response->getContent(false)]。我们将在税额计算应用中用到这一点,那里的服务器会在返回错误码的同时返回 JSON 错误消息。

17.11.2.1. 当服务器始终响应 401 时

在某些 [Apache] 安装中,服务器对每个请求都会响应 [401 Unauthorized] ,即使凭据正确也是如此。原因不在于 PHP 脚本,而在于 [Apache] 执行 PHP 的方式。当 PHP 是 [Apache] 的模块(mod_php)时,它会收到请求的所有 HTTP 头。然而,当 [Apache] 按照 FastCGI 协议在单独的进程中执行 PHP(模块 [mod_fcgid] 或 [mod_proxy_fcgi])时,默认不会把包含标识符的 [Authorization] 头传递给它:对 PHP 来说,客户端从未进行过身份验证。为此,[scripts-web] 文件夹中包含如下 [.htaccess] 文件,它适用于其所有子文件夹:

1
2
3
4
5
6
7
# 将 HTTP [Authorization] 头传递给 PHP(HTTP Basic 身份验证)。
# 当 PHP 以 Apache 模块 (mod_php) 方式运行时,PHP 总能收到它。但当
# PHP 通过 FastCGI (mod_fcgid、PHP-FPM……) 运行时,Apache 默认
# 不会传递它:客户端发送的凭据就会丢失,服务器
# 对每个请求都回答 401。下面两行可以解决这个问题。
CGIPassAuth On
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
  • 第 6 行:指示 [Apache] (2.4.13 及更高版本)把 [Authorization] 头传递给 FastCGI 程序;
  • 第 7 行:第二种较旧的方法,它把 [Authorization] 头复制到 [HTTP_AUTHORIZATION] 环境变量中。Symfony 的 [Request] 类可以从那里读取标识符。

对于 mod_php,这两行不起作用。我们用 [curl] 来验证服务器是否正确接收了凭据,与浏览器不同,它不会在请求之间保存任何内容:[curl -i -u admin:admin "http://localhost/php8-oct-2026/scripts-web/08/auth-server.php"] 应该返回 200 状态码。如果浏览器仍然显示其身份验证窗口,则必须彻底关闭浏览器(它会在整个会话期间保留被拒绝的凭据),或者使用无痕窗口。

17.11.3. 保护客户端/服务器连接的安全

我们已经看到,为了向服务器进行身份验证,客户端会发送如下头:

Authorization: Basic YWRtaW46YWRtaW4=

如果这一行被间谍软件截获,它可以很容易地获取在字符串 [login, password] 中以 Base64 编码的凭据 [YWRtaW46YWRtaW4=]。因此,身份验证必须在客户端与服务器之间的安全连接上进行。安全的 URL 连接使用 [HTTPS] 协议而不是 HTTP 协议。[HTTPS] 协议是在由 TLS 协议(Transport Layer Security,传输层安全,SSL 的继任者)加密的客户端/服务器连接中运行的 HTTP 协议。安全的 URL 连接形如 [https://document_path]。HTTPS 协议的默认端口是 443 端口。

并非所有 Web 服务器都接受这种格式的 URL;它们必须经过配置才能接受。[Laragon] 的 [Apache] 服务器支持 HTTPS 协议,但默认没有启用。你可以通过 [Laragon] 菜单启用它:在 [Laragon] 窗口中单击右键,然后选择 [Apache / SSL / Enabled]。随后 [Apache] 服务器会重新启动,[Laragon] 窗口显示它现在监听两个端口:80 端口(HTTP)和 443 端口(HTTPS)。在启用过程中,[Laragon] 为服务器生成了一个所谓的自签名证书。

而 Web 浏览器默认会拒绝自签名证书。对于仅仅是未知的证书,[Chrome] 和 [Edge] 会显示一个警告页面(“您的连接不是私密连接”),其中有一个按钮 [Advanced] ,随后是一个链接 [Proceed to localhost (unsafe)]。不过,这个链接并非总会出现:特别是当证书被认定为不合规,或者浏览器已缓存了站点 [localhost] 应始终以 HTTPS 并使用有效证书提供服务的信息(HSTS 机制)时,它就不会出现。此时正确的解决办法是让系统信任 [Laragon] 的证书:

  • 在 [Laragon] 菜单中,选择 [Apache / SSL / Add laragon.crt to Trust Store]。[Windows] 会提示你确认将该证书添加到用户的受信任根证书颁发机构中;请接受;
  • 彻底关闭浏览器(其所有窗口)并重新启动:[Chrome] 和 [Edge] 使用 [Windows] 的证书存储,现在对于 [Laragon] 的证书,访问 [https://localhost] 时不会再出现警告;
  • 如果浏览器仍然拒绝该页面,请删除它可能为 [localhost] 缓存的 HSTS 规则:打开页面 [chrome://net-internals/#hsts] (对于 [Edge],请打开 [edge://net-internals/#hsts]),输入 [localhost] 到 [Delete domain security policies] 字段,然后单击 [Delete]。

作为最后手段,并且仅限于在你自己的计算机上,如果你在错误页面上(不要点击任何输入框)直接键入 [Chrome] 和 [Edge] 单词 [thisisunsafe],它们就会允许你绕过该警告。这是面向开发人员的浏览器变通办法:切勿在你无法控制的站点上使用。如果这些方法都不起作用,请在浏览器中使用 URL [http://localhost/...]:我们将在税额计算第 8 版一章中说明,为什么在你自己的机器上这样做并不草率。

把证书添加到 [Windows] 存储并不影响我们的 PHP 客户端:PHP 所使用的 [curl] 库有它自己的证书颁发机构列表。下面的示例说明了这一点。

既然我们有了一个安全的服务器,就让我们为客户端 [auth-client.php] 提供如下配置文件 [config-auth-client-https-verify.json]:

1
2
3
4
5
{
    "url": "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin"
}
  • 第 2 行:协议已变为 [https]。没有指定端口;默认为 443 端口。

让我们使用这个配置运行客户端。控制台输出如下:

> php auth-client.php config-auth-client-https-verify.json
Error communicating with the server: SSL certificate problem: self-signed certificate for "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php".

Symfony 客户端 [HttpClient] 抛出了异常,因为它不接受服务器发送的证书。TLS 连接依赖于由公认的证书颁发机构签发的证书。由 [Laragon] 生成的证书是自签名证书:它没有经过任何证书颁发机构的验证。因此客户端拒绝了它,而且拒绝得有道理:没有证据表明它正在与真正的服务器通信,而不是与冒名者通信。

可以指示 [HttpClient] 不验证服务器发送的证书。这通过 [verify_peer] 和 [verify_host] 选项来完成,它们属于 [HttpClient::create] 方法,我们的客户端从其配置文件中读取它们。[config-auth-client-https.json] 文件将它们设置为 [false]:

1
2
3
4
5
6
7
{
    "url": "https://localhost/php8-oct-2026/scripts-web/08/auth-server.php",
    "user": "admin",
    "password": "admin",
    "verify_peer": false,
    "verify_host": false
}
  • 第 5 行:不验证证书是否由公认的证书颁发机构签发;
  • 第 6 行:不验证证书是否是为所联系的机器(这里是 [localhost] )签发的。

我们在上一章中已经遇到过这个问题,当时用的是 [libcurl] 库及其 [CURLOPT_SSL_VERIFYPEER] 选项。当 PHP 配置中启用了 [curl] 扩展时(这里正是如此),Symfony 客户端 [HttpClient] 实际上就是一个 [curl] 客户端:此时 [HttpClient::create] 实例化的类是 [CurlHttpClient],它把自己的选项转换为 [curl] 选项:[verify_peer] 变为 [CURLOPT_SSL_VERIFYPEER],而 [verify_host] 变为 [CURLOPT_SSL_VERIFYHOST]。

如果我们现在用命令 [php auth-client.php config-auth-client-https.json] 运行客户端,会得到如下结果:

> php auth-client.php config-auth-client-https.json
---Response with status: 200
---Headers of the response
date: Thu, 01 Oct 2026 16:55:27 GMT
server: Apache/2.4.58 (Ubuntu)
x-powered-by: PHP/8.5.11
cache-control: no-cache, private
vary: Accept-Encoding
content-encoding: gzip
connection: close
content-type: text/html; charset=UTF-8
---Server response: []

用户被成功识别。使用 [curl] 时,选项 [-k] (或 [--insecure])的作用与我们的两个选项相同:

1
2
3
4
5
6
7
8
9
> curl -i -k -u admin:admin https://localhost/php8-oct-2026/scripts-web/08/auth-server.php
HTTP/1.0 200 OK
Date: Thu, 01 Oct 2026 15:31:46 GMT
Server: Apache/2.4.58 (Ubuntu)
X-Powered-By: PHP/8.5.11
Cache-Control: no-cache, private
Vary: Accept-Encoding
Connection: close
Content-Type: text/html; charset=UTF-8

注意:只有在开发期间、在你自己的机器上,才可以禁用证书验证。更稳妥的解决方案是使用 [cafile] 选项(属于 [HttpClient] ,或 [curl] 的 [--cacert] 选项)向客户端指定服务器的证书:验证仍然保持启用,客户端接受该特定证书。在生产环境中,服务器拥有由公认的证书颁发机构签发的证书(例如从 Let’s Encrypt 免费获得),不需要任何选项。

现在我们知道如何向安全的服务器进行身份验证了。