PSR-4(オートローダー)の日本語訳と解説

PSR-4はオートローダーの規約です。PSR-0もオートローディング規約でしたが、PSR-0は廃止予定となっており、現在オートローディングに関する規約としてはこちらが推奨されています。

Autoloader:オートローダー

[原文]

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

[日本語訳]

この文書に記載されているキーワード「しなければならない(MUST)」、「してはならない(MUST NOT)」、「必須(REQUIRED)」、「するものとする(SHALL)」、「しないものとする(SHALL NOT)」、「すべきである(SHOULD)」、「すべきでない(SHOULD NOT)」、「推奨する(RECOMMENDED)」、「することができる(MAY)」、「任意(OPTIONAL)」は、RFC 2119に記載されている内容で解釈されます。

だいたいどのPSRにも出てきますね、もはや説明は不要ですね。

1. Overview:概要

[原文]

This PSR describes a specification for autoloading classes from file paths. It is fully interoperable, and can be used in addition to any other autoloading specification, including PSR-0. This PSR also describes where to place files that will be autoloaded according to the specification.

[日本語訳]

このPSRは、ファイルパスからクラスをオートローディングするための仕様を説明しています。 PSR-0を含む、その他のオートローディングの仕様に追加して完全に相互運用可能なものです。 また、仕様に従ってオートロードされるファイルの場所についても説明しています。

PSR-0を含む他のオートローディングは邪魔しませんし、影響されないということです。

2. Specification:仕様

[原文]
  1. The term “class” refers to classes, interfaces, traits, and other similar structures.
  2. A fully qualified class name has the following form:
    \<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>
    1. The fully qualified class name MUST have a top-level namespace name, also known as a “vendor namespace”.
    2. The fully qualified class name MAY have one or more sub-namespace names.
    3. The fully qualified class name MUST have a terminating class name.
    4. Underscores have no special meaning in any portion of the fully qualified class name.
    5. Alphabetic characters in the fully qualified class name MAY be any combination of lower case and upper case.
    6. All class names MUST be referenced in a case-sensitive fashion.
  3. When loading a file that corresponds to a fully qualified class name …
    1. A contiguous series of one or more leading namespace and sub-namespace names, not including the leading namespace separator, in the fully qualified class name (a “namespace prefix”) corresponds to at least one “base directory”.
    2. The contiguous sub-namespace names after the “namespace prefix” correspond to a subdirectory within a “base directory”, in which the namespace separators represent directory separators. The subdirectory name MUST match the case of the sub-namespace names.
    3. The terminating class name corresponds to a file name ending in .php. The file name MUST match the case of the terminating class name.
  4. Autoloader implementations MUST NOT throw exceptions, MUST NOT raise errors of any level, and SHOULD NOT return a value.
[日本語訳]
  1. 「クラス」と言う用語は、クラス、インターフェース、トレイト、および他の同様の構造のことを指します。
  2. 完全修飾クラス名は下記の形式になります。
    \<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>
    1. 完全修飾クラス名には、トップレベル名前空間(ベンダー名前空間)を持たなければなりません(MUST)。
    2. 完全修飾クラス名は一つ以上のサブ名前空間を持つことができます(MAY)。
    3. 完全修飾クラス名は終端クラス名を持たなければなりません(MUST)。
    4. アンダースコアは完全修飾クラス名のどの部分にも特別な意味は持ちません。
    5. 完全修飾クラス名は大文字・小文字の組み合わせを使用することができmす(MAY)。
    6. 大文字小文字を区別してすべてのクラスを参照しなければなりません(MUST)。
  3. 完全修飾クラス名に対応するファイルをロードする場合
    1. 完全修飾クラス名の名前空間接頭語(先頭の区切り文字を含まない名前空間の連続)はベースディレクトリに対応します。
    2. 名前空間接頭語の後に続くサブ名前空間は、ベースディレクトリ内のサブディレクトリに対応し、名前空間の区切り文字はディレクトリの区切り文字を表します。また、サブディレクトリ名はサブ名前空間の大文字・小文字と一致しなければなりません(MUST)。
    3. 終端クラス名は.phpで終わるファイル名に対応します。ファイル名は終端クラス名の大文字・小文字と一致しなければなりません(MUST)。
  4. オートローダーの実装は、例外をスローしてはならず(MUST NOT)、どのレベルのエラーも発生してはなりません(MUST NOT)。また値を返すべきではありません(SHOULD NOT)。

PSR-0との大きな違いは、

  • クラス名のアンダースコア_はディレクトリの区切り文字として扱われない。
  • 「名前空間接頭語」に対して任意のディレクトリを設定できる。

というところでしょう。仕様を読んでもよくわからない場合は下記の例を見たほうが早いです。

3. Examples:例

[原文]

The table below shows the corresponding file path for a given fully qualified class name, namespace prefix, and base directory.

Fully Qualified Class Name Namespace Prefix Base Directory Resulting File Path
\Acme\Log\Writer\File_Writer Acme\Log\Writer ./acme-log-writer/lib/ ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status Aura\Web /path/to/aura-web/src/ /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request Symfony\Core ./vendor/Symfony/Core/ ./vendor/Symfony/Core/Request.php
\Zend\Acl Zend /usr/includes/Zend/ /usr/includes/Zend/Acl.php
[日本語訳]

下記の表は、指定された完全修飾クラス名、名前空間接頭語、ベースディレクトリに対応するファイルパスを表す。

完全修飾クラス名 名前空間接頭語 ベースディレクトリ ファイルパス
\Acme\Log\Writer\File_Writer Acme\Log\Writer ./acme-log-writer/lib/ ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status Aura\Web /path/to/aura-web/src/ /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request Symfony\Core ./vendor/Symfony/Core/ ./vendor/Symfony/Core/Request.php
\Zend\Acl Zend /usr/includes/Zend/ /usr/includes/Zend/Acl.php

名前空間に対するベースディレクトリへの規則性がないのは、任意のものが設定できるからです。任意のベースディレクトリの設定については下記実装例を見るとイメージしやすいかと思います。

[原文]

For example implementations of autoloaders conforming to the specification, please see the examples file. Example implementations MUST NOT be regarded as part of the specification and MAY change at any time.

[日本語訳]

仕様に準拠したオートローダーの実装例については実装例を参照してください。 この実装例は仕様の一部とみなしてはなりません(MUST NOT)。そしていつでも変更することができます(MAY)。

コメントを残す