README

帮助进行套接字操作。

构建状态

安装

stubbles/peer 以 Composer 包的形式分发。要将它作为您的包的依赖项安装，请使用以下命令

composer require "stubbles/peer": "^10.0"

要求

stubbles/peer 至少需要 PHP 8.2。

与 URI 一起工作

有时将 URI 封装在类中很有用，该类提供用于处理该 URI 的方法。Stubbles Core 为此类情况提供了 stubbles\peer\Uri。

可以通过 Uri::fromString('ftp://user@example.net/'); 创建新实例。以下规则适用

• 如果提供的 uri 字符串为空，则不返回实例，而是返回 null。
• 如果提供的 uri 字符串不是一个有效的 URI，则会抛出 stubbles\peer\MalformedUri。
• 在其他所有情况下，将返回 stubbles\peer\Uri 的一个实例。
• 从版本 8.0.0 开始，不建议在 URI 中使用密码，并且将在 9.0.0 中移除对 URI 中密码的支持。通常，协议提供其他更好和更安全的方法来传输密码，因为将密码用于 URI 本身是不安全的。

为了使 uri 字符串成为有效的 URI，它必须遵守在 RFC 3986 中规定的规范。

请注意，将标准化主机名，这意味着如果给定的主机名为例如 eXAMple.net，它将被标准化为 example.net，并且始终以标准化形式返回。

对于方法，以下规则适用

• hasDnsRecord() 如果 URI 不包含主机，则返回 false。
• hasDnsRecord() 对于 localhost、127.0.0.1 和 [::1] 始终返回 true。
• hasDefaultPort() 当指定端口时返回 false，即使它可能是方案的默认端口。此方法旨在用于提供特定协议的附加方法的子类。

URI 实例只能更改其 URI 参数。无法更改 URI 的方案、主机、用户、密码、端口或片段。

与 HTTP URI 一起工作

尽管 URI 的基本实现已经提供了在处理 URI 时有用的帮助，但有时需要对 HTTP URI 提供更好的支持。stubbles/peer 为此类情况提供了 stubbles\peer\http\HttpUri。

可以通过 HttpUri::fromString('http://example.net/'); 创建新实例。以下规则适用

• 如果提供的 uri 字符串为空，则不返回实例，而是返回 null。
• 如果提供的 uri 字符串不是一个有效的 HTTP URI，则会抛出 stubbles\peer\MalformedUri。
• 在其他所有情况下，将返回 stubbles\peer\http\HttpUri 的一个实例。

为了使 uri 字符串成为有效的 URI，它必须遵守在 RFC 7230 中规定的规范。任何不属于 http 或 https 方案的 uri 字符串都将被拒绝，并引发 stubbles\peer\MalformedUri。

此外，可以使用 HttpUri::fromParts($scheme, $host, $port = null, $path = '/', $queryString = null) 创建实例。 (自版本 4.0.0 可用。)

特定方法的规则

• hasDefaultPort() 如果方案是 http 且端口是 80，则返回 true。如果没有提供原始端口，则假定端口为 80。如果方案是 https 且端口是 443，则该方法也返回 true。如果没有提供原始端口，则假定端口为 443。在任何其他情况下，该方法返回 false。
• port() 方法将返回原始提供的端口。如果没有提供，并且方案为 http，则返回值将为 80，如果方案为 https，则返回值为 443。

更改 HTTP URI 的部分

HttpUri 的实例只能更改它们的 URI 参数。无法更改 URI 的主机、用户、密码、端口或片段。此外，还可以更改方案，但这将返回一个新的实例

• toHttp()：如果方案为 http，将返回相同的实例。如果方案为 https，则将返回一个新的实例，该实例具有相同的 URI 但方案为 http。
• toHttps()：如果方案为 https，则返回相同的实例。如果方案为 http，则返回一个新的实例，该实例具有相同的 URI 但方案为 https。

可以使用 isHttp() 和 isHttps() 检查当前方案。

建立到 HTTP URI 的连接

此外，该类还提供了建立到名称 HTTP URI 的连接的可能性

• openSocket() 将创建一个 stubbles\peer\Socket 实例，可以连接到该实例。有关更多详细信息，请参阅关于套接字的部分。
• connect() 提供了具有完整 HTTP 连接的高级访问权限。该方法可以可选地接受一个 stubbles\peer\HeaderList 实例，其中将应用标题到请求中。

建立 HTTP 连接

可以通过以下方式对目标 URI 执行 HTTP 请求

$response = $httpUri->connect()
        ->asUserAgent('Not Mozilla')
        ->timeout(5)
        ->usingHeader('X-Money', 'Euro')
        ->get();

请注意，对 connect() 的调用不会打开连接，但仅在本地建立连接。相反，它可以用来添加更多标题到请求中：用户代理、引用者、Cookie 或任何其他标题。只有最后一种方法真正打开连接。目前，支持 GET、HEAD、POST、PUT 和 DELETE 请求

$response = $httpUri->connect()->get();
$response = $httpUri->connect()->head();
$response = $httpUri->connect()->post($postBody);
$response = $httpUri->connect()->put($putBody);
$response = $httpUri->connect()->delete();

对于 POST 和 PUT，有一个必需的参数，该参数应包含 post/put 正文。对于 POST，还可以提供关联的 array，它将被转换为表单 post 值，这将导致自动添加 Content-type: application/x-www-form-urlencoded 标题到请求中。

然后可以读取响应。它提供了访问 HTTP 响应所有单个细节的方法。

套接字操作

可以使用 stubbles\peer\Socket 执行套接字操作。通过构造函数提供主机来创建套接字，并可选地提供端口。如果没有指定端口，它将回退到端口 80。

在构造时仅创建套接字实例。要实际打开连接，必须调用 connect() 方法。可选地，可以提供建立连接的超时时间，如果没有给出，则默认为 2 秒。成功建立连接后，它将返回一个 stubbles\peer\Stream 实例，该实例提供从套接字读取和写入的方法。

其他实用程序类

stubbles\peer\HeaderList

该类提供了使用标题的可能性，主要解析包含标题的字符串并维护标题列表。

stubbles\peer\http\AcceptHeader

该类可以解析 HTTP 的 accept header 并提供检查是否接受某种类型、其优先级以及如果将 accept header 与类型选择进行比较以找到最佳匹配的访问权限。它可以处理 Accept、Accept-Charset 和 Accept-Encoding。

stubbles\peer\ParsedUri

以 uri 字符串作为构造函数参数，并提供了访问 uri 的各个部分。与 stubbles\peer\Uri 和 stubbles\peer\http\HttpUri 不同，不会在 url 字符串上执行检查，这意味着可以从无效的 url 字符串构造实例，这是其他两个类所不允许的。

stubbles\peer\QueryString

接受查询字符串作为构造参数，并提供对查询字符串中所有参数的访问权限，以修改和删除它们或添加其他参数；并从这些参数中重新构建完整的查询字符串。

stubbles\peer\IpAddress

自4.0.0版本起可用

表示IP地址以及可能的IP地址操作。

与stubbles/values集成

如果存在stubbles/values包，则会自动添加对stubbles\values\Parse的识别，以解析http URI到stubbles\peer\http\HttpUri实例。

此外，还添加了对stubbles\values\Value的一些检查（自7.1.0版本起可用）

• isMailAddress()
• isIpAddress()
• isIpV4Address()
• isIpV6Address()
• isHttpUri()
• isExistingHttpUri()