PHPファイルのフォーマット

一般

PHPコードのみのファイルには、閉じタグ(“?>”)は使ってはなりません。PHPには必須ではないからです。これを含めないことで意図しない末尾の空白が出力に混入されることが防止されます。

NOTE ``__HALT_COMPILER()``による任意のバイナリデータのインクルードはDoctrine Frameworkによって禁止されています。この機能の使用は特別なインストールスクリプトでのみ許可されます。

インデント

4スペースのインデントを使います。タブは使いません。

最大の長さ

ターゲットの行の長さは80文字です。すなわち慣習として開発者は80カラム以内にコードを維持すべきです。しかしながら、より長い行も許容されます。PHPコードの最大長は120文字です。

改行

改行は行の終わりを表現するためのUnixテキストファイルの標準的な方法です。行はラインフィード(LF - linefeed)のみで終わらなければなりません。ラインフィードは通常の10もしくは16進法の0x0Aとして表現されます。

Macintoshコンピュータ(0x0D)のようにキャリッジリターン(CR - carriage returns)を使わないでください。 またWindowsコンピュータ(0x0D, 0x0A)のようにキャリッジリターンとラインフィードの組み合わせ(CRLF)をつかわないでください。

命名慣習

クラス

Doctrine ORM FrameworkはPEARとZendフレームワークと同じクラスの命名慣習を使います。クラスの名前はそれらを保存するディレクトリを直接指し示します。Doctrine Frameworkのrootレベルディレクトリは”Doctrine/”ディレクトリで、この下ですべてのクラスが階層状に保存されます。

クラスの名前はアルファベットの文字のみ含むことが許可されます。数字も許可されますが非推奨です。アンダースコアはパス区切りの位置のみ許可されます。例えば”Doctrine/Table/Exception.php”というファイルの名前は”Doctrine\_Table_Exception“に対応します。

クラスの名前が複数の単語で構成される場合、それぞれの新しい単語の最初の文字は大文字にしなければなりません。連続する大文字は許可されません例えば”XML_Reader”クラスは許可されませんが”Xml_Reader”は受け入れられます。

インターフェイス

インターフェイスは他のクラスと同じ慣習に従わなければなりません(上記を参照)。

これらの名前は”Interface”という単語で終わらなければなりません(``Doctrine_Overloadable``といったものは認められません)。例です:

  • Doctrine\_Adapter_Interface
  • Doctrine\_EventListener_Interface

ファイルの名前

他のすべてのファイルに関して、アルファベット、アンダースコア、とダッシュ(“-”)のみが許可されます。スペースは禁止です。PHPコードを含むファイルは”.php”の拡張子で終わらなければなりません。次の例は上記のセクションの例からクラスの名前を含めるために受け入れられるファイルの名前を示します:

  • Doctrine/Adapter/Interface.php
  • Doctrine/EventListener/Interface

ファイルの名前は先ほど説明したクラスの名前のマッピング方法に従わなければなりません。

関数とメソッド

関数名はアルファベットのみで構成されアンダースコアは認められません。数字も認められますが非推奨です。関数の名前は常に小文字で始まらなければならず複数の単語で構成される場合、それぞれの単語の最初の文字は大文字で始まらなければなりません。この表記は”studlyCaps”もしくは”camelCaps”メソッドと呼ばれます。冗長性が推奨されコードの可読性を強化するために関数の名前は実用的に冗長でなければなりません。

オブジェクト指向のプログラミングに関して、オブジェクトのアクセサには”get”もしくは”set”の接頭辞をつけなければなりません。’obtain’と’assign’を接頭辞とするアクセサを持つ``Doctrine_Record``以外のすべてのクラスに対してこの原則は適用されます。この理由はすべてのユーザーが``Doctrine_Record``を継承するActiveRecordを定義したので、できる限り最小のget/setの名前空間が投入されるからです。

NOTE グローバルスコープの関数は許可されません。すべてのスタティック関数はスタティッククラスにラップされます。

変数

変数の名前にはアルファベットのみが許可されます。アンダースコアは許可されません。数字は許可されますが非推奨です。これらは小文字で始まり”camelCaps”のルールに従わなければなりません。冗長性は推奨されます。変数は常に冗長で実用的であるべきです。最小のループコンテキスト以外では”i"と"n”のような簡単な変数名は非推奨です。ループの箇所が20行以上のコードである場合、インデックス用の変数は説明のような名前をより多く持つことが必要です。フレームワークの範囲内で特定のジェネリックオブジェクト変数は次の名前を使います:

||~ オブジェクトの型 ||~ 変数名 || || Doctrine_Connection || $conn || || Doctrine_Collection || $coll || || Doctrine\_Manager || $manager || || Doctrine_Query || $q ||

より説明のような名前が適切であることがあります(例えば同じクラスん複数のオブジェクトが同じコンテキストで使われるとき)。このケースでは異なる名前を使うことが許可されます。

定数

定数にはアルファベットとアンダースコアの両方が許可されます。これらは常にすべてが大文字です。可読性のために、定数の単語はアンダースコアで区切らなければなりません。例えば、``ATTR_EXC_LOGGING``は許可されますが``ATTR_EXCLOGGING``は許可されません。定数は”const”コンストラクトを使用してクラスメンバーとして定義しなければなりません。グローバルスコープで”define”を使用して定数を定義するのは許可されていません。

class Doctrine_SomeClass { const MY_CONSTANT = ‘something’; }

echo $Doctrine_SomeClass::MY_CONSTANT;

レコードのカラム

すべてのレコードのカラムは小文字でカラムが複数の単語で構成される場合はアンダースコア(_)の使用が推奨されます。

class User { public function setTableDefinition() {

$this->hasColumn(‘home_address’, ‘string’); } }

外部キーフィールドは``[table_name]_[column]``の形式でなければなりません。次の例は``user(id)``を指し示す外部キーです:

class Phonenumber extends Doctrine_Record { public function

setTableDefinition() { $this->hasColumn(‘user_id’, ‘integer’); } }

コーディングスタイル

PHPコードの境界

PHPコードはフルフォームの標準のPHPタグで常に区切らなければならずショートタグは許可されません。PHPコードのみのファイルでは、閉じタグを常に省略しなければなりません。

文字列

文字列がリテラルであるとき(変数の置き換えを含まない)、文字列を区切るためにアポストロフィもしくは”シングルクォート”を使わなければなりません:

リテラル文字列

$string = ‘something’;

リテラル文字列自身がアポストロフィを含むとき、クォテーション記号もしくは”ダブルクォート”で文字列を区切ることが許可されます。これはとりわけSQL文で推奨されます:

アポストフィを含む文字列

$sql = “SELECT id, name FROM people WHERE name = ‘Fred’ OR name =

‘Susan’”;

変数の置き換え

変数の置き換えは次の形式で許可されます:

// variable substitution $greeting = “Hello $name, welcome back!”;

文字列の連結

複数の文字列は”.”演算子を使用して連結できます。可読性を向上させるために”.”演算子の前後でスペースを常に追加します:

$framework = ‘Doctrine’ . ‘ ORM ‘ . ‘Framework’;

改行の連結

文字列を”.”演算子で連結するとき、可読性を向上させるためにステートメントを複数行に分割することが許可されます。このケースでは、それぞれの連続行はホワイトスペースで詰められます。”.”演算子は”=”演算子の下に並べられます:

$sql = “SELECT id, name FROM user ” . “WHERE name = ? ” . “ORDER BY

name ASC”;

配列

インデックスには負の数は許可されず負ではない数で始まらなければなりません。しかしながらこれは非推奨ですべての配列に0を起点とするインデックスを持たせることが推奨されます。arrayコンストラクトでインデックス付きの配列を宣言するとき、可読性を向上させるために行末のスペースをそれぞれのコンマ区切り文字の後に追加しなえkればなりません。”array”コンストラクトで複数行のインデックス付きの配列を宣言することも許可されます。このケースでは、それぞれの連続する行はスペースで詰められます。arrayコンストラクタで連想配列を宣言するとき、ステートメントを複数行に分割することが推奨されます。この場合、キーと値が並ぶように、連続するそれぞれの行はホワイトスペースで埋めなければなりません:

$sampleArray = array(‘Doctrine’, ‘ORM’, 1, 2, 3);
$sampleArray = array(1, 2, 3, $a, $b, $c,
56.44, $d, 500);

$sampleArray = array(‘first’ => ‘firstValue’, ‘second’ => ‘secondValue’);

クラス

クラスは次の命名慣習に従って名付けなければなりません。クラスの名前(もしくはinterface宣言)の後の次の行にかっこを常に書かなければなりません。すべてのクラスはPHPDocumentor標準に従うドキュメントブロックを持たなければなりません。クラスの範囲内のコードは4つのスペースでインデントして1つのPHPファイルにつき1つのクラスのみ許可されます。クラスファイルにコードを追加することは許可されません。

受け入れられるクラス宣言の例は次の通りです:

/** * Documentation here */ class Doctrine_SampleClass { // entire

content of class // must be indented four spaces }

関数とメソッド

メソッドは以下の命名慣習に従いprivate、protected、もしくはpublicコンストラクトの1つを使用して可視性を常に宣言しなければなりません。クラスのように、かっこはメソッドの名前の後の次の行に書きます。関数名と引数用の開き波かっこの間にはスペースは入れません。グローバルスコープの関数は非推奨です。クラス内の関数宣言の許容される例は次の通りです:

/** * Documentation Block Here / class Foo { /* * Documentation

Block Here */ public function bar() { // entire content of function // must be indented four spaces }

public function bar2()
{

}

}

NOTE メソッドの間の改行は上記の``bar()``と``bar2()``メソッドのように行われます。

参照渡しは関数の宣言でのみ許可されます:

/** * Documentation Block Here / class Foo { /* * Documentation

Block Here */ public function bar(&$baz) { } }

呼び出し時の参照渡しは禁止です。戻り値は丸かっこで囲んではなりません。これは可読性を下げるだけでなく後でメソッドが参照渡しに変更された場合にコードを壊す可能性があります。

/** * Documentation Block Here / class Foo { /* * WRONG */ public function bar() { return($this->bar); }
/**
 * RIGHT
 */
public function bar()
{
    return $this->bar;
}

}

関数の引数は区切り文字のコンマの後の単独スペースで区切られます。3つの引数を受け取る関数の呼び出し例は次の通りです:

threeArguments(1, 2, 3);

呼び出し時の参照渡しは禁止です。関数の引数を参照渡しする適切な方法は上記の内容をご覧ください。引数に配列を許可する関数に関しては、可読性を向上させるためにarrayコンストラクトを含む関数呼び出しは複数行に分割されます。これらのケースでは、配列の適切な書き方は次のようになります:

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, ‘Framework’, ‘Doctrine’, 56.44, 500), 2, 3);

制御文

ifとelseifコンストラクトに基づく制御文では開き丸かっこと閉じ丸かっこの前後に単独のスペースを置かなければなりません。丸かっこの間の条件文の範囲では、可読性のために演算子はスペースで区切らなければなりません。大きな条件の論理的なグルーピングを改善するために内側の丸かっこは推奨されます。開き波かっこは条件文と同じ行で書きます。閉じ波かっこは専用の行で書きます。かっこ内の内容は4つのスペースでインデントしなければなりません。

if ($foo != 2) { $foo = 2; }

elseifもしくはelseを含むif文に対して、形式は次のようにならなければなりません:

if ($foo != 1) { $foo = 1; } else { $foo = 3; }

if ($foo != 2) { foo = 2; } elseif (foo == 1) { $foo = 3; } else {

$foo = 11; }

!オペランドを使うときは次の形式に従わなければなりません:

if ( ! $foo) {

}

switchコンストラクトで書く制御文では開き丸かっこの前と閉じ丸かっこの後でそれぞれの単独のスペースを置かなければなりません。switch文の範囲内のすべての内容は4つのスペースでインデントしなければなりません。それぞれのcase文の下の内容は追加の4つの追加スペースでインデントしなければなりませんがbreak文はcase文と同じインデントレベルでなければなりません。

switch ($case) { case 1: case 2: break; case 3: break; default: break;

}

defaultコンストラクトはswitch文から省略してはなりません。

インラインドキュメント

ドキュメントのフォーマット:

すべてのドキュメントブロック(“docblocks”)はphpDocumentorのフォーマットと互換性がなければなりません。phpDocumentorのフォーマットの説明はこのドキュメントの範囲を越えるので詳細は、http://phpdoc.org/のサイトを訪問してください

すべてのメソッドは、最小限のdocblockを持たなければなりません:

  • 関数の説明
  • すべての引数
  • 可能なすべての戻り値
  • 関数を宣言するのに使われるpublic、privateもしくはprotectedからアクセスレベルが既知なので@accessタグを使う必要がない場合

関数/メソッドが例外を投げる場合、@throwsを使います:

/* * Test function * * @throws Doctrine_Exception */ public

function test() { throw new Doctrine_Exception(‘This function did not work’); }

まとめ

この章は//Doctrine ORM for PHP - Guide to Doctrine for PHP//の最後の章です。この本が本当に役立ちDoctrineを快適に使い必要なときに調べるために戻ってくださることを筆者は心より願っております。

常に、Doctrineと共にありますように :)

Thanks, Jon