PHP コードの境界

PHP のコードの区切りには、標準 PHP タグを常に使用しなければなりません。

<?php
 
?>

短いタグは決して使用してはいけません。 PHP コードのみからなるファイルでは、終了タグ ("?>") は決して含めてはいけません (全般を参照ください)。

文字列

文字列リテラル

文字列がリテラルである (変数の展開などが含まれない) 場合は、アポストロフィあるいは「シングルクォート」で文字列を囲まなければなりません。

$a = '文字列の例';

アポストロフィを含む文字列リテラル

リテラル文字列自体にアポストロフィが含まれている場合は、引用符あるいは「ダブルクォート」で文字列を囲んでもかまいません。特に SQL 文などでこのような場合がよくあるでしょう。

$sql = "SELECT `id`, `name` from `people` "
     . "WHERE `name`='Fred' OR `name`='Susan'";

アポストロフィをエスケープするよりも、上の構文のほうが読みやすくなるのでお勧めです。

変数の展開

変数の展開を行うには、次のような方法を使用します。

$greeting = "こんにちは $name さん。ようこそ!";
 
$greeting = "こんにちは {$name} さん。ようこそ!";

一貫性を保つため、以下の形式は許可されません。

$greeting = "こんにちは ${name} さん。ようこそ!";

文字列の連結

文字列の連結には "." 演算子を使用しなければなりません。コードを読みやすくするため、 "." 演算子の前後には常にスペースを入れなければなりません。

$company = 'Zend' . ' ' . 'Technologies';

文字列を "." 演算子で連結する際には、コードを読みやすくするためにひとつの文を複数行に分けることもできます。そのような場合は、 2 行目以降の行頭にスペースを入れ、各行の "." 演算子が最初の行の "=" 演算子と同じ位置にくるようにしなければなりません。

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";

配列

数値添字の配列

添字として負の数を使用してはいけません。

数値添字の配列の添字は、0 以上の任意の数から始めることができます。しかし、常に 0 から始めるようにすることを推奨します。

Array を使用して数値添字の配列を宣言する場合は、コードを読みやすくするため、要素を区切るカンマの後にスペースを入れなければなりません。

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');

"array" を使用して、複数行にまたがる配列を宣言することも可能です。その場合は、2 行目以降の行頭にスペースを入れ、各行の開始位置が以下のようになるようにしなければなりません。

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);

一方、配列の最初の要素を次の行から始めることもできます。その場合は、配列を宣言した位置からさらに一段インデントした位置で要素をそろえ、それ以降のすべての要素を同じインデントで記述するようにします。閉じ括弧はそれ単体でひとつの行に記述し、インデント量は配列の宣言と同じ位置になります。

$sampleArray = array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500,
);

この宣言を使用する際は、配列の最後の要素の後にもカンマをつけておくようにしましょう。そうすることで、配列に新たな要素を追加したときにパースエラーが発生する危険性を少なくできます。

連想配列

連想配列を Array で宣言する場合には、適宜改行をいれて複数行で宣言するようにしましょう。その場合は、 2 行目以降の行頭などにスペースを入れ、キーと値の位置がそれぞれ揃うようにしなければなりません。

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');

一方、配列の最初の要素を次の行から始めることもできます。その場合は、配列を宣言した位置からさらに一段インデントした位置で要素をそろえ、それ以降のすべての要素を同じインデントで記述するようにします。閉じ括弧はそれ単体でひとつの行に記述し、インデント量は配列の宣言と同じ位置になります。可読性を高めるため、代入演算子 "=>" の位置はそろえておかなければなりません。

$sampleArray = array(
    'firstKey'  => 'firstValue',
    'secondKey' => 'secondValue',
);

この宣言を使用する際は、配列の最後の要素の後にもカンマをつけておくようにしましょう。そうすることで、配列に新たな要素を追加したときにパースエラーが発生する危険性を少なくできます。

クラス

クラス宣言

クラス宣言は、以下の Zend Framework 命名規約に従わなければなりません。

開始波括弧は常にクラス名の下に書かなければなりません。

PHPDocumentor の標準形式のドキュメントブロックがなければなりません。

クラス内のコードは、すべて空白 4 文字で字下げします。

ひとつの PHP ファイルにはクラス定義をひとつだけ含めるようにします。

クラスファイルの中にクラス以外のコードを追加することもできますが、お勧めしません。このような場合には、クラス定義とその他のコードの間に空行を 2 行挿入しなければなりません。

これらの条件を満たすクラス宣言の例です。

/**
 * これがドキュメントブロックです
 */
class SampleClass
{
    // クラスのすべての内容は、
    // 空白 4 文字の字下げを使用します。
}

他のクラスを継承したりインターフェイスを実装したりしているクラスの宣言は、可能な限りその依存関係も同じ行に含めるようにしなければなりません。

class SampleClass extends FooAbstract implements BarInterface
{
}

このように宣言しようとした結果、もし行の長さが最大文字数を超えてしまう場合は、キーワード "extends" や "implements" の前で改行してインデント量を一段増やします。

class SampleClass 
    extends FooAbstract
    implements BarInterface
{
}

複数のインターフェイスを実装していて宣言が行の最大長を超える場合は、インターフェイスを区切るカンマの後で改行してインターフェイス名の位置がそろうようにインデントします。

class SampleClass 
    implements BarInterface,
               BazInterface
{
}

クラスのメンバ変数

メンバ変数は、以下の Zend Framework 変数命名規約に従わなければなりません。

クラスの内部で使用する変数は、クラスの先頭 (あらゆるメソッド宣言より前) で宣言する必要があります。

var 構文を使ってはいけません。メンバ変数を宣言する際には private、protected あるいは public のいずれかの修飾子を用いてアクセス範囲を指定します。メンバ変数を public 宣言して外部からアクセスさせることもできますが、それよりはアクセサメソッド (set & get) を使用する方式のほうを推奨します。

関数およびメソッド

関数およびメソッドの宣言

関数は、以下の Zend Framework 関数命名規約に従わなければなりません。

クラス内でメソッドを宣言する際には、常に private、protected あるいは public のいずれかの修飾子を用いてアクセス範囲を指定しなければなりません。

クラスと同様、波括弧は関数名の次の行に書かなければなりません。関数名と引数定義用の開始括弧の間にはスペースを入れてはいけません。

グローバルスコープの関数は、できるだけ使わないようにしましょう。

クラス内の関数宣言の例として適切なものを次に示します。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar()
    {
        // 関数のすべての内容は、
        // 空白 4 文字の字下げを使用します。
    }
}

引数リストが行の最大文字数を超える場合は改行できます。関数やメソッドの引数を改行して続ける場合は、その宣言部よりさらに一段インデントしなければなりません。そして、閉じ括弧の前にさらに改行を入れます。宣言部の閉じ括弧と本体の開始波括弧はスペースをひとつはさんで同じ行に記述し、そのインデント量は関数やメソッドの宣言位置と同じになります。そんな場合の例を次に示します。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar($arg1, $arg2, $arg3,
        $arg4, $arg5, $arg6
    ) {
        // 関数のすべての内容は、
        // 空白 4 文字の字下げを使用します。
    }
}

Note: 値の参照渡しは、メソッドの宣言時にパラメータを渡す部分においてのみ可能です。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * これがドキュメントブロックです
     */
    public function bar(&$baz)
    {}
}

実行時の参照渡しは禁止されています。

返り値は括弧で囲んではいけません。これは可読性を下げますし、将来そのメソッドが参照を返すようになった場合にコードが壊れてしまいます。

/**
 * これがドキュメントブロックです
 */
class Foo
{
    /**
     * 間違いです
     */
    public function bar()
    {
        return($this->bar);
    }
 
    /**
     * 正しい形式です
     */
    public function bar()
    {
        return $this->bar;
    }
}

関数およびメソッドの使用法

関数の引数を指定する際は、引数を区切るカンマの後に空白をひとつ入れます。例えば 3 つの引数を受け取る関数をコールする場合の例は、以下のようになります。

threeArguments(1, 2, 3);

コール時に引数を参照渡しすることは禁じます。関数への引数を参照渡しにする方法は、関数宣言についての節を参照ください。

引数として配列を受け取る関数については、関数コールの中に "array" 構文を含め、それを複数行に分けることもできます。そのような場合の記述法は、以下のようになります。

threeArguments(array(1, 2, 3), 2, 3);
 
threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);
 
threeArguments(array(
    1, 2, 3, 'Zend', 'Studio',
    $a, $b, $c,
    56.44, $d, 500
), 2, 3);

制御構造

If/Else/Elseif

if および elseif 系の制御構造では、条件を指定する括弧の前に空白をひとつ入れなければなりません。また、条件指定の括弧を閉じた後にも空白をひとつ入れなければなりません。

括弧で囲まれた条件文の中では、演算子の前後にも空白をいれなければなりません。また、条件の論理的な区切りを明確にするため、条件文の中でも積極的に括弧を使用することを推奨します。

開始波括弧は、条件文と同じ行に記述します。終了波括弧は、常に改行してそれのみで記述します。波括弧の中では、空白 4 文字の字下げを使用します。

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

条件文が行の最大文字数を超え、さらに複数の条件がある場合は、それらを複数行にわけて記述できます。その場合は論理演算子の前で改行し、条件句の最初の文字がそろうように位置を合わせます。条件部の閉じ括弧と本体の開始波括弧はスペースをひとつはさんで同じ行に記述し、そのインデント量は制御構文の開始位置と同じになります。

if (($a == $b) 
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
}

後者の記法の意図は、後から条件句を追加したり削除したりしたときに問題が起こりにくくすることにあります。

"elseif" あるいは "else" を含む "if" 文の場合の決まりは、通常の "if" と同じです。次の例は、"if" 文に "else" や "elseif" が含まれる場合のものです。

if ($a != 2) {
    $a = 2;
} else {
    $a = 7;
}
 
if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
    $a = 4;
} else {
    $a = 7;
}
 
if (($a == $b) 
    && ($b == $c)
    || (Foo::CONST == $d)
) {
    $a = $d;
} elseif (($a != $b)
          || ($b != $c)
) {
    $a = $c;
} else {
    $a = $b;
}

場合によっては、これらの文で波括弧が必要ないこともあります。しかし、このコーディング規約では、このような例外を認めません。 "if"、"elseif" あるいは "else" 文では、常に波括弧を使用しなければなりません。

Switch

"switch" を使用した制御文では、条件を指定する括弧の前に空白をひとつ入れなければなりません。また、条件指定の括弧を閉じた後にも空白をひとつ入れなければなりません。

"switch" 文の中身は、空白 4 文字の字下げを使用します。各 "case" 文の中身は、さらに 4 文字ぶん字下げします。

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

switch 文の default は、決して省略してはいけません。

Note: 各 case の最後に break や return を記述せず、意図的に次の case に処理を流すという書き方をする場合もあるでしょう。これらの場合を単なる記述漏れと区別するために、case 文で break あるいは return を指定しなかった場合は「意図的に break を省略した」というコメントを含めるようにします。

インラインドキュメント

ドキュメントの書式

ドキュメントブロック ("docblocks") は、phpDocumentor と互換性のある書式でなければなりません。 phpDocumentor の書式については、このドキュメントの対象範囲外です。詳細な情報は » http://phpdoc.org/ を参照ください。

Zend Framework のために書かれたコード、あるいはフレームワーク上で操作するコードは、各ファイルの最初に「ファイルレベル」の docblock、そして各クラスの直前に「クラスレベル」の docblock を含めなければなりません。以下に docblock の例を示します。

ファイル

PHP コードを含むすべてのファイルは、最低限これらの phpDocumentor タグを含むドキュメントブロックを、ファイルの先頭に記述しなければなりません。

/**
 * ファイルについての短い説明
 *
 * ファイルについての長い説明 (もしあれば)...
 *
 * LICENSE: ライセンスに関する情報
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    $Id:$
 * @link       http://framework.zend.com/package/PackageName
 * @since      File available since Release 1.5.0
*/

@category アノテーションの値は "Zend" でなければなりません。

@package アノテーションも必須で、ファイルに含まれるクラスのコンポーネント名と同じでなければなりません。一般的には、これは "Zend" プレフィックスとコンポーネント名のふたつの部分からなります。

@subpackage アノテーションはオプションです。指定する場合は、サブコンポーネント名からクラスのプレフィックスを除いたものとしなければなりません。上の例の場合は、ファイルに含まれるクラス名が "Zend_Magic_Wand" であるか、そのクラス名をプレフィックスの一部として使っているのでしょう。

クラス

各クラスには、最低限これらの phpDocumentor タグを含む docblock が必要です。

/**
 * クラスについての短い説明
 *
 * クラスについての長い説明 (もしあれば)...
 *
 * @category   Zend
 * @package    Zend_Magic
 * @subpackage Wand
 * @copyright  Copyright (c) 2005-2014 Zend Technologies USA Inc. (http://www.zend.com)
 * @license    http://framework.zend.com/license   BSD License
 * @version    Release: @package_version@
 * @link       http://framework.zend.com/package/PackageName
 * @since      Class available since Release 1.5.0
 * @deprecated Class deprecated in Release 2.0.0
 */