README

此仓库包含完整的PSR-7 消息实现、多个流装饰器以及一些有用的功能，如查询字符串解析。

流实现

此包附带多个流实现和流装饰器。

AppendStream

GuzzleHttp\Psr7\AppendStream

从多个流中按顺序读取。

use GuzzleHttp\Psr7;

$a = Psr7\stream_for('abc, ');
$b = Psr7\stream_for('123.');
$composed = new Psr7\AppendStream([$a, $b]);

$composed->addStream(Psr7\stream_for(' Above all listen to me'));

echo $composed; // abc, 123. Above all listen to me.

BufferStream

GuzzleHttp\Psr7\BufferStream

提供可以写入以填充缓冲区并从其中读取以从缓冲区中删除字节的缓冲区流。

此流返回一个 "hwm" 元数据值，该值告诉上游消费者流的配置高水位标记或缓冲区的最大首选大小。

use GuzzleHttp\Psr7;

// When more than 1024 bytes are in the buffer, it will begin returning
// false to writes. This is an indication that writers should slow down.
$buffer = new Psr7\BufferStream(1024);

CachingStream

CachingStream 用于在非可寻址流上允许在之前读取的字节上寻求。这可以在由于需要回滚流（例如，由于重定向）而无法传输非可寻址实体主体时很有用。从远程流读取的数据将缓存在 PHP 临时流中，以便首先在内存中缓存之前读取的字节，然后写入磁盘。

use GuzzleHttp\Psr7;

$original = Psr7\stream_for(fopen('http://www.google.com', 'r'));
$stream = new Psr7\CachingStream($original);

$stream->read(1024);
echo $stream->tell();
// 1024

$stream->seek(0);
echo $stream->tell();
// 0

DroppingStream

GuzzleHttp\Psr7\DroppingStream

当底层流的大小变得太满时开始丢弃数据的流装饰器。

use GuzzleHttp\Psr7;

// Create an empty stream
$stream = Psr7\stream_for();

// Start dropping data when the stream has more than 10 bytes
$dropping = new Psr7\DroppingStream($stream, 10);

$dropping->write('01234567890123456789');
echo $stream; // 0123456789

FnStream

GuzzleHttp\Psr7\FnStream

基于函数哈希的组合流实现。

允许在不需要为简单的扩展点创建具体类的情况下轻松测试和扩展提供的流。

use GuzzleHttp\Psr7;

$stream = Psr7\stream_for('hi');
$fnStream = Psr7\FnStream::decorate($stream, [
    'rewind' => function () use ($stream) {
        echo 'About to rewind - ';
        $stream->rewind();
        echo 'rewound!';
    }
]);

$fnStream->rewind();
// Outputs: About to rewind - rewound!

InflateStream

GuzzleHttp\Psr7\InflateStream

使用 PHP 的 zlib.inflate 过滤器来填充 zlib（HTTP deflate，RFC1950）或 gzipped（RFC1952）内容。

此流装饰器将提供的流转换为 PHP 流资源，然后附加 zlibinflate 过滤器。然后将流转换回 Guzzle 流资源以用作 Guzzle 流。

LazyOpenStream

GuzzleHttp\Psr7\LazyOpenStream

在流上执行 IO 操作后才懒洋洋地读取或写入文件。

use GuzzleHttp\Psr7;

$stream = new Psr7\LazyOpenStream('/path/to/file', 'r');
// The file has not yet been opened...

echo $stream->read(10);
// The file is opened and read from only when needed.

LimitStream

GuzzleHttp\Psr7\LimitStream

LimitStream 可用于读取现有流对象的部分或切片。这可以将大文件分割成更小的部分，以便分块发送（例如，Amazon S3 的分片上传 API）。

use GuzzleHttp\Psr7;

$original = Psr7\stream_for(fopen('/tmp/test.txt', 'r+'));
echo $original->getSize();
// >>> 1048576

// Limit the size of the body to 1024 bytes and start reading from byte 2048
$stream = new Psr7\LimitStream($original, 1024, 2048);
echo $stream->getSize();
// >>> 1024
echo $stream->tell();
// >>> 0

MultipartStream

GuzzleHttp\Psr7\MultipartStream

当读取时返回流式多部分或多部分/表单数据流的字节的流。

NoSeekStream

GuzzleHttp\Psr7\NoSeekStream

NoSeekStream 包装一个流，不允许寻找。

use GuzzleHttp\Psr7;

$original = Psr7\stream_for('foo');
$noSeek = new Psr7\NoSeekStream($original);

echo $noSeek->read(3);
// foo
var_export($noSeek->isSeekable());
// false
$noSeek->seek(0);
var_export($noSeek->read(3));
// NULL

PumpStream

GuzzleHttp\Psr7\PumpStream

提供从 PHP 可调用函数中泵送数据的只读流。

当调用提供的可调用函数时，PumpStream 将要读取的数据量传递给可调用函数。可调用函数可以选择忽略此值，并返回少于或多于请求的字节数。由提供的可调用函数返回的任何额外数据都会在内部缓冲，直到通过使用 PumpStream 的 read() 函数排空。提供的可调用函数必须在没有更多数据可读取时返回 false。

实现流装饰器

创建流装饰器非常简单，多亏了 GuzzleHttp\Psr7\StreamDecoratorTrait。此特质通过代理到底层流来提供实现 Psr\Http\Message\StreamInterface 的方法。只需 use StreamDecoratorTrait 并实现自定义方法即可。

例如，假设我们希望在每次从流中读取最后一个字节时调用一个特定的函数。这可以通过重写read()方法来实现。

use Psr\Http\Message\StreamInterface;
use GuzzleHttp\Psr7\StreamDecoratorTrait;

class EofCallbackStream implements StreamInterface
{
    use StreamDecoratorTrait;

    private $callback;

    public function __construct(StreamInterface $stream, callable $cb)
    {
        $this->stream = $stream;
        $this->callback = $cb;
    }

    public function read($length)
    {
        $result = $this->stream->read($length);

        // Invoke the callback when EOF is hit.
        if ($this->eof()) {
            call_user_func($this->callback);
        }

        return $result;
    }
}

此装饰器可以添加到任何现有流中，并按如下方式使用

use GuzzleHttp\Psr7;

$original = Psr7\stream_for('foo');

$eofStream = new EofCallbackStream($original, function () {
    echo 'EOF!';
});

$eofStream->read(2);
$eofStream->read(1);
// echoes "EOF!"
$eofStream->seek(0);
$eofStream->read(3);
// echoes "EOF!"

PHP StreamWrapper

如果您需要使用PSR-7流作为PHP流资源，可以使用GuzzleHttp\Psr7\StreamWrapper类。

使用GuzzleHttp\Psr7\StreamWrapper::getResource()方法从PSR-7流创建PHP流。

use GuzzleHttp\Psr7\StreamWrapper;

$stream = GuzzleHttp\Psr7\stream_for('hello!');
$resource = StreamWrapper::getResource($stream);
echo fread($resource, 6); // outputs hello!

函数API

在GuzzleHttp\Psr7命名空间下提供了各种函数。

`function str`

function str(MessageInterface $message)

返回HTTP消息的字符串表示。

$request = new GuzzleHttp\Psr7\Request('GET', 'http://example.com');
echo GuzzleHttp\Psr7\str($request);

`function uri_for`

function uri_for($uri)

此函数接受一个字符串或Psr\Http\Message\UriInterface，并返回一个UriInterface对象，表示给定的值。如果值已经是UriInterface，则原样返回。

$uri = GuzzleHttp\Psr7\uri_for('http://example.com');
assert($uri === GuzzleHttp\Psr7\uri_for($uri));

`function stream_for`

function stream_for($resource = '', array $options = [])

根据输入类型创建一个新的流。

选项是一个关联数组，可以包含以下键

- metadata: 自定义元数据的数组。
- size: 流的大小。

此方法接受以下$resource类型

Psr\Http\Message\StreamInterface: 原样返回值。
string: 创建一个使用给定字符串作为内容的流对象。
resource: 创建一个包装给定PHP流资源的流对象。
Iterator: 如果提供的值实现了Iterator，则创建一个包装给定可迭代对象的只读流对象。每次从流中读取时，迭代器中的数据将填充缓冲区，并且将连续调用直到缓冲区等于请求的读取大小。后续的读取调用将首先从缓冲区中读取，然后调用底层迭代器的next，直到迭代器耗尽。
object with __toString(): 如果对象有__toString()方法，则对象将被转换为字符串，然后返回一个使用字符串值的流。
NULL: 当传递null时，返回一个空流对象。
callable: 当传递可调用时，创建一个只读流对象，该对象调用给定的可调用函数。可调用函数使用要读取的建议字节数进行调用。可调用函数可以返回任意数量的字节，但在没有更多数据返回时必须返回false。包装可调用的流对象将调用可调用函数，直到请求的字节数可用。任何额外的字节将被缓冲并用于后续的读取。

$stream = GuzzleHttp\Psr7\stream_for('foo');
$stream = GuzzleHttp\Psr7\stream_for(fopen('/path/to/file', 'r'));

$generator = function ($bytes) {
    for ($i = 0; $i < $bytes; $i++) {
        yield ' ';
    }
}

$stream = GuzzleHttp\Psr7\stream_for($generator(100));

`function parse_header`

function parse_header($header)

解析包含";"分隔数据的头值数组，将其解析为表示头键值对的关联数组数组。当参数不包含值，但只包含键时，此函数将注入一个具有''字符串值的键。

`function normalize_header`

function normalize_header($header)

将可能包含逗号分隔头的数组转换为不包含逗号分隔值的头数组。

`function modify_request`

function modify_request(RequestInterface $request, array $changes)

克隆并修改具有给定更改的请求。此方法对于减少更改消息所需克隆的数量非常有用。

更改可以是以下之一

method: (string) 更改HTTP方法。
set_headers: (array) 设置给定的头。
remove_headers: (array) 删除给定的头。
body: (mixed) 设置给定的主体。
uri: (UriInterface) 设置URI。
query: (string) 设置URI的查询字符串值。
版本：(字符串) 设置协议版本。

`功能 rewind_body`

功能 rewind_body(MessageInterface $message)

尝试回滚消息体，失败时抛出异常。只有当调用 tell() 返回值不是 0 时，消息体才会被回滚。

`功能 try_fopen`

功能 try_fopen($filename, $mode)

使用文件名安全地打开 PHP 流资源。

当 fopen 失败时，PHP 通常会引发警告。此函数添加一个错误处理程序，检查错误并抛出异常。

`功能 copy_to_string`

功能 copy_to_string(StreamInterface $stream, $maxLen = -1)

将流的内容复制到字符串中，直到读取给定的字节数。

`功能 copy_to_stream`

功能 copy_to_stream(StreamInterface $source, StreamInterface $dest, $maxLen = -1)

将流的内容复制到另一个流中，直到读取给定的字节数。

`功能 hash`

功能 hash(StreamInterface $stream, $algo, $rawOutput = false)

计算流的哈希值。此方法读取整个流以计算滚动哈希（基于 PHP 的 hash_init 函数）。

`功能 readline`

功能 readline(StreamInterface $stream, $maxLength = null)

从流中读取一行，直到最大允许的缓冲区长度。

`功能 parse_request`

功能 parse_request($message)

将请求消息字符串解析为请求对象。

`功能 parse_response`

功能 parse_response($message)

将响应消息字符串解析为响应对象。

`功能 parse_query`

功能 parse_query($str, $urlEncoding = true)

将查询字符串解析为关联数组。

如果找到相同的键的多个值，则该键值对的值将成为一个数组。此函数不会将嵌套 PHP 风格数组解析为关联数组（例如，foo[a]=1&foo[b]=2 将被解析为 ['foo[a]' => '1', 'foo[b]' => '2']）。

`功能 build_query`

功能 build_query(array $params, $encoding = PHP_QUERY_RFC3986)

从键值对数组构建查询字符串。

此函数可以使用 parse_query() 的返回值构建查询字符串。当遇到数组时，此函数不会修改提供的键（如 http_build_query 会做的那样）。

`功能 mimetype_from_filename`

功能 mimetype_from_filename($filename)

通过查看扩展名确定文件的 MIME 类型。

`功能 mimetype_from_extension`

功能 mimetype_from_extension($extension)

将文件扩展名映射到 MIME 类型。

`功能 get_message_body_summary`

功能 get_message_body_summary(MessageInterface $message, $truncateAt = 120)

获取消息体的简短摘要。

如果响应不可打印，则返回 null。

附加 URI 方法

除了以 GuzzleHttp\Psr7\Uri 类的形式实现的标准的 Psr\Http\Message\UriInterface 实现之外，此库在处理 URI 时还提供了静态方法以提供额外的功能。

URI 类型

Psr\Http\Message\UriInterface 的实例可以是绝对 URI 或相对引用。绝对 URI 有一个方案。相对引用用于表示相对于另一个 URI（基础 URI）的 URI。相对引用可以根据 RFC 3986 第 4.2 节分为几种形式。

网络路径引用，例如 //example.com/path
绝对路径引用，例如 /path
相对路径引用，例如 subpath

以下方法可以用来识别 URI 的类型。

`GuzzleHttp\Psr7\Uri::isAbsolute`

public static function isAbsolute(UriInterface $uri): bool

是否 URI 是绝对的，即它有一个方案。

`GuzzleHttp\Psr7\Uri::isNetworkPathReference`

public static function isNetworkPathReference(UriInterface $uri): bool

是否 URI 是网络路径引用。以两个斜杠字符开头的相对引用被称为网络路径引用。

`GuzzleHttp\Psr7\Uri::isAbsolutePathReference`

public static function isAbsolutePathReference(UriInterface $uri): bool

判断URI是否为绝对路径引用。以单个斜杠字符开头的相对引用称为绝对路径引用。

`GuzzleHttp\Psr7\Uri::isRelativePathReference`

public static function isRelativePathReference(UriInterface $uri): bool

判断URI是否为相对路径引用。不以斜杠字符开头的相对引用称为相对路径引用。

`GuzzleHttp\Psr7\Uri::isSameDocumentReference`

public static function isSameDocumentReference(UriInterface $uri, UriInterface $base = null): bool

判断URI是否为同一文档引用。同一文档引用是指，除其片段组件外，与基本URI完全相同的URI。当没有提供基本URI时，仅考虑空URI引用（除片段外）为同一文档引用。

URI组件

用于处理URI组件的额外方法。

`GuzzleHttp\Psr7\Uri::isDefaultPort`

public static function isDefaultPort(UriInterface $uri): bool

判断URI是否具有当前方案的默认端口号。Psr\Http\Message\UriInterface::getPort可能返回null或标准端口号。此方法可以独立于实现使用。

`GuzzleHttp\Psr7\Uri::composeComponents`

public static function composeComponents($scheme, $authority, $path, $query, $fragment): string

根据RFC 3986第5.3节从URI的不同组件组成URI引用字符串。通常不需要手动调用此方法，而是通过Psr\Http\Message\UriInterface::__toString间接使用。

`GuzzleHttp\Psr7\Uri::fromParts`

public static function fromParts(array $parts): UriInterface

从parse_url组件的哈希中创建URI。

`GuzzleHttp\Psr7\Uri::withQueryValue`

public static function withQueryValue(UriInterface $uri, $key, $value): UriInterface

创建一个新的URI，其中包含特定的查询字符串值。任何与提供的键完全匹配的现有查询字符串值都将被移除并替换为给定的键值对。null值将设置查询字符串键而没有值，例如“key”而不是“key=value”。

`GuzzleHttp\Psr7\Uri::withQueryValues`

public static function withQueryValues(UriInterface $uri, array $keyValueArray): UriInterface

创建一个新的URI，其中包含多个查询字符串值。它与withQueryValue()的行为相同，但用于键 => 值的关联数组。

`GuzzleHttp\Psr7\Uri::withoutQueryValue`

public static function withoutQueryValue(UriInterface $uri, $key): UriInterface

创建一个新的URI，其中移除了特定的查询字符串值。任何与提供的键完全匹配的现有查询字符串值都将被移除。

引用解析

GuzzleHttp\Psr7\UriResolver提供了根据RFC 3986第5节在基本URI的上下文中解析URI引用的方法。例如，这也是当基于当前请求URI解析网站中的链接时，网络浏览器所做的事情。

`GuzzleHttp\Psr7\UriResolver::resolve`

public static function resolve(UriInterface $base, UriInterface $rel): UriInterface

将相对URI转换为一个新的URI，该URI相对于基本URI进行解析。

`GuzzleHttp\Psr7\UriResolver::removeDotSegments`

public static function removeDotSegments(string $path): string

根据RFC 3986第5.2.4节从路径中移除点段并返回新的路径。

`GuzzleHttp\Psr7\UriResolver::relativize`

public static function relativize(UriInterface $base, UriInterface $target): UriInterface

返回从基本URI到目标URI的相对引用。此方法是resolve()的对应方法

(string) $target === (string) UriResolver::resolve($base, UriResolver::relativize($base, $target))

一个用例是使用当前请求URI作为基本URI，然后在文档中生成相对链接，以减小文档大小或提供自包含的下载文档存档。

$base = new Uri('http://example.com/a/b/');
echo UriResolver::relativize($base, new Uri('http://example.com/a/b/c'));  // prints 'c'.
echo UriResolver::relativize($base, new Uri('http://example.com/a/x/y'));  // prints '../x/y'.
echo UriResolver::relativize($base, new Uri('http://example.com/a/b/?q')); // prints '?q'.
echo UriResolver::relativize($base, new Uri('http://example.org/a/b/'));   // prints '//example.org/a/b/'.

规范化和比较

GuzzleHttp\Psr7\UriNormalizer 提供了根据 RFC 3986 第 6 节标准化并比较 URI 的方法。

`GuzzleHttp\Psr7\UriNormalizer::normalize`

public static function normalize(UriInterface $uri, $flags = self::PRESERVING_NORMALIZATIONS): UriInterface

返回一个标准化的 URI。方案和主机部分已根据 PSR-7 UriInterface 规范转换为小写。此方法通过 $flags 参数添加额外的标准化，该参数是应用标准化的位掩码。以下是一些可用的标准化选项

UriNormalizer::PRESERVING_NORMALIZATIONS

默认的标准化，仅包括保留语义的标准化。
UriNormalizer::CAPITALIZE_PERCENT_ENCODING

百分编码三元组（例如，"%3A"）中的所有字母不区分大小写，应大写。

示例： http://example.org/a%c2%b1b → http://example.org/a%C2%B1b
UriNormalizer::DECODE_UNRESERVED_CHARACTERS

解码未保留字符的百分编码八位字节。为了保持一致性，在 URI 生产者中不应创建范围在 ALPHA (%41–%5A 和 %61–%7A)、DIGIT (%30–%39)、连字符 (%2D)、点 (%2E)、下划线 (%5F) 或波浪号 (%7E) 的百分编码八位字节，当在 URI 中找到时，应由 URI 标准化器解码为相应的未保留字符。

示例： http://example.org/%7Eusern%61me/ → http://example.org/~username/
UriNormalizer::CONVERT_EMPTY_PATH

将空路径转换为 "/" 用于 http 和 https URI。

示例： http://example.org → http://example.org/
UriNormalizer::REMOVE_DEFAULT_HOST

从 URI 中移除给定 URI 方案的默认主机。只有 "file" 方案定义默认主机 "localhost"。所有 file:/myfile、file:///myfile 和 file://localhost/myfile 根据 RFC 3986 是等价的。

示例： file://localhost/myfile → file:///myfile
UriNormalizer::REMOVE_DEFAULT_PORT

从 URI 中移除给定 URI 方案的默认端口。

示例： http://example.org:80/ → http://example.org/
UriNormalizer::REMOVE_DOT_SEGMENTS

移除不必要的点段。相对路径引用中的点段不会被移除，因为这会改变 URI 引用的语义。

示例： http://example.org/../a/b/../c/./d.html → http://example.org/a/c/d.html
UriNormalizer::REMOVE_DUPLICATE_SLASHES

将包含两个或更多相邻斜杠的路径转换为一个。Web 服务器通常忽略重复的斜杠，并认为这些 URI 是等价的。但在理论上，这些 URI 不需要是等价的。因此，这种标准化可能会改变语义。编码的斜杠 (%2F) 不会被移除。

示例： http://example.org//foo///bar.html → http://example.org/foo/bar.html
UriNormalizer::SORT_QUERY_PARAMETERS

按字母顺序对查询参数及其值进行排序。然而，URI 中参数的顺序可能很重要（这不是标准定义的）。因此，这种标准化可能不安全，并可能改变 URI 的语义。

示例： ?lang=en&article=fred → ?article=fred&lang=en

`GuzzleHttp\Psr7\UriNormalizer::isEquivalent`

public static function isEquivalent(UriInterface $uri1, UriInterface $uri2, $normalizations = self::PRESERVING_NORMALIZATIONS): bool

判断两个 URI 是否可以被认为是等价的。在比较之前，两个 URI 都会自动根据给定的 $normalizations 位掩码进行标准化。此方法还接受相对 URI 引用，当它们等价时返回 true。这当然假设它们将与相同的基 URI 一起解析。如果这不是这种情况，相对引用的等价或差异的判断没有任何意义。

xiaoyi510 / psr7

维护者

详细信息

README

流实现

AppendStream

BufferStream

CachingStream

DroppingStream

FnStream

InflateStream

LazyOpenStream

LimitStream

MultipartStream

NoSeekStream

PumpStream

实现流装饰器

PHP StreamWrapper

函数API

function str

function uri_for

function stream_for

function parse_header

function normalize_header

function modify_request

功能 rewind_body

功能 try_fopen

功能 copy_to_string

功能 copy_to_stream

功能 hash

功能 readline

功能 parse_request

功能 parse_response

功能 parse_query

功能 build_query

功能 mimetype_from_filename

功能 mimetype_from_extension

功能 get_message_body_summary