本規約は、共有される PHP コードにおいて高い技術レベルでの連携を確保するために必要とされる基本的なコーディング要素を考慮したうえで構成されています。
前提条件
あいまいさを避けるため、あらかじめ下記用語について説明します。
-
~しなければなりません
:必ず、必須。 -
~してはいけません
:厳禁、禁止。 -
~したほうがいいです
:するべきです。オススメです。 -
~しないほうがいいです
:不向き、不適切なやり方。 -
~してもいいです
:可能、許可。
参考:RFC 2119
1. 概要
-
PHP コードは
<?php
或いは<?=
タグを使用しなければなりません。 -
PHP 文字コードは UTF-8(BOM無し)を使用しなければなりません。
-
シンボル(クラス、関数、定数など)を宣言するためのファイルと、副作用のある処理(出力の生成、ini設定の変更など)を行うためのファイルは、分けたほうがいいです。
-
名前空間、クラスについては PSR-4 に準拠しなければなりません。
-
クラス名は、
StudlyCaps
のように単語の先頭文字を大文字で表記する アッパーキャメルケース で定義しなければなりません。 -
クラス定数は全て大文字とし、区切り文字にはアンダースコア(スネークケース)を用いて定義しなければなりません。
-
メソッド名は、
camelCase
のように単語の先頭文字を小文字で表記する ローワーキャメルケース で定義しなければなりません。
2. ファイル
2.1. PHP タグ
PHP コードは <?php ?>
或いは <?= ?>
タグを使用しなければなりません。 それ以外のタグを使用してはいけません。
2.2. 文字コード
PHP 文字コードは UTF-8(BOM無し)を使用しなければなりません。
2.3. 副作用
新たなシンボル(クラス、関数、定数など)を宣言するためのファイルと、 副作用のある処理を行うためのファイルは、分けたほうがいいです。 一つのファイルの中で両方を行うようにしないほうがいいです
ここでの「副作用」(side effects) とは、クラス、関数、定数を宣言するのに直接関係しない処理が、単にファイルを取り込んだだけで実行されてしまうことを指します。
副作用のある処理には、次のようなものが含まれます。ただし、挙げるものが全てではありません:
- 出力の生成
- 直接に
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-4 に準拠しなければなりません。
PSR-4 によると、1 クラス 1 ファイルにしなければなりません。 尚且つ、 少なくともトップレベル(vendor name)の名前空間を定義しなければなりません。
クラス名は、StudlyCaps
のように単語の先頭文字を大文字で表記する アッパーキャメルケース で定義しなければなりません。
PHP 5.3 以降では、正しい名前空間を使用しなければなりません。
例えば:
<?php
// PHP 5.3 以降
namespace Vendor\Model;
class Foo
{
}
PHP 5.2以前では、クラス名に「Vendor_」接頭辞を使用し、擬似名前空間としたほうがいいです。
<?php
// PHP 5.2以前
class Vendor_Model_Foo
{
}
4. クラス定数、プロパティ及びメソッドについて
ここでのクラスは、全ての一般クラス、インターフェイス、trait を含みます。
4.1. 定数
クラス定数は全て大文字とし、区切り文字にはアンダースコア(スネークケース)を用いて定義しなければなりません。
例えば:
<?php
namespace Vendor\Model;
class Foo
{
const VERSION = '1.0';
const DATE_APPROVED = '2012-06-01';
}
4.2. プロパティ
プロパティの命名規則として下記のような形式で定義してもいいです
-
アッパーキャメルケース (
$StudlyCaps
) -
ローワーキャメルケース (
$camelCase
) -
スネークケース (
$under_score
)
どのような命名規則を使用するにせよ、適切なスコープ内において一貫性を持たせたほうがいいです。 ここでのスコープは、ベンダーレベル、パッケージレベル、クラスレベルまたはメソッドレベルを指します。
4.3. メソッド
メソッド名は、camelCase
のように単語の先頭文字を小文字で表記する ローワーキャメルケース で定義しなければなりません。
※本記事は『日本語ドキュメント作成スタイル基準規約』に基づいて作成されています
※本記事は弊社社員の呉傑が Lindelin.org の寄稿記事として執筆した記事を転載し、公開したものです。