PSR 11 容器接口

本文档描述了依赖注入容器的通用接口 This document describes a common interface for dependency injection containers.

定义 ContainerInterface 接口的目的是为框架或类库如何使用容器来获取对象和参数 ( 本文其它部分称之为实体 ) 的方式标准化

本篇规范中的必须，不得，需要，应，不应，应该，不应该，推荐，可能和可选等词按照 RFC 2119 中的描述进行解释

本文中关键字 implementor 被看作某些实现了 ContainerInterface 接口的依赖注入相关的框架或类库。使用依赖注入容器 ( DIC ) 的用户被看作 user

1. 规范

1.1 通用

1.1.1 实体标识

实体标识必须时一个长度至少为 1 的合法的 PHP 字符串，用于唯一标识容器中的一个实体

实体表示是一个常规的字符串，调用者 不应该 认为字符串的构造有任何语义含义

1.1.2 容器读操作

Psr\Container\ContainerInterface 接口定义了两个公开方法： get 和 has
get 方法声明了一个必传参数：一个使用字符串表示的实体的标识

get 方法可以返回任何内容 ( 一个存放任何数据类型的值 ) 或者当没找到标识对应的实体时抛出 NotFoundExceptionInterface 异常

连续两次使用相同的实体标识调用 get 方法应该返回相同的值

当然了，有可能会返回不同的值，这取决于 实现者 如何设计和 使用者 如何配置

因此 使用者 不应该期待在连续两次调用中会获得相同的值
has 方法声明了唯一的一个参数：一个必须使用字符串表示的实体的标识

如果实体标识对应的实体存在，那么 has 方法应当返回真值，否则返回假值

如果 has($id) 返回假值，那么调用 get($id) 必须抛出 NotFoundExceptionInterface 异常

1.2 异常

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

调用 get 方法时如果对应的实体不存在，则必须抛出 Psr\Container\NotFoundExceptionInterface 异常

1.3 推荐用法

使用者 不应该 将容器传递给一个对象，使得对象与容器之间产生耦合关系。因为这意味着采用了普遍不受欢迎的服务定位器模式 ( Service Locator Pattern )

有关更多详细的信息，可以参考 PSR-4 的说明文档

2. 命名空间

此 PSR 中定义的接口、类和相关的异常都放在 psr/container 命名空间下

任何实现了该 PSR 容器的类库都应该声明它们提供了 psr/container-implementation 1.0.0 的实现

如果项目中需要实现 PSR 则应该加载 psr/container-implementation 1.0.0

composer require psr/container-implementation 1.0.0

3. 接口

3.1. `Psr\Container\ContainerInterface`

<?php
namespace Psr\Container;

/**
 * 声明一个容器接口，并且声明一些方法用于读取容器的实体
 */
interface ContainerInterface
{
    /**
     * 根据唯一标识查找实体，并且返回这个实体
     *
     * @param string $id 要查找的实体的唯一标识
     *
     * @throws NotFoundExceptionInterface  没有找到标识对应的实体时抛出异常
     * @throws ContainerExceptionInterface 检索实体时发生错误则抛出此异常
     *
     * @return mixed 实体
     */
    public function get($id);

    /**
     * 当容器里存在唯一标识对应的实体时返回真值
     * 否则返回假
     *
     * `has($id)` 返回真值并不意味着 `get($id)` 不会抛出异常
     * 它只是表示 `get($id)` 不会抛出 `NotFoundExceptionInterface` 异常
     * 
     * @param string $id 要查找的实体的唯一标识
     *
     * @return bool
     */
    public function has($id);
}

3.2. `Psr\Container\ContainerExceptionInterface`

<?php
namespace Psr\Container;

/**
 * 用于表示容器异常的基本接口
 */
interface ContainerExceptionInterface
{
}

3.3. `Psr\Container\NotFoundExceptionInterface`

<?php
namespace Psr\Container;

/**
 * 容器里没有找到实体
 */
interface NotFoundExceptionInterface extends ContainerExceptionInterface
{
}