README

此存储库包含部分 PSR-7 消息实现、几个流装饰器以及一些有用的功能，如查询字符串解析。目前缺少 ServerRequestInterface 和 UploadedFileInterface；欢迎为这些功能提交拉取请求。

流实现

此包附带了一些流实现和流装饰器。

AppendStream

RingCentral\Psr7\AppendStream

按顺序从多个流中读取。

use RingCentral\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

RingCentral\Psr7\BufferStream

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

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

use RingCentral\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 RingCentral\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

RingCentral\Psr7\DroppingStream

一旦底层流的大小变得过大，就开始丢弃数据的流装饰器。

use RingCentral\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);

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

FnStream

RingCentral\Psr7\FnStream

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

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

use RingCentral\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

RingCentral\Psr7\InflateStream

使用 PHP 的 zlib.inflate 过滤器来膨胀或解压缩 gzip 内容。

此流装饰器跳过给定流的第一个 10 个字节以删除 gzip 标头，将提供的流转换为 PHP 流资源，然后附加 zlib.inflate 过滤器。然后，将流转换回 Guzzle 流资源以用作 Guzzle 流。

LazyOpenStream

RingCentral\Psr7\LazyOpenStream

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

use RingCentral\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

RingCentral\Psr7\LimitStream

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

use RingCentral\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

RingCentral\Psr7\MultipartStream

当读取时返回流式多部分或 multipart/form-data 流的字节的流。

NoSeekStream

RingCentral\Psr7\NoSeekStream

NoSeekStream 包装了一个流，不允许进行查找。

use RingCentral\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

RingCentral\Psr7\PumpStream

提供只读流，从 PHP 可调用对象中提取数据。

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

实现流装饰器

通过 RingCentral\Psr7\StreamDecoratorTrait，创建流装饰器非常简单。这个特性提供了通过代理到底层流来实现 Psr\Http\Message\StreamInterface 方法的功能。只需使用 StreamDecoratorTrait 并实现您自己的自定义方法。

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

use Psr\Http\Message\StreamInterface;
use RingCentral\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 RingCentral\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 流包装器

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

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

use RingCentral\Psr7\StreamWrapper;

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

函数 API

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

`函数 str`

function str(MessageInterface $message)

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

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

`函数 uri_for`

function uri_for($uri)

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

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

`函数 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 = RingCentral\Psr7\stream_for('foo');
$stream = RingCentral\Psr7\stream_for(fopen('/path/to/file', 'r'));

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

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

`函数 parse_header`

function parse_header($header)

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

`函数 normalize_header`

function normalize_header($header)

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

`函数 modify_request`

function modify_request(RequestInterface $request, array $changes)

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

更改可以是以下之一

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

`function rewind_body`

function rewind_body(MessageInterface $message)

尝试重置消息正文，并在失败时抛出异常。如果调用tell()返回的值不是0，则消息正文才会被重置。

`function try_fopen`

function try_fopen($filename, $mode)

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

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

`function copy_to_string`

function copy_to_string(StreamInterface $stream, $maxLen = -1)

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

`function copy_to_stream`

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

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

`function hash`

function hash(StreamInterface $stream, $algo, $rawOutput = false)

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

`function readline`

function readline(StreamInterface $stream, $maxLength = null)

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

`function parse_request`

function parse_request($message)

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

`function parse_server_request`

function parse_server_request($message, array $serverParams = array())

将请求消息字符串解析为服务器端请求对象。

`function parse_response`

function parse_response($message)

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

`function parse_query`

function parse_query($str, $urlEncoding = true)

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

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

`function build_query`

function build_query(array $params, $encoding = PHP_QUERY_RFC3986)

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

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

`function mimetype_from_filename`

function mimetype_from_filename($filename)

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

`function mimetype_from_extension`

function mimetype_from_extension($extension)

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

静态URI方法

RingCentral\Psr7\Uri类有几个静态方法来操作URI。

`RingCentral\Psr7\Uri::removeDotSegments`

public static function removeDotSegments($path) -> UriInterface

从路径中删除点段并返回新的路径。

See http://tools.ietf.org/html/rfc3986#section-5.2.4

`RingCentral\Psr7\Uri::resolve`

public static function resolve(UriInterface $base, $rel) -> UriInterface

解析基本URI和相对URI，并返回一个新的URI。

See http://tools.ietf.org/html/rfc3986#section-5

`RingCentral\Psr7\Uri::withQueryValue`

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

创建一个新的URI，包含特定的查询字符串值。

如果存在与提供的键完全匹配的现有查询字符串值，则会将其移除并替换为给定的键值对。

注意：此函数将“=”转换为“%3D”，将“&”转换为“%26”。

`RingCentral\Psr7\Uri::withoutQueryValue`

public static function withoutQueryValue(UriInterface $uri, $key, $value) -> UriInterface

创建一个新的URI，移除特定的查询字符串值。

如果存在与提供的键完全匹配的现有查询字符串值，则会将其移除。

注意：此函数将“=”转换为“%3D”，将“&”转换为“%26”。

`RingCentral\Psr7\Uri::fromParts`

public static function fromParts(array $parts) -> UriInterface

从parse_url部分的哈希中创建一个RingCentral\Psr7\Uri对象。

未实现

本项目未实现PSR-7的一些方面。欢迎对这些功能的任何一项提交pull request。

Psr\Http\Message\ServerRequestInterface
Psr\Http\Message\UploadedFileInterface

ringcentral / psr7

维护者

详细信息

README

流实现

AppendStream

BufferStream

CachingStream

DroppingStream

FnStream

InflateStream

LazyOpenStream

LimitStream

MultipartStream

NoSeekStream

PumpStream

实现流装饰器

PHP 流包装器

函数 API

函数 str

函数 uri_for

函数 stream_for

函数 parse_header

函数 normalize_header

函数 modify_request

function rewind_body

function try_fopen

function copy_to_string

function copy_to_stream

function hash

function readline

function parse_request

function parse_server_request

function parse_response

function parse_query

function build_query

function mimetype_from_filename

function mimetype_from_extension