PSR-11: Container interface

— y2sunlight 2020-05-25

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

PSR-11: コンテナインターフェース

— 原文より翻訳 PSR-11: Container interface 2020-05-25 現在

このドキュメントでは、依存性注入コンテナの一般的なインターフェースについて説明します。

ContainerInterface が設定する目標は、フレームワークとライブラリがコンテナーを使用してオブジェクトとパラメーター（以下では「エントリ」と呼びます）を取得する方法を標準化することです。

このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。

RFC 2119の説明
MUST, REQUIRED, SHALL — 絶対必要
MUST NOT, SHALL NOT — 絶対禁止
SHOULD, RECOMMENDED — 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT — 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY, OPTIONAL — オプション

このドキュメントの「インプリメンター」という言葉は、依存性注入に関連するライブラリまたはフレームワークに ContainerInterface を実装している人のことと解釈して下さい。依存性注入コンテナー(DIC)の利用者は「ユーザー」と呼びます。

1. 仕様

1.1 基本

1.1.1 エントリ識別子

エントリ識別子は、少なくとも1文字のPHPの正当な文字列で、コンテナ内のアイテムを一意に識別します。エントリ識別子は不透明(opaque)な文字列であるため、呼び出し元は文字列の構造に意味的な物があると仮定してはなりません ( SHOULD NOT )。

1.1.2 Reading from a containerコンテナーからの読み取り

Psr\Container\ContainerInterfaceは、get と has の2つのメソッドを公開しています。

get は、必須のパラメータを1つ取ります：そのパラメータはエントリ識別子で、文字列でなければなりません ( MUST )。 get は何でもを返すことができ( mixed value )、識別子がコンテナに認識されない場合はNotFoundExceptionInterface をスローできます。同じ識別子で取得する2つの連続した呼び出しは、同じ値を返すべきです ( SHOULD )。ただし、実装者の設計やユーザー設定によっては、異なる値が返される可能性があるため、ユーザーは2つの連続した呼び出しで同じ値を取得することに依存すべきではありません ( SHOULD NOT )。

has は、一意のパラメータを1つ取ります：そのパラメータはエントリ識別子で、文字列でなければなりません ( MUST )。has はエントリ識別子がコンテナに認識されている場合は true を、認識されていない場合は false を返す必要があります ( MUST )。has($id) が false を返す場合、get($id) はNotFoundExceptionInterface をスローする必要があります ( MUST )。

1.2 例外

コンテナによって直接スローされる例外は Psr\Container\ContainerExceptionInterface を実装すべきです ( SHOULD )。

存在しないIDでgetメソッドを呼び出すと、Psr\Container\NotFoundExceptionInterface がスローする必要があります ( MUST )。

1.3 推奨される使用法

オブジェクトが独自の依存関係を取得できるように、ユーザーはコンテナをオブジェクトに渡すべきではありません ( SHOULD NOT )。つまり、コンテナーをサービスロケーターとして使用することは、一般的には推奨されないパターンです。

詳細については、METAドキュメントのセクション4を参照してください。

2. パッケージ

説明されているインターフェースとクラス、および関連する例外は、psr/container パッケージの一部として提供されます。

PSRコンテナーの実装を提供するパッケージは、psr/container-implementation 1.0.0 を提供することを宣言する必要があります。

実装が必要なプロジェクトでは、psr/container-implementation 1.0.0 を要求する必要があります。

3. インターフェース

3.1. Psr\Container\ContainerInterface

ContainerInterface.php

<?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 検索するエントリの識別子
     *
     * @throws NotFoundExceptionInterface  この識別子のエントリが見つかりませんでした
     * @throws ContainerExceptionInterface エントリの取得中にエラーが発生しました
     *
     * @return mixed エントリ
     */
    public function get($id);
 
    /**
     * Returns true if the container can return an entry for the given identifier.
     * Returns false otherwise.
     * 
     * コンテナが指定された識別子のエントリを返すことができる場合は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`.
     * 
     * has($id)がtrueを返すことは、get($id)が例外をスローしないことを意味しません。
     * ただし、get($id)はNotFoundExceptionInterfaceをスローしないことは意味します。
     *
     * @param string $id 検索するエントリの識別子
     *
     * @return bool
     */
    public function has($id);
}

3.2. Psr\Container\ContainerExceptionInterface

ContainerExceptionInterface.php

<?php
namespace Psr\Container;
 
/**
 * Base interface representing a generic exception in a container.
 * コンテナの一般的な例外を表す基本インターフェース
 */
interface ContainerExceptionInterface
{
}

3.3. Psr\Container\NotFoundExceptionInterface

NotFoundExceptionInterface.php

<?php
namespace Psr\Container;
 
/**
 * No entry was found in the container.
 * コンテナにエントリが見つかりませんでした
 */
interface NotFoundExceptionInterface extends ContainerExceptionInterface
{
}

目次