ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

guzzlehttp/psr7 完整指南:PSR-7 HTTP 消息库的安装、核心对象与实战用法

guzzlehttp/psr7 完整指南:PSR-7 HTTP 消息库的安装、核心对象与实战用法 后端【免费下载链接】psr7PSR-7 HTTP message library项目地址https://gitcode.com/gh_mirrors/ps/psr7点击查看免费下载guzzlehttp/psr7是 PHP 生态中最流行的 PSR-7HTTP 消息接口标准实现为 PHP 应用提供请求Request、响应Response、URI、上传文件和流Stream等对象既可用于 Guzzle 客户端也可用于任何遵循 PSR-7 接口的框架与中间件。阅读本文后你将掌握该库的安装与版本选择、核心对象的构造与不可变修改模式、流的可变形为以及 PSR-17 工厂的使用方式并了解其底层实现原理与配套文档体系。什么是 guzzlehttp/psr7guzzlehttp/psr7是一个纯 PHP 的 PSR-7 HTTP 消息实现。它提供的对象模型完整覆盖了psr/http-message规范^2.0定义的消息接口族Request / Response / ServerRequestHTTP 请求与响应消息UriRFC 3986 规范的 URI 对象UploadedFile文件上传消息Stream及一系列流装饰器消息体body的底层数据句柄从 composer.json 可以看到该包通过provide声明了psr/http-message-implementation: 2.0与psr/http-factory-implementation: 1.1即它本身就是这两个 PSR 标准的实现者。同时它依赖psr/http-factoryPSR-17 工厂接口与symfony/polyfill-php80、symfony/polyfill-php82等 polyfill保证在低版本 PHP 上也能使用现代语法。何时该用这个包何时不该用README 给出了非常清晰的边界该直接使用此包当你需要创建或检查 PSR-7 消息而不实际发送 HTTP 请求时例如编写中间件、构建请求/响应对、做消息体解析、单元测试替身等。不该直接使用如果你只是要发送 HTTP 请求应安装guzzlehttp/guzzle——它已经依赖本包你无需重复引入。与 Guzzle 的关系本包是 Guzzle 客户端guzzlehttp/guzzle的底层消息层依赖但它不依赖 Guzzle可独立使用。任何遵守 PSR-7 接口的库如 Slim、Laminas Diactoros 生态、各种 HTTP 中间件都可以与本包的对象互换协作。安装与版本选择通过 Composer 一条命令即可安装composer require guzzlehttp/psr7安装后代码通过 PSR-4 自动加载命名空间GuzzleHttp\Psr7\映射到仓库的 src 目录见 composer.json 的autoload配置。版本指导不同大版本的维护状态与 PHP 版本要求如下以当前仓库为准版本状态支持的 PHP 版本3.0最新Latest7.4, 8.62.13维护Maintenance7.2.5, 8.61.9已停止维护End of Life5.4, 8.2其中 3.x 系列当前仓库对应的主版本要求 PHP^7.4 || ^8.0。选择版本时请根据你的 PHP 运行环境与依赖约束composer.json中的require区间决定。快速上手三行代码认识核心对象README 的 Quick Start 展示了最基本的用法use GuzzleHttp\Psr7\Request; use GuzzleHttp\Psr7\Response; use GuzzleHttp\Psr7\Utils; $request new Request(GET, https://example.com/api); $response new Response(200, [Content-Type text/plain], OK); $stream Utils::streamFor(request or response body); echo $request-getMethod(); // GET echo $response-getStatusCode(); // 200 echo $stream; // request or response body这里的三个对象分别对应三种核心抽象Request构造时至少需要 HTTP 方法与 URI字符串或UriInterface均可Response构造时只需状态码Content-Type等头部与正文都可选Utils::streamFor()把字符串等任意数据源包装成流对象字符串可直接echo输出从 src/Request.php 的构造器签名可以看到完整参数顺序new Request( string $method, // HTTP 方法如 GET、POST $uri, // 字符串或 UriInterface array $headers [], // 头部值为 string|string[] $body null, // 字符串 / resource / StreamInterface / null string $version 1.1 // 协议版本默认 1.1 )对应的 src/Response.php 构造器则支持更宽松的调用new Response( int $status 200, // 状态码必须为 100~599 array $headers [], // 响应头部 $body null, // 响应正文 string $version 1.1, ?string $reason null // 原因短语为空时按状态码自动填充 )注意 Response 的状态码构造器会调用assertStatusCodeRange()校验小于 100 或大于等于 600 的状态码会直接抛出InvalidArgumentException见 src/Response.php。原因短语reason phrase在未显式提供时会从内置的标准短语表PHRASES中按状态码自动匹配例如 200 OK、404 Not Found该表覆盖了 1xx 到 5xx 的 60 余个标准状态码见 src/Response.php。不可变性设计修改消息不会改动原对象PSR-7 消息Request、Response、Uri是**不可变immutable**的。README 明确强调Methods such aswithHeader()andwithUri()return a changed copy instead of modifying the original object.也就是说所有with*()方法都会返回一份修改后的副本原对象保持不变$request $request-withHeader(Accept, application/json); // 必须用返回值重新赋值原 $request 不受影响从实现上看这是通过克隆 替换字段完成的。例如 src/MessageTrait.php 的withHeader()$new clone $this; // 克隆原对象 // 在副本上执行头部替换 $new-headerNames[$normalized] $name; $new-headers[$name] $value; return $new; // 返回新副本同样src/Request.php 的withMethod()也是先clone $this再修改$new-method。这一设计让消息对象可以安全地在中间件链中传递、缓存与复用不用担心被意外篡改。与之相对的流是可变的与消息不同流Stream是可变的数据句柄。读取、写入、seek移动游标、关闭都会改变流的游标位置、内容或可用状态$stream Utils::streamFor(hello world); echo $stream-read(5); // hello游标前进到第 5 字节 echo $stream-getContents(); // world游标已到末尾从 src/Stream.php 的实现可以看到__toString()会在流可 seek 时先把游标重置到 0再读取全部内容保证字符串化结果始终是完整内容。请求Request深入请求目标与 Host 头Request不只是方法 URI的容器它还承担着两项重要的协议职责。请求目标Request TargetgetRequestTarget()会根据 URI 自动推导出 HTTP 请求行所需的 origin-form 目标。从 src/Request.php 可以看出推导规则路径为空时目标为/存在查询串时追加?query路径以//开头时会规整为单斜杠开头normalizePathForOriginForm最终结果必须通过Rfc9112::isValidRequestTarget()校验不允许包含空白或控制字符。你也可以用withRequestTarget()显式覆盖默认推导值例如用于构造 OPTIONS*或 CONNECThost:port这类特殊请求目标。Host 头自动管理构造 Request 时若未显式传入Host头构造器会自动从 URI 的 host及非默认端口生成 Host 头见 src/Request.php并且总是把 Host 放在头部列表的第一位符合 RFC 9110 对 Host 头的推荐顺序。withUri($uri, $preserveHost false)的第二个参数则控制是否保留原 Host 头为false默认时以新 URI 的 host 覆盖为true时保留现有的 Host 头。方法与协议的合法性校验方法名必须是合法的 HTTP tokenRfc9110::isToken()否则抛异常src/Request.php协议版本必须形如合法的 HTTP 版本号Rfc9112::isValidProtocolVersion()头名称必须是 token头值必须是合法的 field-value且不支持 obs-fold换行折叠这是出于 RFC 9112 对发送方不得生成折叠字段的安全考量见 src/MessageTrait.php。响应Response深入状态码与原因短语Response的核心是状态码status code与原因短语reason phrase。构造函数中$reason为空字符串时会自动查表填充标准短语withStatus(int $code, string $reasonPhrase )也遵循同样的逻辑src/Response.php。$response new Response(404); echo $response-getStatusCode(); // 404 echo $response-getReasonPhrase(); // Not Found自动填充自定义原因短语也是允许的只要不包含非法控制字符即可$response new Response(418, [], short and stout, 1.1, Im a teapot);消息共性与头部操作Request、Response、ServerRequest 共用MessageTrait因此头部操作 API 完全一致且全部为大小写不敏感内部通过Utils::asciiToLower()做无区域设置依赖的 ASCII 小写化归一见 src/Utils.php方法作用getHeaders()返回全部头部原始大小写为键hasHeader(string $name)判断头部是否存在忽略大小写getHeader(string $name)返回某头部的全部值数组getHeaderLine(string $name)返回某头部合并为逗号分隔的字符串withHeader(string $name, $value)设置替换头部返回副本withAddedHeader(string $name, $value)追加头部值返回副本withoutHeader(string $name)删除头部返回副本头部值支持字符串或字符串数组且会自动去除首尾的 SP/HTAB 空白对应 RFC 9110 中header-field field-name : OWS field-value OWS的语法见 src/MessageTrait.php。传空数组或非字符串值会抛出InvalidArgumentException。流与 Utils从任意数据源构造流Utils是一个静态工具类构造函数为 private不可实例化其中使用频率最高的当属Utils::streamFor()。streamFor() 支持的数据源类型从 src/Utils.php 的注释与实现可见streamFor()接受非常宽泛的输入并给出对应策略输入类型处理策略字符串写入php://temp并包装为Stream空串返回空流StreamInterface原样返回不做复制PHP resource直接包装对php://input会先复制到php://temp规避其怪癖行为Iterator包装为只读的PumpStream按需从迭代器拉取数据带__toString()的对象先转字符串再构造流null返回空流callable / 闭包 / 可调用对象包装为PumpStream按建议字节数反复调用直到返回false/null其他标量如 int、float、bool抛出InvalidArgumentException其中迭代器数据在读取时会做类型归一可转字符串的标量、null、带__toString()的对象会被拼为字符串块非有限浮点数及其他类型会抛出UnexpectedValueException。其他常用工具方法Utils::copyToString(StreamInterface $stream, int $maxLen -1)将流内容读入字符串-1表示读完全部Utils::copyToStream($source, $dest, $maxLen -1)在两个流之间拷贝数据内部按 8192 字节分块并处理写阻塞Utils::hash($stream, $algo, $rawOutput false)对整条流计算散列如 md5、crc32计算后恢复流的游标位置Utils::readLine($stream, ?int $maxLength null)逐字节读取一行可用于解析请求行/响应行Utils::tryFopen()/Utils::tryGetContents()把 PHP 原生 warning 转为异常的安全封装Utils::uriFor($uri)字符串或UriInterface统一转为UriInterfaceUtils::redactUserInfo(UriInterface $uri)将 URI 中 userinfo账号密码替换为***用于日志脱敏Utils::modifyRequest(RequestInterface $request, array $changes)用一次调用批量完成克隆 修改支持method、set_headers、remove_headers、body、uri、query、version键减少多次克隆开销见 src/Utils.php。PSR-17 工厂面向接口创建对象仓库还提供了 PSR-17HTTP Factory的完整实现——HttpFactory它一次性实现了全部六个工厂接口src/HttpFactory.phpRequestFactoryInterface→createRequest(string $method, $uri)ResponseFactoryInterface→createResponse(int $code 200, string $reasonPhrase )ServerRequestFactoryInterface→createServerRequest($method, $uri, array $serverParams [])StreamFactoryInterface→createStream(string $content )/createStreamFromFile()/createStreamFromResource()UploadedFileFactoryInterface→createUploadedFile()UriFactoryInterface→createUri(string $uri )推荐用法是在消费代码中依赖接口类型并注入HttpFactory实例接口层面的依赖倒置例如use GuzzleHttp\Psr7\HttpFactory; use Psr\Http\Message\ResponseFactoryInterface; /** var ResponseFactoryInterface $factory */ $factory new HttpFactory(); $response $factory-createResponse(200, OK);配套文档体系与测试保障README 维护了一份完整的文档索引全部位于仓库 docs 目录下按主题拆分PSR-7 Messages消息对象总览Streams and Decorators流及装饰器模式URI HelpersURI 辅助工具PSR-17 Factories工厂模式Message Helpers消息辅助方法Diagnostic Values诊断信息Header and Query Helpers头部与查询串辅助Stream Helpers流辅助方法URI and MIME HelpersURI 与 MIME 类型辅助Upgrade Guide版本升级指引Changelog变更记录在正确性保障方面仓库通过php-http/psr7-integration-tests与http-interop/http-factory-tests官方互操作测试套件来验证 PSR-7/PSR-17 合规性。例如 tests/Psr7Integration/RequestTest.php 只需提供一个new Request(GET, /)工厂方法其余数百条规范断言全部由官方测试基类继承执行这意味着你使用的消息行为与 PSR-7 规范保持一致。安全与许可仓库在 README 中声明了安全策略若发现安全漏洞请发送邮件至securitytidelift.com在修复公告发布前请勿公开披露安全相关问题。本包采用MIT License开源许可文本见仓库根目录的 LICENSE你可以自由使用、修改与分发只需保留版权声明。结语guzzlehttp/psr7是理解 PSR-7 规范的最佳参考实现之一不可变的消息对象、可变的流、大小写不敏感的头部归一、基于 RFC 9110/9112 的严格输入校验以及一套完整的 PSR-17 工厂。无论你是要在自己的框架中实现 HTTP 中间件还是需要为测试构造替身消息都可以从本仓库的 src 源码与 docs 文档体系出发快速构建出规范、安全、可复用的 HTTP 消息处理代码。赞分享后端【免费下载链接】psr7PSR-7 HTTP message library项目地址https://gitcode.com/gh_mirrors/ps/psr7点击查看免费下载相关推荐Nyholm/psr7: PSR-7 HTTP消息实现教程Nyholm/psr7: PSR 7 HTTP消息实现教程 项目介绍 Nyholm/psr7 是一个遵循 PHP FIG 标准具体是 PSR 7的 HTTPGuzzleHttp\Psr7\HttpFactory 全面指南在 PHP 项目中用 PSR-17 工厂接口创建 PSR-7 消息GuzzleHttp\Psr7\HttpFactory 全面指南在 PHP 项目中用 PSR 17 工厂接口创建 PSR 7 消息 本指南深入讲解 guzzl后端探索 Nyholm/psr7: PHP PSR-7 HTTP 消息接口实现探索 Nyholm/psr7: PHP PSR 7 HTTP 消息接口实现 在现代PHP开发中遵循统一的接口和标准是提高代码可读性、可维护性和互操作性的关键。创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表