README

AMPHP 是一组为 PHP 设计的事件驱动库，考虑到纤维和并发。 amphp/http 是一组基本 HTTP 原语，可以被服务器和客户端共享。

安装

此包可以作为 Composer 依赖项安装。

composer require amphp/http

此包需要 PHP 8.1 或更高版本。

用法

此包提供 HTTP 客户端和服务器所需的基本原语。

• 状态码
• Cookie
• 头部

状态码

通过 Amp\Http\HttpStatus 将 HTTP 状态码转换为可读格式。它包括每个 IANA 注册的状态码的常量。此外，通过 HttpStatus::getReason($code) 可获取默认原因。

Cookie

HTTP Cookie 由 RFC 6265 定义。此包实现了 set-cookie 和 cookie 头的解析器。它还提供了一种方便的开发者 API 来创建此类头部。

注意 此库不设置关于 Cookie 编码的标准。因此，RFC 6265 的限制适用于名称和值。如果您需要为某些 Cookie 设置任意值，建议使用 URL 编码或 Base64 等编码机制。

Set-Cookie

set-cookie 头用于创建 Cookie。服务器在响应中发送此头部，客户端在响应包含此类头部时解析头部。每个头部恰好包含一个头部。因此，相应的类被称为 ResponseCookie。

注意 关于 set-cookie 的更多信息可以在 MDN 参考 或其他来源中找到。

ResponseCookie::fromHeader() 接受一个头部值并尝试解析它。如果解析成功，则返回一个 ResponseCookie。如果不成功，则返回 null。不会抛出异常，因为接收到的 Cookie 总是用户输入且不受信任，根据 RFC，应丢弃格式错误的头部。

$attributes = CookieAttributes::default()->withSecure();
$cookie = new ResponseCookie("session", \bin2hex(\random_bytes(16)), $attributes);

var_dump($cookie->getName());
var_dump($cookie->getValue());
var_dump($cookie->isHttpOnly());
var_dump("set-cookie: " . $cookie);

string(7) "session"
string(32) "7b6f532a60bc0786fdfc42307649d634"
bool(true)
string(70) "set-cookie: session=7b6f532a60bc0786fdfc42307649d634; Secure; HttpOnly"

Cookie

cookie 头用于从客户端发送 Cookie 到服务器。客户端在请求中发送此头部，服务器在请求包含此类头部时解析头部。客户端不得发送此类头部超过一个。因此，相应的类被称为 RequestCookie。

注意 关于 cookie 的更多信息可以在 MDN 参考 或其他来源中找到。

RequestCookie::fromHeader() 接受一个头部值并尝试解析它。如果解析成功，则返回一个 RequestCookie 实例数组。如果不成功，则返回一个空数组。不会抛出异常，因为接收到的 Cookie 总是用户输入且不受信任，根据 RFC，应丢弃格式错误的头部。

$responseCookie = new ResponseCookie("session", \bin2hex(\random_bytes(16)), $attributes);

$cookie = ResponseCookie::fromHeader($responseCookie);
$cookie = new RequestCookie("session", $cookie->getValue());

var_dump($cookie->getName());
var_dump($cookie->getValue());
var_dump("cookie: " . $cookie);

string(7) "session"
string(32) "7b6f532a60bc0786fdfc42307649d634"
string(48) "cookie: session=7b6f532a60bc0786fdfc42307649d634"

头部

此包提供了一个基于 RFC 7230 的 HTTP 头部解析器。它还提供了一个相应的头部格式化器。

解析头部

Amp\Http\Rfc7230::parseHeaders() 将原始头部解析到数组中，映射头部名称到头部值的数组。每个头部行必须以 \r\n 结尾，最后一个也是如此。

<?php

use Amp\Http\Http1\Rfc7230;

require __DIR__ . "/../vendor/autoload.php";

$rawHeaders = "Server: GitHub.com\r\n"
    . "Date: Tue, 31 Oct 2006 08:00:29 GMT\r\n"
    . "Connection: close\r\n"
    . "Content-Length: 0\r\n";

$headers = Rfc7230::parseHeaders($rawHeaders);

var_dump($headers);

array(4) {
  ["server"]=>
  array(1) {
    [0]=>
    string(10) "GitHub.com"
  }
  ["date"]=>
  array(1) {
    [0]=>
    string(29) "Tue, 31 Oct 2006 08:00:29 GMT"
  }
  ["connection"]=>
  array(1) {
    [0]=>
    string(5) "close"
  }
  ["content-length"]=>
  array(1) {
    [0]=>
    string(1) "0"
  }
}

格式化头部

Amp\Http\Rfc7230::formatHeaders() 接受一个数组，其格式与 parseHeaders() 返回的格式相同。它可防止头部注入和其他不符合规范的头部名称和值。

<?php

use Amp\Http\Cookie\ResponseCookie;use Amp\Http\Http1\Rfc7230;

require __DIR__ . "/../vendor/autoload.php";

$headers = Rfc7230::formatHeaders([
    "server" => [
        "GitHub.com",
    ],
    "location" => [
        "https://github.com/",
    ],
    "set-cookie" => [
        new ResponseCookie("session", \bin2hex(\random_bytes(16))),
        new ResponseCookie("user", "amphp"),
    ]
]);

var_dump($headers);

string(149) "server: GitHub.com
location: https://github.com/
set-cookie: session=09f1906ab952c9ae14e2c07bb714392f; HttpOnly
set-cookie: user=amphp; HttpOnly
"

版本控制

amphp/http 遵循与其他所有 amphp 包相同的 semver 语义版本规范。

注意 为了符合RFC规范而严格必需的BC（向后兼容性）破坏不被视为BC破坏。这包括如对cookie的错误引号处理等情况，RFC并不太明确。

但是，除非出于安全原因，否则不会改变宽松解析器。

安全

如果您发现任何与安全相关的问题，请通过电子邮件发送至 [email protected]，而不是使用问题跟踪器。

许可

MIT许可证（MIT）。有关更多信息，请参阅 LICENSE。