PSR-1: Basic Coding Standard

— y2sunlight 2020-04-21

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

PSR-1: 基本コーディング規約

— 原文より翻訳 PSR-1: Basic Coding Standard 2020-04-21 現在

このセクションの規約は、共有されるPHPコードにおいて、高度な技術的相互運用性を保証するために必要な標準コーディング要素と見なす必要があるもので構成されています。

このドキュメントのキーワード 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 — オプション

1. 概観

ファイルは、<?php と <?= タグのみを使用する必要があります (MUST)
ファイルは、BOMなしのUTF-8のみを使用する必要があります (MUST)
ファイルは、シンボル（クラス、関数、定数など）を宣言するか、または副作用（例えば、出力の生成や.ini設定の変更など）を引き起こすかのいずれか行うべきです (SHOULD)。両方を行うべきではありません (SHOULD NOT)
名前空間とクラスは、オートローディングPSR(PSR-0, PSR-4)に従う必要があります (MUST)
クラス名は、StudlyCaps (Upper Camel Case または Pascal Case) で宣言する必要があります (MUST)
クラス定数は、アンダースコア区切りの大文字で宣言する必要があります (MUST)
メソッド名は、camelCase で宣言する必要があります (MUST)

StudlyCaps(UCC: Upper Camel Case)とcamelCase(LCC: Lowere Camel Case)については以下を参照
キャメルケース

2. ファイル

2.1 PHPタグ

PHPコードは長いタグ <?php ?> または短いechoタグ <?= ?> を使用する必要があります。他のタグのバリエーションを使用してはなりません( MUST )。

2.2 文字コード

PHPコードはBOMなしのUTF-8のみを使用する必要があります( MUST )。

2.3 副作用

ファイルは、新しいシンボル（クラス、関数、定数など）を宣言する場合は、他の副作用を引き起こさないようにする必要があります( SHOULD )。また、副作用を伴うロジックを実行する必要がある場合は、宣言を行うべきではありません( SHOULD NOT )。

「副作用」という語句は、クラス、関数、定数などの宣言に直接関係しないロジックの実行を意味し、ファイルをインクルードするだけで、ロジックが実行されることを意味します。

「副作用」には、以下が含まれますが、これらに限定されません。

出力の生成
requireまたはincludeの明示的な使用
外部サービスへの接続
ini設定の変更
エラーまたは例外の発行
ローバル変数または静的変数の変更
ファイルの読み取りまたは書き込み　など

以下は、宣言と副作用の両方を含むファイルの例です。つまり、避けるべき例です：

<?php
// 副作用：ini設定の変更
ini_set('error_reporting', E_ALL);
 
// 副作用：ファイルのロード
include "file.php";
 
// 副作用：出力の生成
echo "<html>\n";
 
// 宣言
function foo()
{
    // 関数本体
}

次の例は、副作用のない宣言を含むファイルです。つまり、見習うべき例です：

<?php
// 宣言
function foo()
{
    // 関数本体
}

// 条件付き宣言は副作用ではありません
if (! function_exists('bar')) {
    function bar()
    {
        // 関数本体
    }
}

3. 名前空間とクラス名

名前空間とクラスは、オートローディングPSR (PSR-0, PSR-4) に従う必要があります( MUST )。

これは、各クラスがそれ自体でファイル内にあり、少なくとも1つのレベルのネームスペース（トップレベルはベンダー名です）にあることを意味します。

クラス名はStudlyCapsで宣言する必要があります( MUST )。

StudlyCapsとは、Upper Camel Case または Pascal Caseと同意です。

PHP 5.3以降用に記述されたコードは、正式な名前空間を使用する必要があります( MUST )。

例えば：

<?php
// PHP 5.3以降
namespace Vendor\Model;
 
class Foo
{
}

5.2.x以前向けに記述されたコードは、クラス名の前にプレフィックス( Vendor_ など)の疑似名前空間規則を使用する必要があります( SHOULD )。

<?php
// PHP 5.2.xおよびそれ以前
class Vendor_Model_Foo
{
}

4. クラス定数、プロパティ、メソッド

「クラス」という用語は、すべてのクラス(class)、インターフェース(interface)、およびトレイト(trait)を指します。

4.1 定数

クラス定数は、アンダースコア区切りで大文字で宣言する必要があります( MUST )。例えば以下のようです：

namespace Vendor\Model;
 
class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

4.2 プロパティ

このガイドでは、プロパティ名について、StudlyCaps、camelCase、または under_score の使用に関する推奨を意図的に避けています。

StudlyCapsとは、Upper Camel Case または Pascal Caseと同意です。
camelCaseとは、Lower Camel Case と同意です。
under_scoreとは、Snake Case と同意です。

どのような命名規則が使用されていても、合理的なスコープで一貫して適用されるべきです。そのスコープとは、ベンダーレベル、パッケージレベル、クラスレベル、またはメソッドレベルなどでしょう( SHOULD )。

4.3 メソッド

メソッド名は camelCase で宣言する必要があります( MUST )。

目次