PHP中PSR规范

已通过（ACCEPTED）—— 文章标题将不会有所显示
起草中（DRAFT）—— 暂不翻译
未通过（ABANDONED）—— 简单说明，暂不翻译
已弃用（DEPRECATED）—— 会有说明，暂不翻译

PSR-0 自动加载规范（已弃用）
PSR-1 基础编码规范（已通过）
PSR-2 编码风格规范（已弃用）
PSR-3 日志接口规范（已通过）
PSR-4 自动加载规范（已通过）
PSR-4 自动加载规范 - 示例文档 
PSR-4 自动加载规范 - 说明文档
PSR-5 PHPDoc 标准（起草中）
PSR-6 缓存接口规范（已通过）
PSR-6 缓存接口规范 - 说明文档 
PSR-7 HTTP 消息接口规范（已通过）
PSR-8 Huggable 接口（未通过）
PSR-9 项目安全问题公示（未通过）
PSR-10 项目安全上报方法（未通过）
PSR-11 容器接口（已通过）
PSR-11 容器接口 - 说明文档 
PSR-12 编码规范扩充（已通过）
PSR-13 超媒体链接（已通过）
PSR-13 超媒体链接 - 说明文档
PSR-14 事件分发器（已通过）
PSR-15 HTTP 请求处理器（已通过）
PSR-16 缓存接口（已通过）
PSR-16 缓存接口 - 说明文档
PSR-17 HTTP 工厂（已通过）
PSR-18 HTTP 客户端（已通过） 
PSR-19 PHPDoc tags（起草中）
PSR-20 Clock（起草中）
PSR-21 Internationalization（起草中）
PSR-22 Application Tracing（起草中）

PSR-4 自动加载规范

PSR-3 日志接口规范 
PSR-6 缓存接口规范 
PSR-11 容器接口
PSR-13 超媒体链接
PSR-14 事件分发器
PSR-16 缓存接口

PSR-7 HTTP 消息接口规范
PSR-15 HTTP 请求处理器
PSR-17 HTTP 工厂 
PSR-18 HTTP 客户端  

PSR-1 基础编码规范
PSR-12 编码规范扩充

大写开头的驼峰式 ($StudlyCaps)
小写开头的驼峰式 ($camelCase)
下划线分隔式 ($under_score)

必须 (MUST)：绝对，严格遵循，请照做，无条件遵守；
一定不可 (MUST NOT)：禁令，严令禁止；
应该 (SHOULD) ：强烈建议这样做，但是不强求；
不该 (SHOULD NOT)：强烈不建议这样做，但是不强求；
可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少；
参见  RFC 2119 .

必须 (MUST)：绝对，严格遵循，请照做，无条件遵守；
一定不可 (MUST NOT)：禁令，严令禁止；
应该 (SHOULD) ：强烈建议这样做，但是不强求；
不该 (SHOULD NOT)：强烈不建议这样做，但是不强求；
可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少；

Fully Qualified Class Name    Namespace Prefix   Base Directory           Resulting File Path
\Acme\Log\Writer\File_Writer  Acme\Log\Writer    ./acme-log-writer/lib/   ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status     Aura\Web           /path/to/aura-web/src/   /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request         Symfony\Core       ./vendor/Symfony/Core/   ./vendor/Symfony/Core/Request.php
\Zend\Acl                     Zend               /usr/includes/Zend/      /usr/includes/Zend/Acl.php

/path/to/src/
    VendorFoo/
        Bar/
            Baz.php     # VendorFoo_Bar_Baz
    VendorDib/
        Zim/
            Gir.php     # VendorDib_Zim_Gir

/path/to/src/
    VendorFoo/
        Bar/
            Baz.php     # VendorFoo_Bar_Baz
    VendorDib/
        Zim/
            Gir.php     # VendorDib_Zim_Gir
    Irk_Operation/
        Impending_Doom/
            V1.php
            V2.php      # Irk_Operation\Impending_Doom\V2

vendor/
    vendor_name/
        package_name/
            src/
                Vendor_Name/
                    Package_Name/
                        ClassName.php       # Vendor_Name\Package_Name\ClassName
            tests/
                Vendor_Name/
                    Package_Name/
                        ClassNameTest.php   # Vendor_Name\Package_Name\ClassNameTest

vendor/
    vendor_name/
        package_name/
            src/
                ClassName.php       # Vendor_Name\Package_Name\ClassName
            tests/
                ClassNameTest.php   # Vendor_Name\Package_Name\ClassNameTest

较浅的目录结构；
文件位置更加固定；
不再使用类名中下划线作为目录分隔符；
更明确的互操作性实现

不能像 PSR-0 仅仅通过类名就能确定它在文件系统的具体位置 (这种 “类 - 到 - 文件” 约定继承自 Horde/PEAR)。

无需改变任何人的习惯或者实现方式

相对较深的目录结构
类名中的下划线被识别为目录分隔符

转换规则可以被其他提案引用

不符合某民意调查的受访者跟合作者的意愿（就是要修改老代码，有些人怕麻烦）

Paul M. Jones, Solar/Aura

Phil Sturgeon, PyroCMS (Coordinator)
Larry Garfield, Drupal

Andreas Hennings
Bernhard Schussek
Beau Simensen
Donald Gilbert
Mike van Riel
Paul Dragoonis
Too many others to name and count

Autoloader, round 4
POLL: Autoloader: Split or Combined?
PSR-X autoloader spec: Loopholes, ambiguities
Autoloader: Combine Proposals?
Package-Oriented Autoloader, Round 2
Autoloader: looking again at namespace
DISCUSSION: Package-Oriented Autoloader - vote against
VOTE: Package-Oriented Autoloader
Proposal: Package-Oriented Autoloader
Towards a Package Oriented Autoloader
List of Alternative PSR-4 Proposals
Summary of [post-Acceptance Vote pull] PSR-4 discussions

一个标准的缓存接口能提供独立的库来让我们轻松缓存中间数据；他们可以简单的依赖和使用这些标准接口而不用关心具体的实现细节。
由多个项目共享的常见开发的缓存系统，即使他们扩展了这个接口，也比单独开发的实现要健壮

任何接口标准化会被认为扼杀了未来创新，被认为不应该这样实现。但是我们相信缓存是一个足够商业化的问题场景，缓存接口在这里提供的扩展能力降低了任何潜在的停滞风险。

一种通用的底层和中间级缓存需求接口。
一种清晰的机制，用于扩展规范以支持高级功能，包括将来的 PSRs 或单个实现。 此机制必须允许多个独立扩展而不会发生冲突。

与所有现有缓存的实现体系结构兼容。
像命名空间或标记这样由少数用户使用的高级缓存特性。

灵活并且可扩展
允许在不违反接口的情况下实现大量的变化
不会将对象构造函数的隐式暴露为伪接口

比简单的方法更冗长

/**
 * 获取可用控件列表。
 *
 * 在这种情况下，我们假设小部件列表很少改动 
 * 列表一直缓存到显式清除为止。
 */
function get_widget_list()
{
    $pool = get_cache_pool('widgets');
    $item = $pool->getItem('widget_list');
    if (!$item->isHit()) {
        $value = compute_expensive_widget_list();
        $item->set($value);
        $pool->save($item);
    }
    return $item->get();
}

/**
 * 可用控件缓存列表。
 *
 * 在这种情况下，我们假设已经计算了一个小部件列表，
 * 缓存它，无论缓存的是什么。
 */
function save_widget_list($list)
{
    $pool = get_cache_pool('widgets');
    $item = $pool->getItem('widget_list');
    $item->set($list);
    $pool->save($item);
}

/**
 * 清除缓存小部件列表。
 *
 * 在这种情况下，我们只想从缓存中删除小部件。
 * 我们不在意他是否已被设置；POST的条件是『不再设置』 。
 */
function clear_widget_list()
{
    $pool = get_cache_pool('widgets');
    $pool->deleteItems(['widget_list']);
}

/**
 * 清除所有的小部件。
 *
 * 在这种情况下，我们只想清空池中所有的小部件。 
 * 应用中其他的池可能不会受到影响。
 */
function clear_widget_cache()
{
    $pool = get_cache_pool('widgets');
    $pool->clear();
}

/**
 * 加载小部件
 *
 * 我们想要获取一个小部件的列表，其中一些是缓存 一些不是。
 * 这里假设从缓存中加载比在非缓存加载机制中更快。
 *
 * 在这种情况下， 假设窗口小部件需要经常更改因此我们仅设置缓存的时间为一小时 (3600 秒)。
 * 我们也将新缓存的对象返回到池中。
 *
 * 还需要注意在实际实现中还需要对小部件窗口进行多次加载操作，
 * 但是这与本次演示无关。
 */
function load_widgets(array $ids)
{
    $pool = get_cache_pool('widgets');
    $keys = array_map(function($id) { return 'widget.' . $id; }, $ids);
    $items = $pool->getItems($keys);

    $widgets = array();
    foreach ($items as $key => $item) {
        if ($item->isHit()) {
            $value = $item->get();
        } else {
            $value = expensive_widget_load($id);
            $item->set($value);
            $item->expiresAfter(3600);
            $pool->saveDeferred($item, true);
        }
        $widget[$value->id()] = $value;
    }
    $pool->commit(); // 如果没有延期的项目这里无操作。

    return $widgets;
}

/**
 * 这个示例反应了此规范未包含的功能，
 * 但是显示为如何通过扩展来实现添加此类功能的示例。
 */

interface TaggablePoolInterface extends Psr\Cache\CachePoolInterface
{
    /**
     * 只清除池中指定标记的项目。
     */
    clearByTag($tag);
}

interface TaggableItemInterface extends Psr\Cache\CacheItemInterface
{
    public function setTags(array $tags);
}

/**
 * 标记缓存小部件。
 */
function set_widget(TaggablePoolInterface $pool, Widget $widget)
{
    $key = 'widget.' . $widget->id();
    $item = $pool->getItem($key);

    $item->setTags($widget->tags());
    $item->set($widget);
    $pool->save($item);
}

更加传统的方法.

较差的扩展及灵活性.

Larry Garfield

Paul Dragoonis, PPI Framework (Coordinator)
Robert Hafner, Stash

Survey of existing cache implementations, by @dragoonis
Strong vs. Weak informal poll, by @Crell
Implementation details informal poll, by @Crell

class ExpiresAtInvalidParameterException implements Psr\Cache\InvalidArgumentException {}

// ...

if (! (
        null === $expiration
        || $expiration instanceof \DateTime
        || $expiration instanceof \DateTimeInterface
)) {
    throw new ExpiresAtInvalidParameterException(sprintf(
        'Argument 1 passed to %s::expiresAt() must be an instance of DateTime or DateTimeImmutable; %s given',
        get_class($this),
        is_object($expiration) ? get_class($expiration) : gettype($expiration)
    ));
}

POST /path HTTP/1.1
Host: example.com

foo=bar&baz=bat

HTTP/1.1 200 OK
Content-Type: text/plain

这是返回的消息内容

RFC 2119
RFC 3986
RFC 7230
RFC 7231 

$message = $message->withHeader('foo', 'bar');

echo $message->getHeaderLine('foo');
// 输出: bar

echo $message->getHeaderLine('FOO');
// 输出: bar

$message = $message->withHeader('fOO', 'baz');
echo $message->getHeaderLine('foo');
// 输出: baz

$message = $message
    ->withHeader('foo', 'bar')
    ->withAddedHeader('foo', 'baz');

$header = $message->getHeaderLine('foo');
// $header 包含: 'bar, baz'

$header = $message->getHeader('foo');
// ['bar', 'baz']

$request = $request
    ->withMethod('OPTIONS')
    ->withRequestTarget('*')
    ->withUri(new Uri('https://example.org/'));

OPTIONS * HTTP/1.1

array(
    'files' => array(
        'name' => array(
            0 => 'file0.txt',
            1 => 'file1.html',
        ),
        'type' => array(
            0 => 'text/plain',
            1 => 'text/html',
        ),
        /* 等等其他属性 */
    ),
)

array(
    'files' => array(
        0 => array(
            'name' => 'file0.txt',
            'type' => 'text/plain',
            /* 等等其他属性 */
        ),
        1 => array(
            'name' => 'file1.html',
            'type' => 'text/html',
            /* 等等其他属性 */
        ),
    ),
)

<input type="file" name="avatar" />

array(
    'avatar' => array(
        'tmp_name' => 'phpUxcOty',
        'name' => 'my-avatar.png',
        'size' => 90996,
        'type' => 'image/png',
        'error' => 0,
    ),
)

array(
    'avatar' => /* UploadedFileInterface 实例 */
)

<input type="file" name="my-form[details][avatar]" />

array(
    'my-form' => array(
        'details' => array(
            'avatar' => array(
                'tmp_name' => 'phpUxcOty',
                'name' => 'my-avatar.png',
                'size' => 90996,
                'type' => 'image/png',
                'error' => 0,
            ),
        ),
    ),
)

array(
    'my-form' => array(
        'details' => array(
            'avatar' => /* UploadedFileInterface 实例 */
        ),
    ),
)

Upload an avatar: <input type="file" name="my-form[details][avatars][]" />
Upload an avatar: <input type="file" name="my-form[details][avatars][]" />

array(
    'my-form' => array(
        'details' => array(
            'avatars' => array(
                'tmp_name' => array(
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ),
                'name' => array(
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ),
                'size' => array(
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ),
                'type' => array(
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ),
                'error' => array(
                    0 => '...',
                    1 => '...',
                    2 => '...',
                ),
            ),
        ),
    ),
)

array(
    'my-form' => array(
        'details' => array(
            'avatars' => array(
                0 => /* UploadedFileInterface 实例 */,
                1 => /* UploadedFileInterface 实例 */,
                2 => /* UploadedFileInterface 实例 */,
            ),
        ),
    ),
)

$request->getUploadedFiles()['my-form']['details']['avatars'][1];

$file0 = $request->getUploadedFiles()['files'][0];
$file1 = $request->getUploadedFiles()['files'][1];

printf(
    "Received the files %s and %s",
    $file0->getClientFilename(),
    $file1->getClientFilename()
);

// "Received the files file0.txt and file1.html"

// 移动文件至上传目录
$filename = sprintf(
    '%s.%s',
    create_uuid(),
    pathinfo($file0->getClientFilename(), PATHINFO_EXTENSION)
);
$file0->moveTo(DATA_DIR . '/' . $filename);

// 将文件流式传输至 Amazon S3。
// 假设 $s3wrapper 是一个将写入 S3 的 PHP 流，而 Psr7StreamWrapper 是一个将 StreamInterface 作为 PHP StreamWrapper 进行装饰的类。
$stream = new Psr7StreamWrapper($file1->getStream());
stream_copy_to_stream($stream, $s3wrapper);

<?php
namespace Psr\Http\Message;

/**
 * 
 * HTTP 消息包括客户端向服务器发起的「请求」和服务器端返回给客户端的「响应」。
 * 此接口定义了他们通用的方法。
 * 
 * HTTP 消息是被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套
 * 机制，在内部保持好原有的内容，然后把修改状态后的信息返回。
 *
 * @see http://www.ietf.org/rfc/rfc7230.txt
 * @see http://www.ietf.org/rfc/rfc7231.txt
 */
interface MessageInterface
{
    /**
     * 获取字符串形式的 HTTP 协议版本信息。
     *
     * 字符串 **必须** 包含 HTTP 版本数字（如：「1.1」, 「1.0」）。
     *
     * @return string HTTP 协议版本
     */
    public function getProtocolVersion();

    /**
     * 返回指定 HTTP 版本号的消息实例。
     *
     * 传参的版本号只 **必须** 包含 HTTP 版本数字，如："1.1", "1.0"。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息对象，然后返回
     * 一个新的带有传参进去的 HTTP 版本的实例
     *
     * @param string $version HTTP 版本信息
     * @return self
     */
    public function withProtocolVersion($version);

    /**
     * 获取所有的报头信息
     *
     * 返回的二维数组中，第一维数组的「键」代表单条报头信息的名字，「值」是
     * 以数组形式返回的，见以下实例：
     *
     *     // 把「值」的数据当成字串打印出来
     *     foreach ($message->getHeaders() as $name => $values) {
     *         echo $name . ': ' . implode(', ', $values);
     *     }
     *
     *     // 迭代的循环二维数组
     *     foreach ($message->getHeaders() as $name => $values) {
     *         foreach ($values as $value) {
     *             header(sprintf('%s: %s', $name, $value), false);
     *         }
     *     }
     *
     * 虽然报头信息是没有大小写之分，但是使用 `getHeaders()` 会返回保留了原本
     * 大小写形式的内容。
     *
     * @return string[][] 返回一个两维数组，第一维数组的「键」 **必须** 为单条报头信息的
     *     名称，对应的是由字串组成的数组，请注意，对应的「值」 **必须** 是数组形式的。
     */
    public function getHeaders();

    /**
     * 检查是否报头信息中包含有此名称的值，不区分大小写
     *
     * @param string $name 不区分大小写的报头信息名称
     * @return bool 找到返回 true，未找到返回 false
     */
    public function hasHeader($name);

    /**
     * 根据给定的名称，获取一条报头信息，不区分大小写，以数组形式返回
     *
     * 此方法以数组形式返回对应名称的报头信息。
     *
     * 如果没有对应的报头信息，**必须** 返回一个空数组。
     *
     * @param string $name 不区分大小写的报头字段名称。
     * @return string[] 返回报头信息中，对应名称的，由字符串组成的数组值，如果没有对应
     *     的内容，**必须** 返回空数组。
     */
    public function getHeader($name);

    /**
     * 根据给定的名称，获取一条报头信息，不区分大小写，以逗号分隔的形式返回
     * 
     * 此方法返回所有对应的报头信息，并将其使用逗号分隔的方法拼接起来。
     *
     * 注意：不是所有的报头信息都可使用逗号分隔的方法来拼接，对于那些报头信息，请使用
     * `getHeader()` 方法来获取。
     * 
     * 如果没有对应的报头信息，此方法 **必须** 返回一个空字符串。
     *
     * @param string $name 不区分大小写的报头字段名称。
     * @return string 返回报头信息中，对应名称的，由逗号分隔组成的字串，如果没有对应
     *     的内容，**必须** 返回空字符串。
     */
    public function getHeaderLine($name);

    /**
     * 返回替换指定报头信息「键/值」对的消息实例。
     *
     * 虽然报头信息是不区分大小写的，但是此方法必须保留其传参时的大小写状态，并能够在
     * 调用 `getHeaders()` 的时候被取出。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息对象，然后返回
     * 一个更新后带有传参进去报头信息的实例
     *
     * @param string $name 不区分大小写的报头字段名称。
     * @param string|string[] $value 报头信息或报头信息数组。
     * @return self
     * @throws \InvalidArgumentException 无效的报头字段或报头信息时抛出
     */
    public function withHeader($name, $value);

    /**
     * 返回一个报头信息增量的 HTTP 消息实例。
     *
     * 原有的报头信息会被保留，新的值会作为增量加上，如果报头信息不存在的话，字段会被加上。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息对象，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param string $name 不区分大小写的报头字段名称。
     * @param string|string[] $value 报头信息或报头信息数组。
     * @return self
     * @throws \InvalidArgumentException 报头字段名称非法时会被抛出。
     * @throws \InvalidArgumentException 报头头信息的值非法的时候会被抛出。
     */
    public function withAddedHeader($name, $value);

    /**
     * 返回被移除掉指定报头信息的 HTTP 消息实例。
     *
     * 报头信息字段在解析的时候，**必须** 保证是不区分大小写的。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息对象，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param string $name 不区分大小写的头部字段名称。
     * @return self
     */
    public function withoutHeader($name);

    /**
     * 获取 HTTP 消息的内容。
     *
     * @return StreamInterface 以数据流的形式返回。
     */
    public function getBody();

    /**
     * 返回指定内容的 HTTP 消息实例。
     *
     * 内容 **必须** 是 `StreamInterface` 接口的实例。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息对象，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param StreamInterface $body 数据流形式的内容。
     * @return self
     * @throws \InvalidArgumentException 当消息内容不正确的时候抛出。
     */
    public function withBody(StreamInterface $body);
}

<?php
namespace Psr\Http\Message;

/**
 * 代表客户端向服务器发起请求的 HTTP 消息对象。
 *
 * 根据 HTTP 规范，此接口包含以下属性：
 *
 * - HTTP 协议版本号
 * - HTTP 请求方法
 * - URI
 * - 报头信息
 * - 消息内容
 *
 * 在构造 HTTP 请求对象的时候，如果没有提供 Host 信息，
 * 实现类库 **必须** 从给出的 URI 中去提取 Host 信息。
 *
 * HTTP 请求是被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保
 * 持好原有的内容，然后把修改状态后的新的 HTTP 请求实例返回。
 */
interface RequestInterface extends MessageInterface
{
    /**
     * 获取消息的请求目标。
     * 
     * 获取消息的请求目标的使用场景，可能是在客户端，也可能是在服务器端，也可能是在指定信息的时候
     * （参阅下方的 `withRequestTarget()`）。
     * 
     * 在大部分情况下，此方法会返回组合 URI 的原始形式，除非被指定过（参阅下方的 `withRequestTarget()`）。
     *
     * 如果没有可用的 URI，并且没有设置过请求目标，此方法 **必须** 返回 「/」。
     *
     * @return string
     */
    public function getRequestTarget();

    /**
     * 返回一个指定目标的请求实例。
     * 
     * 如果请求需要非原始形式的请求目标——例如指定绝对形式、认证形式或星号形式——则此方法
     * 可用于创建指定请求目标的实例。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 请求实例，然后返回
     * 一个新的修改过的 HTTP 请求实例。
     *
     * @see [http://tools.ietf.org/html/rfc7230#section-2.7](http://tools.ietf.org/html/rfc7230#section-2.7) 
     * （关于请求目标的各种允许的格式）
     * 
     * @param mixed $requestTarget
     * @return self
     */
    public function withRequestTarget($requestTarget);

    /**
     * 获取当前请求使用的 HTTP 方法
     *
     * @return string HTTP 方法字符串
     */
    public function getMethod();

    /**
     * 返回更改了请求方法的消息实例。
     *
     * 虽然，在大部分情况下，HTTP 请求方法都是使用大写字母来标示的，但是，实现类库 **不应该**
     * 修改用户传参的大小格式。
     * 
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 请求实例，然后返回
     * 一个新的修改过的 HTTP 请求实例。
     *
     * @param string $method 大小写敏感的方法名
     * @return self
     * @throws \InvalidArgumentException 当非法的 HTTP 方法名传入时会抛出异常。
     */
    public function withMethod($method);

    /**
     * 获取 URI 实例。
     *
     * 此方法 **必须** 返回 `UriInterface` 的 URI 实例。
     *
     * @see http://tools.ietf.org/html/rfc3986#section-4.3
     * @return UriInterface 返回与当前请求相关的 `UriInterface` 类型的 URI 实例。
     */
    public function getUri();

    /**
     * 返回修改了 URI 的消息实例。
     *
     * 当传入的 URI 包含有 HOST 信息时，此方法 **必须** 更新 HOST 信息。如果 URI 
     * 实例没有附带 HOST 信息，任何之前存在的 HOST 信息 **必须** 作为候补，应用
     * 更改到返回的消息实例里。
     * 
     * 你可以通过传入第二个参数来，来干预方法的处理，当 `$preserveHost` 设置为 `true` 
     * 的时候，会保留原来的 HOST 信息。当 `$preserveHost` 设置为 `true` 时，此方法
     * 会如下处理 HOST 信息：
     * 
     * - 如果 HOST 信息不存在或为空，并且新 URI 包含 HOST 信息，则此方法 **必须** 更新返回请求中的 HOST 信息。
     * - 如果 HOST 信息不存在或为空，并且新 URI 不包含 HOST 信息，则此方法 **不得** 更新返回请求中的 HOST 信息。
     * - 如果HOST 信息存在且不为空，则此方法 **不得** 更新返回请求中的 HOST 信息。
     * 
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 请求实例，然后返回
     * 一个新的修改过的 HTTP 请求实例。
     *
     * @see http://tools.ietf.org/html/rfc3986#section-4.3
     * @param UriInterface $uri `UriInterface` 新的 URI 实例
     * @param bool $preserveHost 是否保留原有的 HOST 头信息
     * @return self
     */
    public function withUri(UriInterface $uri, $preserveHost = false);
}

<?php
namespace Psr\Http\Message;

/**
 * 表示服务器端接收到的 HTTP 请求。
 *
 * 根据 HTTP 规范，此接口包含以下属性：
 *
 * - HTTP 协议版本号
 * - HTTP 请求方法
 * - URI
 * - 报头信息
 * - 消息内容
 *
 * 此外，它封闭了从 CGI 和/或 PHP 环境变量，包括：
 *
 * - `$_SERVER` 中表示的值。
 * - 提供的任意 Cookie 信息（通常通过 `$_COOKIE` 获取）
 * - 查询字符串参数（通常通过 `$_GET` 获取，或者通过 `parse_str()` 解析）
 * - 如果存在的话，上传文件的信息（通常通过 `$_FILES` 获取）
 * - 反序列化的消息体参数（通常来自于 `$_POST`）
 *
 * `$_SERVER` 的值 **必须** 被视为不可变的，因为代表了请求时应用程序的状态；因此，没有允许修改的方法。
 * 其他值则提供了修改的方法，因为可以从 `$_SERVER` 或请求体中恢复，并且可能在应用程序中被处理
 * （比如可能根据内容类型对消息体参数进行反序列化）。
 *
 * 此外，这个接口要识别请求的扩展信息和匹配其他的参数。
 * （例如，通过 URI 进行路径匹配，解析 Cookie 值，反序列化非表单编码的消息体，报头中的用户名进行匹配认证）
 * 这些参数存储在「attributes」中。
 *
 * HTTP 请求是被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保
 * 持好原有的内容，然后把修改状态后的，新的 HTTP 请求实例返回。
 */
interface ServerRequestInterface extends RequestInterface
{
    /**
     * 返回服务器参数。
     *
     * 返回与请求环境相关的数据，通常从 PHP 的 `$_SERVER` 超全局变量中获取，但不是必然的。
     *
     * @return array
     */
    public function getServerParams();

    /**
     * 获取 Cookie 数据。
     *
     * 获取从客户端发往服务器的 Cookie 数据。
     *
     * 这个数据的结构 **必须** 和超全局变量 `$_COOKIE` 兼容。
     *
     * @return array
     */
    public function getCookieParams();

    /**
     * 返回具体指定 Cookie 的实例。
     *
     * 这个数据不是一定要来源于 `$_COOKIE`，但是 **必须** 与之结构兼容。通常在实例化时注入。
     *
     * 这个方法 **禁止** 更新实例中的 Cookie 报头和服务器参数中的相关值。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     * 
     * @param array $cookies 表示 Cookie 的键值对。
     * @return self
     */
    public function withCookieParams(array $cookies);

    /**
     * 获取查询字符串参数。
     *
     * 如果可以的话，返回反序列化的查询字符串参数。
     *
     * 注意：查询参数可能与 URI 或服务器参数不同步。如果你需要确保只获取原始值，则可能需要调用
     * `getUri()->getQuery()` 或服务器参数中的 `QUERY_STRING` 获取原始的查询字符串并自行解析。
     *
     * @return array
     */
    public function getQueryParams();

    /**
     * 返回具体指定查询字符串参数的实例。
     *
     * 这些值 **应该** 在传入请求的闭包中保持不变。它们 **可能** 在实例化的时候注入，
     * 例如来自 `$_GET` 或者其他一些值（例如 URI）中得到。如果是通过解析 URI 获取，则
     * 数据结构必须与 `parse_str()` 返回的内容兼容，以便处理查询参数、嵌套的代码可以复用。
     *
     * 设置查询字符串参数 **不得** 更改存储的 URI 和服务器参数中的值。
     * 
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param array $query 查询字符串参数数组，通常来源于 `$_GET`。
     * @return self
     */
    public function withQueryParams(array $query);

    /**
     * 获取规范化的上传文件数据。
     *
     * 这个方法会规范化返回的上传文件元数据树结构，每个叶子结点都是 `Psr\Http\Message\UploadedFileInterface` 实例。
     *
     * 这些值 **可能** 在实例化的时候从 `$_FILES` 或消息体中获取，或者通过 `withUploadedFiles()` 获取。
     *
     * @return array `UploadedFileInterface` 的实例数组；如果没有数据则必须返回一个空数组。
     */
    public function getUploadedFiles();

    /**
     * 返回使用指定的上传文件数据的新实例。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param array `UploadedFileInterface` 实例的树结构，类似于 `getUploadedFiles()` 的返回值。
     * @return self
     * @throws \InvalidArgumentException 如果提供无效的结构时抛出。
     */
    public function withUploadedFiles(array $uploadedFiles);

    /**
     * 获取请求消息体中的参数。
     *
     * 如果请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data 且请求方法是 POST，
     * 则此方法 **必须** 返回 $_POST 的内容。
     *
     * 如果是其他情况，此方法可能返回反序列化请求正文内容的任何结果；当解析返回返回的结构化内容时，潜在的类型 **必须**
     * 只能是数组或 `object` 类型。`null` 表示没有消息体内容。
     *
     * @return null|array|object 如果存在则返回反序列化消息体参数。一般是一个数组或 `object`。
     */
    public function getParsedBody();

    /**
     * 返回具有指定消息体参数的实例。
     *
     * **可能** 在实例化时注入。
     *
     * 如果请求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data 且请求方法是 POST，
     * 则方法的参数只能是 $_POST。
     *
     * 数据不一定要来自 $_POST，但是 **必须** 是反序列化请求正文内容的结果。由于需要反序列化/解析返回的结构化数据，
     * 所以这个方法只接受数组、 `object` 类型和 `null`（如果没有可用的数据解析）。
     *
     * 例如，如果确定请求数据是一个 JSON，可以使用此方法创建具有反序列化参数的请求实例。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @param null|array|object $data 反序列化的消息体数据，通常是数组或 `object`。
     * @return self
     * @throws \InvalidArgumentException 如果提供的数据类型不支持。
     */
    public function withParsedBody($data);

    /**
     * 获取从请求派生的属性。
     *
     * 请求「attributes」可用于从请求导出的任意参数：比如路径匹配操作的结果；解密 Cookie 的结果；
     * 反序列化非表单编码的消息体的结果；属性将是应用程序与请求特定的，并且可以是可变的。
     *
     * @return mixed[] 从请求派生的属性。
     */
    public function getAttributes();

    /**
     * 获取单个派生的请求属性。
     *
     * 获取 getAttributes() 中声明的某一个属性，如果不存在则返回提供的默认值。
     *
     * 这个方法不需要 hasAttribute 方法，因为允许在找不到指定属性的时候返回默认值。
     *
     * @see getAttributes()
     * @param string $name 属性名称。
     * @param mixed $default 如果属性不存在时返回的默认值。
     * @return mixed
     */
    public function getAttribute($name, $default = null);

    /**
     * 返回具有指定派生属性的实例。
     *
     * 此方法允许设置 getAttributes() 中声明的单个派生的请求属性。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @see getAttributes()
     * @param string $name 属性名。
     * @param mixed $value 属性值。
     * @return self
     */
    public function withAttribute($name, $value);

    /**
     * 返回移除指定属性的实例。
     *
     * 此方法允许移除 getAttributes() 中声明的单个派生的请求属性。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @see getAttributes()
     * @param string $name 属性名。
     * @return self
     */
    public function withoutAttribute($name);
}

<?php
namespace Psr\Http\Message;

/**
 * 表示服务器返回的响应消息。
 *
 * 根据 HTTP 规范，此接口包含以下各项的属性：
 *
 * - 协议版本
 * - 状态码和原因短语
 * - 报头
 * - 消息体
 * 
 * HTTP 响应是被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保
 * 持好原有的内容，然后把修改状态后的，新的 HTTP 响应实例返回。
 */
interface ResponseInterface extends MessageInterface
{
    /**
     * 获取响应状态码。
     *
     * 状态码是一个三位整数，用于理解请求。
     *
     * @return int 状态码。
     */
    public function getStatusCode();

    /**
     * 返回具有指定状态码和原因短语（可选）的实例。
     *
     * 如果未指定原因短语，实现代码 **可能** 选择 RFC7231 或 IANA 为状态码推荐的原因短语。
     *
     * 此方法在实现的时候，**必须** 保留原有的不可修改的 HTTP 消息实例，然后返回
     * 一个新的修改过的 HTTP 消息实例。
     *
     * @see http://tools.ietf.org/html/rfc7231#section-6
     * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
     * @param int $code 三位整数的状态码。
     * @param string $reasonPhrase 为状态码提供的原因短语；如果未提供，实现代码可以使用 HTTP 规范建议的默认代码。
     * @return self
     * @throws \InvalidArgumentException 如果传入无效的状态码，则抛出。
     */
    public function withStatus($code, $reasonPhrase = '');

    /**
     * 获取与响应状态码关联的响应原因短语。
     *
     * 因为原因短语不是响应状态行中的必需元素，所以原因短语 **可能** 是空。
     * 实现代码可以选择返回响应的状态代码的默认 RFC 7231 推荐原因短语（或 IANA HTTP 状态码注册表中列出的原因短语）。
     *
     * @see http://tools.ietf.org/html/rfc7231#section-6
     * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
     * @return string 原因短语；如果不存在，则 **必须** 返回空字符串。
     */
    public function getReasonPhrase();
}

<?php
namespace Psr\Http\Message;

/**
 * 描述数据流。
 *
 * 通常，实例将包装PHP流; 此接口提供了最常见操作的包装，包括将整个流序列化为字符串。
 */
interface StreamInterface
{
    /**
     * 从头到尾将流中的所有数据读取到字符串。
     *
     * 这个方法 **必须** 在开始读数据前定位到流的开头，并读取出所有的数据。
     *
     * 警告：这可能会尝试将大量数据加载到内存中。
     *
     * 这个方法 **不得** 抛出异常以符合 PHP 的字符串转换操作。
     *
     * @see http://php.net/manual/en/language.oop5.magic.php#object.tostring
     * @return string
     */
    public function __toString();

    /**
     * 关闭流和任何底层资源。
     *
     * @return void
     */
    public function close();

    /**
     * 从流中分离任何底层资源。
     *
     * 分离之后，流处于不可用状态。
     *
     * @return resource|null 如果存在的话，返回底层 PHP 流。
     */
    public function detach();

    /**
     * 如果可知，获取流的数据大小。
     *
     * @return int|null 如果可知，返回以字节为单位的大小，如果未知返回 `null`。
     */
    public function getSize();

    /**
     * 返回当前读/写的指针位置。
     *
     * @return int 指针位置。
     * @throws \RuntimeException 产生错误时抛出。
     */
    public function tell();

    /**
     * 返回是否位于流的末尾。
     *
     * @return bool
     */
    public function eof();

    /**
     * 返回流是否可随机读取。
     *
     * @return bool
     */
    public function isSeekable();

    /**
     * 定位流中的指定位置。
     *
     * @see http://www.php.net/manual/en/function.fseek.php
     * @param int $offset 要定位的流的偏移量。
     * @param int $whence 指定如何根据偏移量计算光标位置。有效值与 PHP 内置函数 `fseek()` 相同。
     *     SEEK_SET：设定位置等于 $offset 字节。默认。
     *     SEEK_CUR：设定位置为当前位置加上 $offset。
     *     SEEK_END：设定位置为文件末尾加上 $offset （要移动到文件尾之前的位置，offset 必须是一个负值）。
     * @throws \RuntimeException 失败时抛出。
     */
    public function seek($offset, $whence = SEEK_SET);

    /**
     * 定位流的起始位置。
     *
     * 如果流不可以随机访问，此方法将引发异常；否则将执行 seek(0)。
     *
     * @see seek()
     * @see http://www.php.net/manual/en/function.fseek.php
     * @throws \RuntimeException 失败时抛出。
     */
    public function rewind();

    /**
     * 返回流是否可写。
     *
     * @return bool
     */
    public function isWritable();

    /**
     * 向流中写数据。
     *
     * @param string $string 要写入流的数据。
     * @return int 返回写入流的字节数。
     * @throws \RuntimeException 失败时抛出。
     */
    public function write($string);

    /**
     * 返回流是否可读。
     *
     * @return bool
     */
    public function isReadable();

    /**
     * 从流中读取数据。
     *
     * @param int $length 从流中读取最多 $length 字节的数据并返回。如果数据不足，则可能返回少于
     *     $length 字节的数据。
     * @return string 返回从流中读取的数据，如果没有可用的数据则返回空字符串。
     * @throws \RuntimeException 失败时抛出。
     */
    public function read($length);

    /**
     * 返回字符串中的剩余内容。
     *
     * @return string
     * @throws \RuntimeException 如果无法读取则抛出异常。
     * @throws \RuntimeException 如果在读取时发生错误则抛出异常。
     */
    public function getContents();

    /**
     * 获取流中的元数据作为关联数组，或者检索指定的键。
     *
     * 返回的键与从 PHP 的 stream_get_meta_data() 函数返回的键相同。
     *
     * @see http://php.net/manual/en/function.stream-get-meta-data.php
     * @param string $key 要检索的特定元数据。
     * @return array|mixed|null 如果没有键，则返回关联数组。如果提供了键并且找到值，
     *     则返回特定键值；如果未找到键，则返回 null。
     */
    public function getMetadata($key = null);
}

<?php
namespace Psr\Http\Message;

/**
 * URI 数据对象。
 *
 * 此接口按照 RFC 3986 来构建 HTTP URI，提供了一些通用的操作，你可以自由的对此接口
 * 进行扩展。你可以使用此 URI 接口来做 HTTP 相关的操作，也可以使用此接口做任何 URI 
 * 相关的操作。
 *
 * 此接口的实例化对象被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保
 * 持好原有的内容，然后把修改状态后的，新的实例返回。
 *
 * 通常，HOST 信息也将出现在请求消息中。对于服务器端的请求，通常可以在服务器参数中发现此信息。
 * 
 * @see [URI 通用标准规范](http://tools.ietf.org/html/rfc3986)
 */
interface UriInterface
{
    /**
     * 从 URI 中取出 scheme。
     *
     * 如果不存在 Scheme，此方法 **必须** 返回空字符串。
     *
     * 根据 RFC 3986 规范 3.1 章节，返回的数据 **必须** 是小写字母。
     *
     * 最后部分的「:」字串不属于 Scheme，**不得** 作为返回数据的一部分。
     *
     * @see https://tools.ietf.org/html/rfc3986#section-3.1
     * @return string URI Ccheme 的值。
     */
    public function getScheme();

    /**
     * 返回 URI 认证信息。
     *
     * 如果没有 URI 认证信息的话，**必须** 返回一个空字符串。
     *
     * URI 的认证信息语法是：
     *
     * <pre>
     * [user-info@]host[:port]
     * </pre>
     *
     * 如果端口部分没有设置，或者端口不是标准端口，**不应该** 包含在返回值内。
     *
     * @see https://tools.ietf.org/html/rfc3986#section-3.2
     * @return string URI 认证信息，格式为：「[user-info@]host[:port]」。
     */
    public function getAuthority();

    /**
     * 从 URI 中获取用户信息。
     *
     * 如果不存在用户信息，此方法 **必须** 返回一个空字符串。
     * 
     * 如果 URI 中存在用户，则返回该值；此外，如果密码也存在，它将附加到用户值，用冒号（「:」）分隔。
     *
     * 用户信息后面跟着的 "@" 字符，不是用户信息里面的一部分，**不得** 在返回值里出现。
     *
     * @return string URI 的用户信息，格式："username[:password]" 
     */
    public function getUserInfo();

    /**
     * 从 URI 中获取 HOST 信息。
     *
     * 如果 URI 中没有此值，**必须** 返回空字符串。
     *
     * 根据 RFC 3986 规范 3.2.2 章节，返回的数据 **必须** 是小写字母。
     *
     * @see http://tools.ietf.org/html/rfc3986#section-3.2.2
     * @return string URI 中的 HOST 信息。
     */
    public function getHost();

    /**
     * 从 URI 中获取端口信息。
     *
     * 如果端口信息是与当前 Scheme 的标准端口不匹配的话，就使用整数值的格式返回，如果是一
     * 样的话，**应该** 返回 `null` 值。
     * 
     * 如果不存在端口和 Scheme 信息，**必须** 返回 `null` 值。
     * 
     * 如果不存在端口数据，但是存在 Scheme 的话，**可能** 返回 Scheme 对应的
     * 标准端口，但是 **应该** 返回 `null`。
     * 
     * @return null|int URI 中的端口信息。
     */
    public function getPort();

    /**
     * 从 URI 中获取路径信息。
     *
     * 路径可以是空的，或者是绝对的（以斜线「/」开头），或者相对路径（不以斜线开头）。
     * 实现 **必须** 支持所有三种语法。
     *
     * 根据 RFC 7230 第 2.7.3 节，通常空路径「」和绝对路径「/」被认为是相同的。
     * 但是这个方法 **不得** 自动进行这种规范化，因为在具有修剪的基本路径的上下文中，
     * 例如前端控制器中，这种差异将变得显著。用户的任务就是可以将「」和「/」都处理好。
     *
     * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。
     * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.3 节。
     *
     * 例如，如果值包含斜线（「/」）而不是路径段之间的分隔符，则该值必须以编码形式（例如「%2F」）
     * 传递给实例。
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.3
     * @return string URI 路径信息。
     */
    public function getPath();

    /**
     * 获取 URI 中的查询字符串。
     *
     * 如果不存在查询字符串，则此方法必须返回空字符串。
     *
     * 前导的「?」字符不是查询字符串的一部分，**不得** 添加在返回值中。
     *
     * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。
     * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.4 节。
     *
     * 例如，如果查询字符串的键值对中的值包含不做为值之间分隔符的（「&」），则该值必须
     * 以编码形式传递（例如「%26」）到实例。
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.4
     * @return string URI 中的查询字符串
     */
    public function getQuery();

    /**
     * 获取 URI 中的片段（Fragment）信息。
     *
     * 如果没有片段信息，此方法 **必须** 返回空字符串。
     *
     * 前导的「#」字符不是片段的一部分，**不得** 添加在返回值中。
     *
     * 返回的值 **必须** 是百分号编码，但 **不得** 对任何字符进行双重编码。
     * 要确定要编码的字符，请参阅 RFC 3986 第 2 节和第 3.5 节。
     *
     * @see https://tools.ietf.org/html/rfc3986#section-2
     * @see https://tools.ietf.org/html/rfc3986#section-3.5
     * @return string URI 中的片段信息。
     */
    public function getFragment();

    /**
     * 返回具有指定 Scheme 的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含指定 Scheme 的实例。
     *
     * 实现 **必须** 支持大小写不敏感的「http」和「https」的 Scheme，并且在
     * 需要的时候 **可能** 支持其他的 Scheme。
     *
     * 空的 Scheme 相当于删除 Scheme。
     *
     * @param string $scheme 给新实例使用的 Scheme。
     * @return self 具有指定 Scheme 的新实例。
     * @throws \InvalidArgumentException 使用无效的 Scheme 时抛出。
     * @throws \InvalidArgumentException 使用不支持的 Scheme 时抛出。
     */
    public function withScheme($scheme);

    /**
     * 返回具有指定用户信息的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含指定用户信息的实例。
     *
     * 密码是可选的，但用户信息 **必须** 包括用户；用户信息的空字符串相当于删除用户信息。
     * 
     * @param string $user 用于认证的用户名。
     * @param null|string $password 密码。
     * @return self 具有指定用户信息的新实例。
     */
    public function withUserInfo($user, $password = null);

    /**
     * 返回具有指定 HOST 信息的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含指定 HOST 信息的实例。
     *
     * 空的 HOST 信息等同于删除 HOST 信息。
     *
     * @param string $host 用于新实例的 HOST 信息。
     * @return self 具有指定 HOST 信息的实例。
     * @throws \InvalidArgumentException 使用无效的 HOST 信息时抛出。
     */
    public function withHost($host);

    /**
     * 返回具有指定端口的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含指定端口的实例。
     *
     * 实现 **必须** 为已建立的 TCP 和 UDP 端口范围之外的端口引发异常。
     *
     * 为端口提供的空值等同于删除端口信息。
     *
     * @param null|int $port 用于新实例的端口；`null` 值将删除端口信息。
     * @return self 具有指定端口的实例。
     * @throws \InvalidArgumentException 使用无效端口时抛出异常。
     */
    public function withPort($port);

    /**
     * 返回具有指定路径的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含指定路径的实例。
     *
     * 路径可以是空的、绝对的（以斜线开头）或者相对路径（不以斜线开头），实现必须支持这三种语法。
     *
     * 如果 HTTP 路径旨在与 HOST 相对而不是路径相对，，那么它必须以斜线开头。
     * 假设 HTTP 路径不以斜线开头，对应该程序或开发人员来说，相对于一些已知的路径。
     *
     * 用户可以提供编码和解码的路径字符，要确保实现了 `getPath()` 中描述的正确编码。
     *
     * @param string $path 用于新实例的路径。
     * @return self 具有指定路径的实例。
     * @throws \InvalidArgumentException 使用无效的路径时抛出。
     */
    public function withPath($path);

    /**
     * 返回具有指定查询字符串的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含查询字符串的实例。
     *
     * 用户可以提供编码和解码的查询字符串，要确保实现了 `getQuery()` 中描述的正确编码。
     *
     * 空查询字符串值等同于删除查询字符串。
     *
     * @param string $query 用于新实例的查询字符串。
     * @return self 具有指定查询字符串的实例。
     * @throws \InvalidArgumentException 使用无效的查询字符串时抛出。
     */
    public function withQuery($query);

    /**
     * 返回具有指定 URI 片段（Fragment）的实例。
     *
     * 此方法 **必须** 保留当前实例的状态，并返回包含片段的实例。
     *
     * 用户可以提供编码和解码的片段，要确保实现了 `getFragment()` 中描述的正确编码。
     *
     * 空片段值等同于删除片段。
     *
     * @param string $fragment 用于新实例的片段。
     * @return self 具有指定 URI 片段的实例。
     */
    public function withFragment($fragment);

    /**
     * 返回字符串表示形式的 URI。
     *
     * 根据 RFC 3986 第 4.1 节，结果字符串是完整的 URI 还是相对引用，取决于 URI 有哪些组件。
     * 该方法使用适当的分隔符连接 URI 的各个组件：
     *
     * - 如果存在 Scheme 则 **必须** 以「:」为后缀。
     * - 如果存在认证信息，则必须以「//」作为前缀。
     * - 路径可以在没有分隔符的情况下连接。但是有两种情况需要调整路径以使 URI 引用有效，因为 PHP
     *   不允许在 `__toString()` 中引发异常：
     *     - 如果路径是相对的并且有认证信息，则路径 **必须** 以「/」为前缀。
     *     - 如果路径以多个「/」开头并且没有认证信息，则起始斜线 **必须** 为一个。
     * - 如果存在查询字符串，则 **必须** 以「?」作为前缀。
     * - 如果存在片段（Fragment），则 **必须** 以「#」作为前缀。
     *
     * @see http://tools.ietf.org/html/rfc3986#section-4.1
     * @return string
     */
    public function __toString();
}

<?php
namespace Psr\Http\Message;

/**
 * 通过 HTTP 请求上传的一个文件内容。
 *
 * 此接口的实例是被视为无法修改的，所有能修改状态的方法，都 **必须** 有一套机制，在内部保
 * 持好原有的内容，然后把修改状态后的，新的实例返回。
 */
interface UploadedFileInterface
{
    /**
     * 获取上传文件的数据流。
     *
     * 此方法必须返回一个 `StreamInterface` 实例，此方法的目的在于允许 PHP 对获取到的数
     * 据流直接操作，如 stream_copy_to_stream() 。
     *
     * 如果在调用此方法之前调用了 `moveTo()` 方法，此方法 **必须** 抛出异常。
     *
     * @return StreamInterface 上传文件的数据流
     * @throws \RuntimeException 没有数据流的情形下。
     * @throws \RuntimeException 无法创建数据流。
     */
    public function getStream();

    /**
     * 把上传的文件移动到新目录。
     *
     * 此方法保证能同时在 `SAPI` 和 `non-SAPI` 环境下使用。实现类库 **必须** 判断
     * 当前处在什么环境下，并且使用合适的方法来处理，如 move_uploaded_file(), rename()
     * 或者数据流操作。
     *
     * $targetPath 可以是相对路径，也可以是绝对路径，使用 rename() 解析起来应该是一样的。
     *
     * 当这一次完成后，原来的文件 **必须** 会被移除。
     * 
     * 如果此方法被调用多次，一次以后的其他调用，都要抛出异常。
     *
     * 如果在 SAPI 环境下的话，$_FILES 内有值，当使用  moveTo(), is_uploaded_file()
     * 和 move_uploaded_file() 方法来移动文件时 **应该** 确保权限和上传状态的准确性。
     * 
     * 如果你希望操作数据流的话，请使用 `getStream()` 方法，因为在 SAPI 场景下，无法
     * 保证书写入数据流目标。
     * 
     * @see http://php.net/is_uploaded_file
     * @see http://php.net/move_uploaded_file
     * @param string $targetPath 目标文件路径。
     * @throws \InvalidArgumentException 参数有问题时抛出异常。
     * @throws \RuntimeException 发生任何错误，都抛出此异常。
     * @throws \RuntimeException 多次运行，也抛出此异常。
     */
    public function moveTo($targetPath);

    /**
     * 获取文件大小。
     *
     * 实现类库 **应该** 优先使用 $_FILES 里的 `size` 数值。
     * 
     * @return int|null 以 bytes 为单位，或者 null 未知的情况下。
     */
    public function getSize();

    /**
     * 获取上传文件时出现的错误。
     *
     * 返回值 **必须** 是 PHP 的 UPLOAD_ERR_XXX 常量。
     *
     * 如果文件上传成功，此方法 **必须** 返回 UPLOAD_ERR_OK。
     *
     * 实现类库 **必须** 返回 $_FILES 数组中的 `error` 值。
     * 
     * @see http://php.net/manual/en/features.file-upload.errors.php
     * @return int PHP 的 UPLOAD_ERR_XXX 常量。
     */
    public function getError();

    /**
     * 获取客户端上传的文件的名称。
     * 
     * 永远不要信任此方法返回的数据，客户端有可能发送了一个恶意的文件名来攻击你的程序。
     * 
     * 实现类库 **应该** 返回存储在 $_FILES 数组中 `name` 的值。
     *
     * @return string|null 用户上传的名字，或者 null 如果没有此值。
     */
    public function getClientFilename();

    /**
     * 客户端提交的文件类型。
     * 
     * 永远不要信任此方法返回的数据，客户端有可能发送了一个恶意的文件类型名称来攻击你的程序。
     *
     * 实现类库 **应该** 返回存储在 $_FILES 数组中 `type` 的值。
     *
     * @return string|null 用户上传的类型，或者 null 如果没有此值。
     */
    public function getClientMediaType();
}

必须 (MUST)：绝对，严格遵循，请照做，无条件遵守；
一定不可 (MUST NOT)：禁令，严令禁止；
应该 (SHOULD) ：强烈建议这样做，但是不强求；
不该 (SHOULD NOT)：强烈不建议这样做，但是不强求；
可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少；

参见：RFC 2119

有一些基于回调函数（ Pimple，Laravel，...）
另一些基于不同格式（ PHP 数组，YAML 文件，XML 文件）的配置（ Symfony，ZF，...）
有一些可以利用工厂模式...
有一些使用 PHP API 来创建对象 （ PHP-DI，ZF，Symfony，Mouf... ）
有一些可以进行自动装载对象（ Laravel，PHP-DI，... ）
另一些可以基于注解来装载对象（ PHP-DI，JMS Bundle... ）
有一些提供图形用户界面（ Mouf... ）
有一些可以编译配置文件到 PHP 类中（ Symfony，ZF... ）
有一些可以使用对象别名...
有一些可以使用代理来提供依赖的延迟加载...

「用户不应该将容器作为参数传入对象然后在对象中通过容器获得对象的依赖。这样是把容器当作服务定位器来使用，而服务定位器是不受欢迎的模式」

// 这是不推荐的，容器被当作服务定位器来使用了
class BadExample
{
    public function __construct(ContainerInterface $container)
    {
        $this->db = $container->get('db');
    }
}

// 可以考虑使用直接注入的方式，替代上面的方式
class GoodExample
{
    public function __construct($db)
    {
        $this->db = $db;
    }
}
// 然后，你可以使用容器来将 $db 对象注入到 $goodExample 类中。

class RouterExample
{
    // ...

    public function __construct(ContainerInterface $container)
    {
        $this->container = $container;
    }

    public function getRoute($request)
    {
        $controllerName = $this->getContainerEntry($request->getUrl());
        // 这是正确的，路由通过容器查找对应的控制器对象，
        // 而路由不依赖控制器
        $controller = $this->container->get($controllerName);
        // ...
    }
}

// 这是合理的：一个创建对象的工厂接口和它的实现
interface FactoryInterface
{
    public function newInstance();
}

class ExampleFactory implements FactoryInterface
{
    protected $container;

    public function __construct(ContainerInterface $container)
    {
        $this->container = $container;
    }

    public function newInstance()
    {
        return new Example($this->container->get('db'));
    }
}

ContainerInterface: +8
ProviderInterface: +2
LocatorInterface: 0
ReadableContainerInterface: -5
ServiceLocatorInterface: -6
ObjectFactory: -6
ObjectStore: -8
ConsumerInterface: -9

所用的容器都提供了通过 id 获取对应对象的方法
大多数使用的方法名称是 get()
所有的容器中，get() 方法都有一个必须的字符串参数
一些容器的 get() 方法有一个其他可选的参数，但是不同容器的可选参数作用不一样
大多数容器都提供了一个测试是否可以通过 id 获取到对应对象的方法
大多数使用的方法名称为 has()
对于所有提供了 has() 方法的容器，它们都有一个字符串参数
大多数容器在 get() 方法没有查到对象时抛出异常，而不是返回 null
大多数容器都没有实现 ArrayAccess 接口

get() 方法，有一个必须的字符串参数，可返回任何对象。如果没有找到参数对应的对象时抛出异常。
has() 方法，有一个必须的字符串参数，返回布尔值。

尽管 ContainerInterface 接口的 get() 方法只定义了一个必须的参数，但它的实现类可以接受其他的可选参数。

接受更多可选参数违背 PHP 面向对象原则，这和 PSR-11 没有直接关系
我们不鼓励接口的实现类添加额外的可选参数，因为我们推荐面向接口编程而不是面向实现编程

请求的对象不存在（错误的请求）
或者请求对象的依赖不存在（比如容器的配置错误）

if (!$container->has($id)) {
    // 请求的对象不存在
    return;
}
try {
    $entry = $container->get($id);
} catch (NotFoundExceptionInterface $e) {
    // 因为请求的对象存在，所以 NotFoundExceptionInterface 的异常表示这是容器配置错误或者请求对象的依赖不存在。
}

已有的容器实现

Acclimate
Aura.DI
dcp-di
League Container
Mouf
Njasm Container
PHP-DI
PimpleInterop
XStatic
Zend ServiceManager

Alias-Container
Prefixer-Container

Behat
interop.silex.di
mindplay/middleman
PHP-DI Invoker
Prophiler
Silly
Slim
Splash
Zend Expressive

人员

Matthieu Napoli
David Négrier

Matthew Weier O'Phinney (Coordinator)
Korvin Szanto

Alexandru Pătrănescu
Amy Stephen
Ben Peachey
David Négrier
Don Gilbert
Jason Judge
Jeremy Lindblom
Larry Garfield
Marco Pivetta
Matthieu Napoli
Nelson J Morais
Paul M. Jones
Phil Sturgeon
Stephan Hochdörfer
Taylor Otwell

容器 PSR 和服务定位器的讨论
Container-interop 项目的  ContainerI...
所有的 issues
接口名称和 container-interop 项目范围的讨...
接口名称的投票
已有容器方法名称的统计分析
方法名称和参数的讨论
异常基类作用的讨论
NotFoundExceptionInterface...
在 container-interop  项目和 在 PHP-FIG mailing list 对 get 方法可选参数的讨论

declare(ticks=1) {
    // 一些代码
}

new Foo();

public function process(string $algorithm, ...$parts)
{
    // 函数体
}

public function process(string $algorithm, &...$parts)
{
    // 函数体
}

流程控制关键词之后 必须 要有一个空格
左括号后面 不能 有空格
右括号前面 不能 有空格
右括号与左大括号之间 必须 要有一个空格
流程主体 必须 要缩进一次
流程主体 必须 在左大括号之后另起一行
右大括号 必须 在流程主体之后另起一行

$i++;
++$j;

$intValue = (int) $input;

if ($a === $b) {
    $foo = $bar ?? $a ?? $b;
} elseif ($a > $b) {
    $foo = $a + $b * $c;
}

$variable = $foo ? 'foo' : 'bar';

$variable = $foo ?: 'bar';

必须 (MUST)：绝对，严格遵循，请照做，无条件遵守。
一定不可 (MUST NOT)：禁令，严令禁止。
应该 (SHOULD) ：强烈建议这样做，但是不强求。
不该 (SHOULD NOT)：强烈不建议这样做，但是不强求。
可以 (MAY) 和可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少。

RFC 2119
RFC 4287
RFC 5988
RFC 6570
IANA Link Relations Registry
Microformats Relations List

本规范旨在提取和标准化不同格式之间的超媒体链接表示。

本规范不寻求去标准化或偏爱任何特定超媒体序列化的格式

Larry Garfield

Matthew Weier O'Phinney (coordinator)
Marc Alexander

Evert Pot

What's in a link? by Evert Pot
FIG Link Working Group List

class A {}

class B extends A {}

$b = new B();

function listener(A $event): void {};

namespace Psr\EventDispatcher;

/**
 * Defines a dispatcher for events.
 */
interface EventDispatcherInterface
{
    /**
     * Provide all relevant listeners with an event to process.
     *
     * @param object $event
     *   The object to process.
     *
     * @return object
     *   The Event that was passed, now modified by listeners.
     */
    public function dispatch(object $event);
}

namespace Psr\EventDispatcher;

/**
 * Mapper from an event to the listeners that are applicable to that event.
 */
interface ListenerProviderInterface
{
    /**
     * @param object $event
     *   An event for which to return the relevant listeners.
     * @return iterable[callable]
     *   An iterable (array, iterator, or generator) of callables.  Each
     *   callable MUST be type-compatible with $event.
     */
    public function getListenersForEvent(object $event) : iterable;
}

namespace Psr\EventDispatcher;

/**
 * An Event whose processing may be interrupted when the event has been handled.
 *
 * A Dispatcher implementation MUST check to determine if an Event
 * is marked as stopped after each listener is called.  If it is then it should
 * return immediately without calling any further Listeners.
 */
interface StoppableEventInterface
{
    /**
     * Is propagation stopped?
     *
     * This will typically only be used by the Dispatcher to determine if the
     * previous listener halted propagation.
     *
     * @return bool
     *   True if the Event is complete and no further listeners should be called.
     *   False to continue calling listeners.
     */
    public function isPropagationStopped() : bool;
}

PSR-7
RFC 2119

namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * 处理服务器请求并返回响应
 *
 * HTTP 请求处理程序处理 HTTP 请求，以便生成 HTTP 相应。
 */
interface RequestHandlerInterface
{
    /**
     * 处理服务器请求并返回响应
     *
     * 可以调用其他协助代码来生成响应。
     */
    public function handle(ServerRequestInterface $request): ResponseInterface;
}

namespace Psr\Http\Server;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;

/**
 * 参与处理服务器的请求与响应
 *
 * 一个 HTTP 中间件组件参与处理一个 HTTP 的消息:
 * 通过对请求进行操作, 生成相应,或者将请求转发给后续的中间件，并  且可能对它的响应进行操作
 * 
 */
interface MiddlewareInterface
{
    /**
     * 处理一个传入的请求
     *
     * 处理传入的服务器请求以产生相应.
     * 如果无法生成响应本身，它可能会委托给提供的请求处理程序来执行此操作
     * 
     */
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface;
}

一个简单的缓存操作接口.
提供有关性能 (往返时间) 原因的多键操作的基本支持.
提供一个能将 PSR-6 实现转换为 PSR 简单缓存的适配器模式.
很有可能将所有的缓存 PSRs 从缓存库公开.

解决了所有可能的极端情况，PSR-6 已经做得很好了.

Paul Dragoonis (@dragoonis)

Jordi Boggiano (@seldaek) - Composer (Coordinator)
Fabien Potencier (@fabpot) - Symfony

Evert Pot (@evert)
Florin Pățan (@dlsniper)

Daniel Messenger (@dannym87)

投票入口: groups.google.com/d/topic/php-fig/...
接受投票: groups.google.com/d/msg/php-fig/A8...

现存各种缓存实现方案调查 , by @dragoonis

namespace Psr\Http\Message;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\UriInterface;

interface RequestFactoryInterface
{
    /**
     * 创建一个新的请求
     *
     * @param string $method 请求使用的 HTTP 方法。
     * @param UriInterface|string $uri 请求关联的 URI。
     */
    public function createRequest(string $method, $uri): RequestInterface;
}

namespace Psr\Http\Message;

use Psr\Http\Message\ResponseInterface;

interface ResponseFactoryInterface
{
    /**
     * 创建一个响应对象。
     *
     * @param int $code HTTP 状态码，默认值为 200。
     * @param string $reasonPhrase 与状态码关联的原因短语。如果未提供，实现 **可能** 使用 HTTP 规范中建议的值。
     */
    public function createResponse(int $code = 200, string $reasonPhrase = ''): ResponseInterface;
}

namespace Psr\Http\Message;

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\UriInterface;

interface ServerRequestFactoryInterface
{
    /**
     * 创建一个服务端请求。
     *
     * 注意服务器参数要精确的按给定的方式获取 - 不执行给定值的解析或处理。
     * 尤其是不要从中尝试获取 HTTP 方法或 URI，这两个信息一定要通过函数参数明确给出。
     *
     * @param string $method 与请求关联的 HTTP 方法。
     * @param UriInterface|string $uri 与请求关联的 URI。
     * @param array $serverParams 用来生成请求实例的 SAPI 参数。
     */
    public function createServerRequest(string $method, $uri, array $serverParams = []): ServerRequestInterface;
}

namespace Psr\Http\Message;

use Psr\Http\Message\StreamInterface;

interface StreamFactoryInterface
{
    /**
     * 从字符串创建一个流。
     *
     * 流 **应该** 使用临时资源来创建。
     *
     * @param string $content 用于填充流的字符串内容。
     */
    public function createStream(string $content = ''): StreamInterface;

    /**
     * 通过现有文件创建一个流。
     *
     * 文件 **必须** 用给定的模式打开文件，该模式可以是 `fopen` 函数支持的任意模式。
     *
     * `$filename` **可能** 是任意被 `fopen()` 函数支持的字符串。
     *
     * @param string $filename 用作流基础的文件名或 URI。
     * @param string $mode 用于打开基础文件名或流的模式。
     *
     * @throws \RuntimeException 如果文件无法被打开时抛出。
     * @throws \InvalidArgumentException 如果模式无效会被抛出。
     */
    public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface;

    /**
     * 通过现有资源创建一个流。
     *
     * 流必须是可读的并且可能是可写的。
     *
     * @param resource $resource 用作流的基础的 PHP 资源。
     */
    public function createStreamFromResource($resource): StreamInterface;
}

$resource = fopen('php://temp', 'r+');

namespace Psr\Http\Message;

use Psr\Http\Message\StreamInterface;
use Psr\Http\Message\UploadedFileInterface;

interface UploadedFileFactoryInterface
{
    /**
     * 创建一个上传文件接口的对象。
     *
     * 如果未提供大小，将通过检查流的大小来确定。
     *
     * @link http://php.net/manual/features.file-upload.post-method.php
     * @link http://php.net/manual/features.file-upload.errors.php
     *
     * @param StreamInterface $stream 表示上传文件内容的流。
     * @param int $size 文件的大小，以字节为单位。
     * @param int $error PHP 上传文件的错误码。
     * @param string $clientFilename 如果存在，客户端提供的文件名。
     * @param string $clientMediaType 如果存在，客户端提供的媒体类型。
     *
     * @throws \InvalidArgumentException 如果文件资源不可读时抛出异常。
     */
    public function createUploadedFile(
        StreamInterface $stream,
        int $size = null,
        int $error = \UPLOAD_ERR_OK,
        string $clientFilename = null,
        string $clientMediaType = null
    ): UploadedFileInterface;
}

namespace Psr\Http\Message;

use Psr\Http\Message\UriInterface;

interface UriFactoryInterface
{
    /**
     * 创建一个 URI。
     *
     * @param string $uri 要解析的 URI。
     *
     * @throws \InvalidArgumentException 如果给定的 URI 无法被解析时抛出。
     */
    public function createUri(string $uri = '') : UriInterface;
}

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;

interface ClientInterface
{
    /**
     * 发送一个 PSR-7 标准的请求，返回一个 PSR-7 格式的响应.
     *
     * @param RequestInterface $request  
     *
     * @return ResponseInterface
     *
     * @throws \Psr\Http\Client\ClientExceptionInterface 发生错误将抛出客户端异常接口对象
     * 
     */
    public function sendRequest(RequestInterface $request): ResponseInterface;
}

namespace Psr\Http\Client;

/**
 * 每个HTTP客户端相关的异常都必须实现此接口.
 */
interface ClientExceptionInterface extends \Throwable
{
}

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;

/**
 * 请求失败时的异常.
 *
 * 举例:
 *      - 请求无效 (e.g. 参数缺失)
 *      - 请求运行错误 (e.g. 响应体不可见)
 */
interface RequestExceptionInterface extends ClientExceptionInterface
{
    /**
     * 获取请求对象.
     * 
     * 请求对象可能和客户端接口发送的对象不一致.
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}

namespace Psr\Http\Client;

use Psr\Http\Message\RequestInterface;

/**
 * 因网络原因导致请求无法完成时抛出该异常.
 *
 * 抛出该异常将没有响应体，因为收不到响应体时也会抛出这个异常.
 *
 * 举例：域名不能解析或连接失败.
 */
interface NetworkExceptionInterface extends ClientExceptionInterface
{
    /**
     * 返回请求对象.
     *
     * 返回的请求对象可能和客户端接口发送的对象不一致.
     *
     * @return RequestInterface
     */
    public function getRequest(): RequestInterface;
}