深入理解PHP-FIG的HTTP消息接口(PSR-7)
HTTP消息是现代Web开发的基础，PHP-FIG的PSR-7规范定义了一套标准接口，用于处理HTTP请求和响应。本文将全面解析这些接口的设计理念和使用方法。
接口概览
PSR-7定义了7个核心接口，构成了HTTP消息处理的基础架构：
- MessageInterface - HTTP消息的基础接口
- RequestInterface - 客户端发出的HTTP请求
- ServerRequestInterface - 服务器接收的HTTP请求
- ResponseInterface - 服务器发出的HTTP响应
- StreamInterface - 数据流处理接口
- UriInterface - URI处理接口
- UploadedFileInterface - 上传文件处理接口
这些接口采用了不可变对象(Immutable Object)设计模式，所有修改操作都会返回一个新的实例，而不是修改原对象。
核心接口详解
MessageInterface - HTTP消息基础
作为所有HTTP消息的基础接口，MessageInterface定义了以下核心方法：
// 获取协议版本
public function getProtocolVersion(): string;
// 创建带有新协议版本的消息实例
public function withProtocolVersion(string $version): self;
// 获取所有头信息
public function getHeaders(): array;
// 检查头信息是否存在
public function hasHeader(string $name): bool;
// 获取指定头信息的值数组
public function getHeader(string $name): array;
// 获取指定头信息的字符串值
public function getHeaderLine(string $name): string;
// 创建带有新头信息的消息实例
public function withHeader(string $name, $value): self;
// 添加头信息值
public function withAddedHeader(string $name, $value): self;
// 创建不包含指定头信息的消息实例
public function withoutHeader(string $name): self;
// 获取消息体
public function getBody(): StreamInterface;
// 创建带有新消息体的消息实例
public function withBody(StreamInterface $body): self;
RequestInterface - HTTP请求
RequestInterface扩展了MessageInterface，增加了请求特有的方法：
// 获取请求目标
public function getRequestTarget(): string;
// 创建带有新请求目标的消息实例
public function withRequestTarget(string $requestTarget): self;
// 获取HTTP方法
public function getMethod(): string;
// 创建带有新HTTP方法的消息实例
public function withMethod(string $method): self;
// 获取URI对象
public function getUri(): UriInterface;
// 创建带有新URI的消息实例
public function withUri(UriInterface $uri, bool $preserveHost = false): self;
ServerRequestInterface - 服务器端请求
ServerRequestInterface进一步扩展了RequestInterface，增加了服务器环境特有的功能：
// 获取服务器参数(通常来自$_SERVER)
public function getServerParams(): array;
// 获取cookie参数
public function getCookieParams(): array;
// 创建带有新cookie参数的消息实例
public function withCookieParams(array $cookies): self;
// 获取查询参数
public function getQueryParams(): array;
// 创建带有新查询参数的消息实例
public function withQueryParams(array $query): self;
// 获取上传文件
public function getUploadedFiles(): array;
// 创建带有新上传文件的消息实例
public function withUploadedFiles(array $uploadedFiles): self;
// 获取解析后的请求体
public function getParsedBody();
// 创建带有新解析后请求体的消息实例
public function withParsedBody($data): self;
// 获取所有属性
public function getAttributes(): array;
// 获取单个属性
public function getAttribute(string $name, $default = null);
// 创建带有新属性的消息实例
public function withAttribute(string $name, $value): self;
// 创建不包含指定属性的消息实例
public function withoutAttribute(string $name): self;
ResponseInterface - HTTP响应
ResponseInterface扩展了MessageInterface，增加了响应特有的方法：
// 获取状态码
public function getStatusCode(): int;
// 创建带有新状态码的消息实例
public function withStatus(int $code, string $reasonPhrase = ''): self;
// 获取状态描述
public function getReasonPhrase(): string;
辅助接口详解
StreamInterface - 数据流处理
StreamInterface提供了对数据流的统一操作：
// 将流内容转为字符串
public function __toString(): string;
// 关闭流
public function close(): void;
// 分离底层资源
public function detach();
// 获取流大小
public function getSize(): ?int;
// 检查是否到达流末尾
public function eof(): bool;
// 检查是否可定位
public function isSeekable(): bool;
// 定位到指定位置
public function seek(int $offset, int $whence = SEEK_SET): void;
// 定位到流开头
public function rewind(): void;
// 检查是否可写
public function isWritable(): bool;
// 写入数据
public function write(string $string): int;
// 检查是否可读
public function isReadable(): bool;
// 读取数据
public function read(int $length): string;
// 获取剩余内容
public function getContents(): string;
// 获取流元数据
public function getMetadata(?string $key = null);
UriInterface - URI处理
UriInterface提供了对URI各部分的解析和操作：
// 获取协议部分
public function getScheme(): string;
// 获取授权部分
public function getAuthority(): string;
// 获取用户信息
public function getUserInfo(): string;
// 获取主机部分
public function getHost(): string;
// 获取端口
public function getPort(): ?int;
// 获取路径
public function getPath(): string;
// 获取查询字符串
public function getQuery(): string;
// 获取片段
public function getFragment(): string;
// 创建带有新协议的消息实例
public function withScheme(string $scheme): self;
// 创建带有新用户信息的消息实例
public function withUserInfo(string $user, ?string $password = null): self;
// 创建带有新主机的消息实例
public function withHost(string $host): self;
// 创建带有新端口的消息实例
public function withPort(?int $port): self;
// 创建带有新路径的消息实例
public function withPath(string $path): self;
// 创建带有新查询字符串的消息实例
public function withQuery(string $query): self;
// 创建带有新片段的消息实例
public function withFragment(string $fragment): self;
UploadedFileInterface - 上传文件处理
UploadedFileInterface提供了对上传文件的统一操作：
// 获取文件流
public function getStream(): StreamInterface;
// 移动文件到新位置
public function moveTo(string $targetPath): void;
// 获取文件大小
public function getSize(): ?int;
// 获取错误码
public function getError(): int;
// 获取客户端文件名
public function getClientFilename(): ?string;
// 获取客户端文件类型
public function getClientMediaType(): ?string;
设计理念解析
PSR-7接口设计遵循了几个重要原则：
- 不可变性(Immutability)：所有修改操作都返回新实例，确保线程安全和可预测性。
- 流式处理(Streaming)：使用StreamInterface处理大数据，避免内存问题。
- 值对象(Value Objects)：URI和上传文件等作为值对象处理。
- 类型安全：严格类型提示和返回值类型声明。
实际应用示例
创建请求对象
$uri = new Uri('https://example.com/api');
$body = new Stream(fopen('php://temp', 'r+'));
$body->write(json_encode(['key' => 'value']));
$request = new Request(
'POST',
$uri,
['Content-Type' => 'application/json'],
$body
);
处理服务器请求
$request = new ServerRequest(
'GET',
new Uri('https://example.com'),
$_SERVER,
$_COOKIE,
$_GET,
$_FILES,
$_POST
);
// 获取查询参数
$page = $request->getQueryParams()['page'] ?? 1;
// 添加属性
$request = $request->withAttribute('user_id', 123);
构建响应对象
$response = new Response(200, ['Content-Type' => 'text/html']);
$response->getBody()->write('<h1>Hello World</h1>');
// 修改状态码
$response = $response->withStatus(404);
最佳实践
- 尽量使用接口类型提示：在需要HTTP消息的地方使用接口而不是具体实现。
- 利用不可变性：链式调用修改操作。
- 注意流资源管理：及时关闭不再使用的流。
- 合理处理大文件：使用流式处理避免内存耗尽。
通过理解这些接口的设计和使用方法，开发者可以构建出更加健壮、可维护的HTTP应用程序。PSR-7已经成为PHP生态中处理HTTP消息的事实标准，被众多框架和库广泛采用。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
