PSR-7 消息实现,并提供常用实用方法

维护者

详细信息

github.com/guzzle/psr7

源代码

问题

安装数: 739,230,767

依赖项: 2,780

建议者: 67

安全: 2

星星: 7,858

观察者: 40

分支: 297

开放问题: 9

2.7.0 2024-07-18 11:15 UTC

README

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

CI Static analysis

特性

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

安装

composer require guzzlehttp/psr7

版本指导

AppendStream

GuzzleHttp\Psr7\AppendStream

从多个流中按顺序读取。

use GuzzleHttp\Psr7;

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

$composed->addStream(Psr7\Utils::streamFor(' 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\Utils::streamFor(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\Utils::streamFor();

// 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\Utils::streamFor('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 的 zlibinflate 过滤器来膨胀 zlib(HTTP 压缩,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\Utils::streamFor(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

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

NoSeekStream

GuzzleHttp\Psr7\NoSeekStream

NoSeekStream 包装一个流,不允许寻址。

use GuzzleHttp\Psr7;

$original = Psr7\Utils::streamFor('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;

    private $stream;

    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()) {
            ($this->callback)();
        }

        return $result;
    }
}

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

use GuzzleHttp\Psr7;

$original = Psr7\Utils::streamFor('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\Utils::streamFor('hello!');
$resource = StreamWrapper::getResource($stream);
echo fread($resource, 6); // outputs hello!

静态API

GuzzleHttp\Psr7命名空间下有各种静态方法可用。

GuzzleHttp\Psr7\Message::toString

public static function toString(MessageInterface $message): string

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

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

GuzzleHttp\Psr7\Message::bodySummary

public static function bodySummary(MessageInterface $message, int $truncateAt = 120): string|null

获取消息体的简短摘要。

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

GuzzleHttp\Psr7\Message::rewindBody

public static function rewindBody(MessageInterface $message): void

尝试重置消息体,如果失败则抛出异常。

只有当tell()调用的返回值不为0时,才会重置消息体。

GuzzleHttp\Psr7\Message::parseMessage

public static function parseMessage(string $message): array

将HTTP消息解析为关联数组。

该数组包含“start-line”键,包含消息的开始行,“headers”键包含头部数组值的关联数组,以及“body”键包含消息体。

GuzzleHttp\Psr7\Message::parseRequestUri

public static function parseRequestUri(string $path, array $headers): string

为HTTP请求消息构建一个URI。

GuzzleHttp\Psr7\Message::parseRequest

public static function parseRequest(string $message): Request

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

GuzzleHttp\Psr7\Message::parseResponse

public static function parseResponse(string $message): Response

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

GuzzleHttp\Psr7\Header::parse

public static function parse(string|array $header): array

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

GuzzleHttp\Psr7\Header::splitList

public static function splitList(string|string[] $header): string[]

将定义为包含逗号分隔列表的HTTP头部拆分为每个单独的值

$knownEtags = Header::splitList($request->getHeader('if-none-match'));

示例头部包括acceptcache-controlif-none-match

GuzzleHttp\Psr7\Header::normalize (已弃用)

public static function normalize(string|array $header): array

Header::normalize()已被弃用,改为使用Header::splitList(),它具有清理后的API和改进的文档。

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

GuzzleHttp\Psr7\Query::parse

public static function parse(string $str, int|bool $urlEncoding = true): array

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

如果发现同一键的多个值,该键值对的值将变成一个数组。此函数不会将嵌套的PHP风格数组解析为关联数组(例如,foo[a]=1&foo[b]=2将被解析为['foo[a]' => '1', 'foo[b]' => '2'])。

GuzzleHttp\Psr7\Query::build

public static function build(array $params, int|false $encoding = PHP_QUERY_RFC3986, bool $treatBoolsAsInts = true): string

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

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

GuzzleHttp\Psr7\Utils::caselessRemove

public static function caselessRemove(iterable $keys, $keys, array $data): array

从数据中按键(不区分大小写)移除指定的项。

GuzzleHttp\Psr7\Utils::copyToStream

public static function copyToStream(StreamInterface $source, StreamInterface $dest, int $maxLen = -1): void

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

GuzzleHttp\Psr7\Utils::copyToString

public static function copyToString(StreamInterface $stream, int $maxLen = -1): string

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

GuzzleHttp\Psr7\Utils::hash

public static function hash(StreamInterface $stream, string $algo, bool $rawOutput = false): string

计算流的哈希值。

此方法通过PHP的hash_init函数计算滚动哈希,读取整个流。

GuzzleHttp\Psr7\Utils::modifyRequest

public static function modifyRequest(RequestInterface $request, array $changes): RequestInterface

克隆并修改带有给定更改的请求。

此方法对于减少修改消息所需克隆的数量很有用。

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

GuzzleHttp\Psr7\Utils::readLine

public static function readLine(StreamInterface $stream, ?int $maxLength = null): string

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

GuzzleHttp\Psr7\Utils::redactUserInfo

public static function redactUserInfo(UriInterface $uri): UriInterface

从URI的用户信息部分中删除密码。

GuzzleHttp\Psr7\Utils::streamFor

public static function streamFor(resource|string|null|int|float|bool|StreamInterface|callable|\Iterator $resource = '', array $options = []): StreamInterface

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

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

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

此方法接受以下$resource类型

  • Psr\Http\Message\StreamInterface: 返回值不变。
  • string: 创建一个使用给定字符串作为内容的流对象。
  • resource: 创建一个包装给定PHP流资源的流对象。
  • Iterator: 如果提供的值实现了Iterator,则将创建一个只读流对象,该对象包装了给定的可迭代对象。每次从流中读取时,迭代器中的数据将填充缓冲区,并持续调用,直到缓冲区等于请求的读取大小。后续的读取调用将首先从缓冲区读取,然后对基础迭代器调用next,直到迭代器耗尽。
  • object with __toString(): 如果对象有__toString()方法,对象将转换为字符串,然后返回一个使用字符串值的流。
  • NULL:当传入null时,返回一个空流对象。
  • callable:当传入一个可调用对象时,将创建一个只读流对象,并调用给定的可调用对象。可调用对象使用建议读取的字节数进行调用。可调用对象可以返回任意数量的字节,但必须在没有更多数据返回时返回false。包装可调用对象的流对象将一直调用可调用对象,直到请求的字节数可用。任何额外的字节将被缓冲并在后续读取中使用。
$stream = GuzzleHttp\Psr7\Utils::streamFor('foo');
$stream = GuzzleHttp\Psr7\Utils::streamFor(fopen('/path/to/file', 'r'));

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

$stream = GuzzleHttp\Psr7\Utils::streamFor($generator(100));

GuzzleHttp\Psr7\Utils::tryFopen

public static function tryFopen(string $filename, string $mode): resource

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

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

GuzzleHttp\Psr7\Utils::tryGetContents

public static function tryGetContents(resource $stream): string

安全地获取给定流的内容。

当stream_get_contents失败时,PHP通常会引发警告。此函数添加了一个错误处理器,检查错误并抛出异常。

GuzzleHttp\Psr7\UriFor

public static function uriFor(string|UriInterface $uri): UriInterface

返回给定值的UriInterface。

此函数接受一个字符串或UriInterface,并返回给定值的UriInterface。如果值已经是UriInterface,则直接返回。

GuzzleHttp\Psr7\MimeType::fromFilename

public static function fromFilename(string $filename): string|null

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

GuzzleHttp\Psr7\MimeType::fromExtension

public static function fromExtension(string $extension): string|null

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

从函数API升级

静态API首次在1.7.0版本中引入,以缓解全局和局部包副本之间的函数冲突问题。函数API已在2.0.0版本中删除。此处提供了一个迁移表,供您方便使用。

附加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是否为绝对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\UriComparator提供方法以确定修改后的URL是否应被视为跨域。

GuzzleHttp\Psr7\UriComparator::isCrossOrigin

public static function isCrossOrigin(UriInterface $original, UriInterface $modified): bool

确定修改后的URL是否应相对于原始URL被视为跨域。

引用解析

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。

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%b1bhttp://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.orghttp://example.org/

  • UriNormalizer::REMOVE_DEFAULT_HOST

    从URI中移除给定URI方案的默认主机。只有“file”方案定义了默认主机“localhost”。所有file:/myfilefile:///myfilefile://localhost/myfile根据RFC 3986都是等效的。

    示例:file://localhost/myfilefile:///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.htmlhttp://example.org/a/c/d.html

  • UriNormalizer::REMOVE_DUPLICATE_SLASHES

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

    示例:http://example.org//foo///bar.htmlhttp://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解析。如果不是这种情况,对相对引用的等效性或差异的判断没有任何意义。

安全

如果您在此软件包中发现安全漏洞,请发送电子邮件至[email protected]。所有安全漏洞都将得到及时处理。请在修复宣布之前,不要公开披露与安全相关的问题。请参阅安全策略以获取更多信息。

许可

Guzzle是在MIT许可(MIT)下提供的。有关更多信息,请参阅许可文件

企业版

作为Tidelift订阅的一部分提供。

Guzzle和其他数千个包的维护人员正在与Tidelift合作,为您提供在构建应用程序时使用的开源依赖项的商业支持和维护。通过支付您使用的确切的依赖项维护人员的费用,您可以节省时间,降低风险,并提高代码质量。 了解更多。