翻译进度
4
分块数量
4
参与人数

PSR-11 容器接口

这是一篇协同翻译的文章,你可以点击『我来翻译』按钮来参与翻译。

容器接口

本文描述了依赖注入容器的通用接口。

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

为了避免歧义,文档大量使用了「能愿动词」,对应的解释如下:

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

参见:RFC 2119

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

轻色年华 翻译于 1个月前

1. Specification

1.1 Basics

1.1.1 Entry identifiers

An entry identifier is any PHP-legal string of at least one character that uniquely identifies an item within a container. An entry identifier is an opaque string, so callers SHOULD NOT assume that the structure of the string carries any semantic meaning.

1.1.2 Reading from a container

  • The Psr\Container\ContainerInterface exposes two methods: get and has.

  • get takes one mandatory parameter: an entry identifier, which MUST be a string. get can return anything (a mixedvalue), or throw a NotFoundExceptionInterface if the identifier is not known to the container. Two successive calls to get with the same identifier SHOULD return the same value. However, depending on the implementor design and/or user configuration, different values might be returned, so user SHOULD NOT rely on getting the same value on 2 successive calls.

  • has takes one unique parameter: an entry identifier, which MUST be a string. has MUST return true if an entry identifier is known to the container and false if it is not. If has($id) returns false, get($id) MUST throw a NotFoundExceptionInterface.

1.2 Exceptions

Exceptions directly thrown by the container SHOULD implement the Psr\Container\ContainerExceptionInterface.

A call to the get method with a non-existing id MUST throw a Psr\Container\NotFoundExceptionInterface.

1.3 Recommended usage

Users SHOULD NOT pass a container into an object so that the object can retrieve its own dependencies. This means the container is used as a Service Locator which is a pattern that is generally discouraged.

Please refer to section 4 of the META document for more details.

2. Package

The interfaces and classes described as well as relevant exceptions are provided as part of the psr/container package.

Packages providing a PSR container implementation should declare that they provide psr/container-implementation``1.0.0.

Projects requiring an implementation should require psr/container-implementation 1.0.0.

3. Interfaces

3.1. Psr\Container\ContainerInterface

<?php
namespace Psr\Container;

/**
 * Describes the interface of a container that exposes methods to read its entries.
 */
interface ContainerInterface
{
    /**
     * Finds an entry of the container by its identifier and returns it.
     *
     * @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);

    /**
     * Returns true if the container can return an entry for the given identifier.
     * Returns false otherwise.
     *
     * `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

<?php
namespace Psr\Container;

/**
 * Base interface representing a generic exception in a container.
 */
interface ContainerExceptionInterface
{
}

3.3. Psr\Container\NotFoundExceptionInterface

<?php
namespace Psr\Container;

/**
 * No entry was found in the container.
 */
interface NotFoundExceptionInterface extends ContainerExceptionInterface
{
}

本文章首发在 Laravel China 社区
本文中的所有译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

参与译者:4
讨论数量: 0
发起讨论


暂无话题~