[译文]PSR-11-容器 container

PHP规范 PSR-11 容器

本文翻译自 PSR-11-container, 限于翻译水平, 部分地方文字表达地不够清晰, 还请见谅, 如有更好的意见欢迎在评论区里提出.

配合 PSR-11-容器-规范说明 食用更为美味.
阅读本文档能够让你了解PHP关于(依赖注入)容器的标准规范.

---

容器接口 Container interface

本文档描述了一个依赖注入容器的通用接口.

ContainerInterface 设立的目的在于标准化框架和库(libraries)如何利用容器获取对象和参数.

本文档中的关键字必须 (MUST), 一定不可 (MUST NOT), 应该 (SHOULD), 不该 (SHOULD NOT), 可以 (MAY)和可选 (OPTIONAL)按照 RFC 2119 来解释.

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

本文档中的词语 实现者(implementor) 解释为在依赖注入相关的库或框架中实现 ContainerInterface 接口的人.
使用依赖注入容器(DIC)的用户称之为 用户

1. 规范 Specification

---

1.1 基础 Basics

1.1.1 条目标识符 Entry identifiers

条目标识符是任意一个至少包含一个字符的PHP合法字符串, 用于唯一标识容器中的一个项.
一个条目标识符是一个不透明的字符串, 调用者不应该 认为该字符串的结构具有任何语义含义.

1.1.2 从容器中获取 Reading from a container

• Psr\Container\ContainerInterface 接口提供了两个方法: get 和 has
• get
  
  • get 需要一个强制参数: 一个条目标识符, 它 必须 是一个字符串.
  • get 可以返回任何类型的值, 或者当它无法获取对应条目时抛出一个 NotFoundExceptionInterface 异常.
  • 连续的两次使用相同条目标识符调用 get 时 应该 返回相同的值. 但是也可能返回不同的值, 这取决于 实现者 的设计 和/或 用户 配置, 因此 用户 不该 依赖在两次连续调用中获得相同的值.
• has
  
  • has 需要一个唯一的参数: 一个条目标识符, 它 必须 是一个字符串.
  • 如果一个条目标识符对于该容器是可知的, has 必须 返回 true 否则返回 false.
  • 如果 has($id) 返回 false, get($id) 必须 抛出一个 NotFoundExceptionInterface异常.

1.2 异常 Exceptions

容器直接抛出的异常 应该 实现 Psr\Container\ContainerExceptionInterface 接口.

传入不存在的id来调用 get时, 必须 抛出一个 Psr\Container\NotFoundExceptionInterface 异常.

Psr\Container\ContainerExceptionInterface 接口具体实现见下文

1.3 推荐用法 Recommended usage

用户 不该 为了让对象能够检索自己的依赖而将容器传递给对象. 因为这意味着容器被作为 服务器定位器使用, 这是不被推荐使用的模式.

有关更多详细信息, 请参阅 META文档.

2. 包 Package

---

psr/container 包提供了本文档中所描述的接口和类以及相关的异常.

提供符合PSR规范容器实现的包应声明他们提供了 psr/container-implementation 1.0.0, 如下所示.

需要一个PSR容器实现的项目应包含 psr/container-implementation 1.0.0

3. 接口 Interfaces

---

3.1 Psr\Container\ContainerInterface

namespace Psr\Container;

/**
 * 描述容器的接口, 该容器对外提供方法以获取其中的条目.
 */
interface ContainerInterface
{
    /**
     * 通过条目标识符来查找容器中的条目并返回该条目
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @throws NotFoundExceptionInterface  No entry was found for **this** identifier.
     * @throws ContainerExceptionInterface Error while retrieving the entry.
     *
     * @return mixed Entry.
     */
    public function get($id);

    /**
     * 如果容器可以返回给定条目标识符对应的条目, 则返回true, 否则返回false
     *
     * `has($id)` returning true does not mean that `get($id)` will not throw an exception.
     * It does however mean that `get($id)` will not throw a `NotFoundExceptionInterface`.
     *
     * @param string $id Identifier of the entry to look for.
     *
     * @return bool
     */
    public function has($id);
}

3.2 Psr\Container\ContainerExceptionInterface

namespace Psr\Container;

/**
 * 容器中用来表示一般异常的基础接口
 */
interface ContainerExceptionInterface
{
}

3.3 Psr\Container\NotFoundExceptionInterface

namespace Psr\Container;

/**
 * 容器中无法获取指定条目
 */
interface NotFoundExceptionInterface extends ContainerExceptionInterface
{
}