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 接口定义了两个公开方法: gethas

  • 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
{
}

PHP 标准规范

关于   |   FAQ   |   我们的愿景   |   广告投放   |  博客

  简单教程,简单编程 - IT 入门首选站

Copyright © 2013-2022 简单教程 twle.cn All Rights Reserved.