— y2sunlight 2020-05-25

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

• PSR - PHP標準勧告
• PSR-1: Basic Coding Standard - 基本コーディング規約
• PSR-3: Logger Interface - ロガーインターフェイス
• PSR-4: Autoloading Standard - オートローディング規約
• PSR-5: PHPDoc Standard(Draft) - PHPDoc規約
• PSR-6: Caching Interface - キャッシングインターフェイス
• PSR-7: HTTP Message Interface - HTTPメッセージインターフェイス
• PSR-11: Container Interface - コンテナインターフェイス
• PSR-12: Extended Coding Style Guide - 拡張コーディングスタイルガイド
• PSR-13: Link definition interfaces - リンク定義インターフェース
• PSR-14: Event Dispatcher - イベントディスパッチャー
• PSR-15: HTTP Handlers - HTTPハンドラー

— // 原文より翻訳 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文字のPHPの正当な文字列で、コンテナ内のアイテムを一意に識別します。 エントリ識別子は不透明(opaque)な文字列であるため、呼び出し元は文字列の構造に意味的な物があると仮定してはなりません ( SHOULD NOT )。

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

• get takes one mandatory parameter: an entry identifier, which MUST be a string. get can return anything (a mixed value), 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.
  
  getは、必須のパラメータを1つ取ります：それはエントリ識別子で文字列でなければなりません (MUST)。 getは何でもを返すことができ( mixed value )、識別子がコンテナに認識されない場合はNotFoundExceptionInterfaceをスローできます。 同じ識別子で取得する2つの連続した呼び出しは、同じ値を返すべきです (SHOULD)。 ただし、実装者の設計やユーザー設定によっては、異なる値が返される可能性があるため、ユーザーは2つの連続した呼び出しで同じ値を取得することに依存すべきではありません (SHOULD NOT)。

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

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

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

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

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

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.

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

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

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

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

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

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

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

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

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

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 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.
     * コンテナが指定された識別子のエントリを返すことができる場合は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 Identifier of the entry to look for.
     *                   検索するエントリの識別子
     *
     * @return bool
     */
    public function has($id);
}

ContainerExceptionInterface.php

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

NotFoundExceptionInterface.php

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