The Cookbook へようこそ

テストがない新機能は追加されません。リポジトリにコミットする前にテストが通っているべきです。

インデントには１つのタブを使用します。

インデントは次のようになります:

<?php
// ベースレベル
    // レベル 1
        // レベル 2
    // レベル 1
// ベースレベル
?>

1. <?php
2. // ベースレベル
3. // レベル 1
4. // レベル 2
5. // レベル 1
6. // ベースレベル
7. ?>

あるいは:

$booleanVariable = true;
$stringVariable = "moose";
if ($booleanVariable) {
    echo "Boolean value is true";
    if ($stringVariable == "moose") {
        echo "We have encountered a moose";
    }
}

1. $booleanVariable = true;
2. $stringVariable = "moose";
3. if ($booleanVariable) {
4. echo "Boolean value is true";
5. if ($stringVariable == "moose") {
6. echo "We have encountered a moose";
7. }
8. }

このセクションには保留されている変更があります. More information about translations

Control structures are for example "if", "for", "foreach", "while", "switch" etc. Below, an example with "if":

<?php 
if ((expr_1) || (expr_2)) { 
    // action_1;
} elseif (!(expr_3) && (expr_4)) {
    // action_2; 
} else {
    // default_action; 
} 
?>

1. <?php
2. if ((expr_1) || (expr_2)) {
3. // action_1;
4. } elseif (!(expr_3) && (expr_4)) {
5. // action_2;
6. } else {
7. // default_action;
8. }
9. ?>

• In the control structures there should be 1 (one) space before the first parenthesis and 1 (one) space between the last parenthesis and the opening bracket.
• Always use curly brackets in control structures, even if they are not needed. They increase the readability of the code, and they give you fewer logical errors.
• Opening curly brackets should be placed on the same line as the control structure. Closing curly brackets should be placed on new lines, and they should have same indentation level as the control structure. The statement included in curly brackets should begin on a new line, and code contained within it should gain a new level of indentation.

<?php 
// wrong - no brackets, badly placed statement
if (expr) statement; 

// wrong - no brackets
if (expr) 
    statement; 

// good
if (expr) {
    statement;
}
?>

1. <?php
2. // wrong - no brackets, badly placed statement
3. if (expr) statement;
4. // wrong - no brackets
5. if (expr)
6. statement;
7. // good
8. if (expr) {
9. statement;
10. }
11. ?>

このセクションには保留されている変更があります. More information about translations

Ternary operators are permissible when the entire ternary operation fits on one line. Longer ternaries should be split into if else statements. Ternary operators should not ever be nested. Optionally parentheses can be used around the condition check of the ternary for clarity.

//Good, simple and readable
$variable = isset($options['variable']) ? $options['variable'] : true;

//Nested ternaries are bad
$variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

1. //Good, simple and readable
2. $variable = isset($options['variable']) ? $options['variable'] : true;
3. //Nested ternaries are bad
4. $variable = isset($options['variable']) ? isset($options['othervar']) ? true : false : false;

関数は、関数名と開始ブラケットの間に空白なしでコールされます。各関数コールの各パラメータの間には１つの空白があります。

<?php 
$var = foo($bar, $bar2, $bar3); 
?>

1. <?php
2. $var = foo($bar, $bar2, $bar3);
3. ?>

上記でみたように、イコールサイン (=) の両脇に１つの空白があります。コードの可読性を高めるために、イコールサインの前に空白（あるいはタブ）を追加することができますが、以下のような複数の関数コールの場合にのみ使用します:

<?php 
$varShort     = foo($bar1);
$variableLong = foo($bar1);
?>

1. <?php
2. $varShort = foo($bar1);
3. $variableLong = foo($bar1);
4. ?>

関数定義の例:

<?php 
function someFunction($arg1, $arg2 = '') {
    if (expr) {
        statement;
    }
    return $var;
}
?>

1. <?php
2. function someFunction($arg1, $arg2 = '') {
3. if (expr) {
4. statement;
5. }
6. return $var;
7. }
8. ?>

デフォルト値をもつパラメータは、関数定義の最後に置きます。関数が少なくとも true あるいは false のような何かを返すようにしてみましょう。そうすると関数コールが成功したかどうかを決定できます。

<?php 
function connection(&$dsn, $persistent = false) {
    if (is_array($dns)) {
        $dns_info = &$dns;
    } else {
        $dns_info = BD::parseDNS(dns);
    }

    if (!($dns_info) || !($dns_info['phpType'])) {
        return $this->addError();
    }
    return true;
}
?>

1. <?php
2. function connection(&$dsn, $persistent = false) {
3. if (is_array($dns)) {
4. $dns_info = &$dns;
5. } else {
6. $dns_info = BD::parseDNS(dns);
7. }
8. if (!($dns_info) || !($dns_info['phpType'])) {
9. return $this->addError();
10. }
11. return true;
12. }
13. ?>

イコールサインの両脇には空白をいれます。

コメントはすべて英語で書くべきです。明確にコードのコメントブロックを記述します。

コメントには次のような phpDocumentor タグを記述できます:

• @access
• @author
• @copyright
• @deprecated
• @example
• @ignore
• @internal
• @link
• @see
• @since
• @tutorial
• @version
• inline {@internal}}
• inline {@inheritdoc}}
• inline {@link}}

PhpDoc タグは Java の JavaDoc タグに非常に似ています。DocBlock 行の最初のものである場合にのみタグが処理されます。たとえば:

<?php
/**
 * Tag example.
 * @author this tag is parsed, but this @version is ignored
 * @version 1.0 this tag is also parsed
 */
?>

1. <?php
2. /**
3. * Tag example.
4. * @author this tag is parsed, but this @version is ignored
5. * @version 1.0 this tag is also parsed
6. */
7. ?>

３つのインラインタグ（{@internal}}, {@inheritdoc}},{@link}}）があります。

<?php
/**
 * Example of inline phpDoc tags.
 *
 * This function works hard with {@link foo()} to rule the world.
 */
function bar() {
}

function foo() {
}
?>

1. <?php
2. /**
3. * Example of inline phpDoc tags.
4. *
5. * This function works hard with {@link foo()} to rule the world.
6. */
7. function bar() {
8. }
9. function foo() {
10. }
11. ?>

クラスやライブラリのファイルを include する際に、require_once 関数だけを常に使用します。

ショートタグ (<? ?>) ではなく、常に長いタグ (<?php ?>) を使用します。

すべての関数はキャメルケースで記述します

<?php
function longFunctionName() {
}
?>

1. <?php
2. function longFunctionName() {
3. }
4. ?>

クラス名はキャメルケースで記述します。たとえば:

<?php
class ExampleClass {
}
?>

1. <?php
2. class ExampleClass {
3. }
4. ?>

変数名はできるだけ内容を表すようにすべきですが、できるだけ短くすべきです。通常の変数は小文字で始め、複数の単語の場合はキャメルケースで記述すべきです。オブジェクトを含む変数は大文字で始め、その変数がそのオブジェクトのクラスに関連することを示すべきです。たとえば:

<?php
$user = 'John';
$users = array('John', 'Hans', 'Arne');

$Dispatcher = new Dispatcher();
?>

1. <?php
2. $user = 'John';
3. $users = array('John', 'Hans', 'Arne');
4. $Dispatcher = new Dispatcher();
5. ?>

メソッドや変数に PHP5 の private や protected キーワードを使用することはできないので、次のようなルールに従っています:

• protected メソッドや変数は、単一のアンダースコア ("_") で始めます。たとえば:

  <?php
  class A {
      var _iAmAProtectedVariable;
  
      function _iAmAProtectedMethod() {
          /*...*/
      }
  }
  ?>
  

  1. <?php
  2. class A {
  3. var _iAmAProtectedVariable;
  4. function _iAmAProtectedMethod() {
  5. /*...*/
  6. }
  7. }
  8. ?>
• private メソッドや変数は、２つのアンダースコア ("_") で始めます。たとえば:

<?php
class A {
    var __iAmAPrivateVariable;

    function __iAmAPrivateMethod() {
        /*...*/
    }
}
?>

1. <?php
2. class A {
3. var __iAmAPrivateVariable;
4. function __iAmAPrivateMethod() {
5. /*...*/
6. }
7. }
8. ?>

URL やメールアドレスの例にはすべて、"example.com", "example.org", "example.net" を使用します。たとえば:

• Email: someone@example.com
• WWW: http://www.example.com
• FTP: ftp://ftp.example.com

ファイル名は小文字で生成すべきです。ファイル名が複数の単語からなる場合は、アンダースコアで区切ります。たとえば:

long_file_name.php

DocBlock で使用する変数の型:

mixed と型を指定した場合、不明かどうかあるいは何が有効であるかを示すべきであることを覚えておいてください。

定数は大文字で定義すべきです:

<?php
define('CONSTANT', 1);
?>

1. <?php
2. define('CONSTANT', 1);
3. ?>

定数名が複数の単語からなる場合、アンダースコアで区切ります。たとえば:

<?php
define('LONG_NAMED_CONSTANT', 2);
?>

1. <?php
2. define('LONG_NAMED_CONSTANT', 2);
3. ?>