README

PSR-7 的独立完整实现 - HTTP 消息接口。

该软件包不依赖于任何现有框架，仅实现 PSR-7 中描述的功能。

安装

安装库的首选方式是使用 composer

composer require kambo/httpmessage

基本用法

工厂

该软件包包含一组工厂类，用于从超全局变量（$_POST、$_COOKIE、$_FILES 等）创建 Files、Headers、Uri 和 ServerRequest 类的实例。每个对象都是通过在相应的工厂上调用 create 方法创建的。唯一参数是环境类的实例。例如，以下代码将创建 ServerRequest 实例

// Create Environment object based on server variables.
$environment = new Environment($_SERVER, fopen('php://input', 'w+'), $_POST, $_COOKIE, $_FILES);
// Create instance of ServerRequest object
$serverRequest = (new ServerRequestFactory())->create($environment);

环境对象是服务器和 CGI 变量的简单包装，通常是从超全局变量（$_POST、$_COOKIE、$_FILES 等）实例化的。

Environment 类的构造函数有两个必选参数 - server 和 body。

服务器是一个包含诸如标题、路径和脚本位置等信息的相关数组，它必须与超全局变量 $_SERVER 具有相同的结构。主体是 resource，它由请求主体的原始数据创建。通常，它应该从 php://input 流创建。

构造函数还接受三个可选参数 - post、cookie 和 files。每个参数都是超全局变量的对应物，并且它必须具有相同的结构，例如：cookie 必须与 $_COOKIE 变量具有相同的结构。如果缺少这些参数中的任何一个，则使用空数组。

// Create Environment object based on server variables.
$environment = new Environment($_SERVER, fopen('php://input', 'w+'), $_POST, $_COOKIE, $_FILES); 

服务器请求 - ServerRequest

服务器请求是服务器端 HTTP 请求的表示。

根据 HTTP 规范，此类包含以下每个方面的属性

• 协议版本
• HTTP 方法
• URI
• 头部
• 消息主体

此外，它封装了从 CGI 和/或 PHP 环境到达应用程序的所有数据，包括

• 在 $_SERVER 中表示的值。
• 提供的任何cookie（通常通过 $_COOKIE 提供）
• 查询字符串参数（通常通过 $_GET 或通过 parse_str() 解析提供）
• 如果有，上传文件（如由 $_FILES 表示）
• 反序列化的主体参数（通常来自 $_POST）

通过从现有的超全局变量（$_POST、$_COOKIE、$_FILES 等）创建 ServerRequest 实例来创建 ServerRequest。

$environment   = new Environment($_SERVER, fopen('php://input', 'w+'), $_POST, $_COOKIE, $_FILES);
$serverRequest = (new ServerRequestFactory())->create($environment);

使用 ServerRequest

获取值

ServerRequest 随带许多方便的方法来处理请求

// Create ServerRequest from existing super global variables
$environment   = new Environment($_SERVER, fopen('php://input', 'w+'), $_POST, $_COOKIE, $_FILES);
$serverRequest = (new ServerRequestFactory())->create($environment);

// Return method of server request eg. GET
$serverRequest->getMethod();
// Return URI server request eg. http://foo.bar
$serverRequest->getUri();
// Return URI server query parameters eg. [ 'foo' => 'bar' ]
$serverRequest->getQueryParams();
// Get server parameters ($_SERVER) 
$serverRequest->getServerParams();
// Get request cookies ($_COOKIE)
$serverRequest->getCookieParams();
// Returns an associative array of the message's headers
$serverRequest->getHeaders();

请求最重要的部分之一是其主体。可以通过调用方法 getParsedBody 获取请求主体。

// Get parsed body of request
$serverRequest->getParsedBody();

该软件包根据请求的内容类型解析原始请求主体。以下内容类型受到支持

• 如果内容类型是 application/json，则 json
• 如果内容类型是 application/xml 或 text/xml（返回 SimpleXMLElement 实例），则 xml
• 如果内容类型是 application/x-www-form-urlencoded 或 multipart/form-data，则查询字符串

上传文件存储为 UploadedFile 类实例的树。可以通过方法 getUploadedFiles 获取它们

// Get request uploaded files as tree in following format: 
// <name of upload field> => [ <instance of UploadedFile class>, ... ]
$serverRequest->getUploadedFiles();

修改请求

可以通过以 with 字符串为前缀的方法修改请求。例如

• withMethod() - 更改请求方法
• withQueryParams() - 更改查询参数
• withParsedBody() - 更改解析后的主体
• withCookieParams() - 更改 cookie 参数

由于请求是不可变的；所有更改状态的方法都保留当前消息的内部状态，并返回包含更改状态的新实例。

$requestWithGet = $serverRequest->withMethod('GET');
$requestWithPost = $requestWithGet->withMethod('POST');

echo $requestWithGet; // print GET
echo $requestWithPost; // print POST

流

流提供了一组常见的PHP流操作包装，包括将整个流序列化为字符串。

通常用于描述Request或Response的正文内容。

新的Stream实例必须从现有的Resource创建。

// Create Stream from based on raw data from the request body.
$stream = new Stream(fopen('php://input', 'w+'));

可以使用getContents方法轻松将Stream的内容转换为字符串。

// Create Stream from based on raw data from the request body:
$stream = new Stream(fopen('php://input', 'w+'));
// Convert Stream into string:
echo $stream->getContents();

请求

请求是出站客户端请求的表示。例如，它可以表示对某个第三方网站的请求。

请求对象通过方法名和URI作为参数创建。

// Create request with GET method to the URI 'foo.bar':
$clientRequest = new Request('GET', 'foo.bar');
echo $clientRequest->getMethod(); // GET

请求对象构造函数还接受三个可选参数 - 标头、正文和协议。

标头由Headers对象实例表示。以下片段展示了如何创建带有标头X-Foo设置为值Bar的请求。

// Prepare array with header X-Foo and value Bar:
$headers = ['X-Foo' => 'Bar'];
// Create request with GET method to the uri 'foo.bar' with header 'X-Foo: Bar':
$clientRequest = new Request('GET', 'foo.bar', $headers); 

请求正文可以是字符串或Stream类的实例，如果提供字符串，则将从这个字符串创建一个Stream实例。

// Create request with GET method to the uri 'foo.bar' with body :
$clientRequest = new Request('GET', 'foo.bar', [], 'string body');
// Body is of type Stream it must be typecast to the string:
echo (string)$clientRequest->getBody(); // string body

请求是不可变的；所有更改状态的方法都保留实例的内部状态，并返回包含更改状态的新实例。

注意：包不提供执行实际请求的客户端。

响应

响应是出站服务器端响应的表示。通常表示将发送到浏览器的数据。

响应对象的构造函数有三个可选参数 - 状态、标头和正文。如果未提供状态，则使用状态代码200（'OK'）。其余参数的默认值是null。

// Create response with status 200, empty headers and body.
$response = new Response();
// 

如果您想包含额外的标头，可以像在Request中一样，通过创建并设置Headers类的实例来完成。

// Prepare array with header X-Foo and value Bar
$headers = ['X-Foo' => 'Bar'];
// Create response with status code 200 and header 'X-Foo: Bar'
$response = new Response(200, $headers); 

正文的处理与Request类相同，它可以是Stream的实例或字符串。

// Create response with status code 200, empty headers and 
$response = new Response(200, null, 'string body');
// Body is instance of Stream it must be typecast to the string.
echo (string)$response->getBody(); // string body

响应是不可变的；所有更改状态的方法都保留实例的内部状态，并返回包含更改状态的新实例。

许可证

MIT许可证（MIT），https://open-source.org.cn/licenses/MIT