Documentation

コーディング標準

コード書式や文書の標準は Fuel に貢献するひとはすべて従う必要があります。 このガイドラインを読んでいない貢献はすべて受け入れられません。

ファイル書式

PHP タグの閉じ方

PHP のコードだけしか含まないファイルは常に PHP の閉じタグ (?>) を省略します。 これは見つけにくい「死の白い画面」を避けるためです。

インデント

すべてのインデントはスペースではなくタブを使用すべきです。
しかし、インデント後の整形はタブではなくスペースを使用します。

		// 2 つのタブでインデント
		$var       = 'something';  // インデントはタブを使用、値とコメントの
		$variable  = 'else';       // 縦並びの整形はスペースを使用

行の末尾

行の末尾は Unix 形式の LF にします。

ファイル名

すべてのファイル名は、すべて小文字にしなければなりません。例外はありません。

エンコーディング

ファイルは UTF-8 で保存し、BOM は使用しません。

命名規則

名前空間

コアクラスはすべて Fuel\Core というネームスペースにします。

namespace Fuel\Core;

クラス

Class names should use underscores to separate words, and each word in the class name should begin with a capital letter. The use of camelcase is discouraged but cannot be prevented in some cases when putting the class in a subdirectory makes absolutely no sense. If possible, this should be avoided.

namespace Fuel\Core;

class Session
{

}

namespace Fuel\Core;

class Session_Cookie extends Session_Driver
{

}

Every class should be defined into its own file. Any underscores in the class name will be converted to a directory separator during autoloading, so this must be reflected in the name and location of the class file. For the classes above, their names wouldresult in the following file path:

COREPATH/classes/session.php
COREPATH/classes/session/cookie.php

メソッド

クラス名同様、メソッド名は単語の境界でキャメルケースではなくアンダースコアを使用します。 メソッド名はすべて小文字です。スコープ (public, protected, private) は常に含めます。
名前の１文字目にアンダースコアを使用できます。これはメソッドが protected/private であることを明記したり、 必要に迫られて public にしたメソッドを protected/private とみなして欲しいことを表明するためです。

class Session
{

	public static function get_flash($name, $data)
	{
		// ここにコードを記述する
	}

}

class View
{

	// ビューに関するグローバルデータの配列
	protected static $_global_data = array();

	protected static function capture($view_filename, array $view_data)
	{
		// ここにコードを記述する
	}

}

変数

変数名は簡潔にし、小文字とアンダースコアだけを含むようにします。 ループイテレータは短く、なるべく単一文字にするようにします。

$first_name
$buffer
for ($i = 0; $i < $max; $i++)

Except for the PHP global system constant that doesn't have a Fuel wrapper (for example $_ENV), global variables should never been used. If you have a legitemate use for such a constant, please inform the team so a wrapper can be created to allow consistent and immutable access to that constant.
Use of the keyword global to create or import global variables into a local variable scope is explicitly forbidden!

定数

定数は全て大文字にすること以外は変数と同じガイドラインに 従います。

MY_CONSTANT
TEMPLATE_PATH
TEXT_DEFAULT

The use of global constants is discouraged and should be kept to an absolute minimum. If you need one, be prepend to defend your use case before the Fuel team will accept your proposal!. Where possible, use class constants to make their scope, usage and meaning clear.

キーワード

true, false, null, as などのようなキーワードは、すべて小文字にします。大文字は定数のために予約されているためです。 同じことが array, integer, string のようなプリミティブ型にも当てはまります。

$var = true;
$var = false;
$var = null;
foreach ($array as $key => $value)
public function my_function(array $array)
function my_function($arg = null)

Type casting

The use of type casting is discouraged. PHP is a weakly typed language with at times very vague type conversion rules. They may cause unintended behaviour, which may introduce very hard to find bugs. Instead, do a content check before you convert to make sure the variable contains an expected value.

Control Structures

if, for, foreach, while, switch のような制御に関するキーワードのあとにはスペースを入れ、 パラメータや引数のリストまたは値を続けます。ブレースは新しい行にします。 break は case と同じインデントにします。

if ($arg === true)
{
	//ここで何かする
}
elseif ($arg === null)
{
	//ここで何か別のことをする
}
else
{
	//ここで何かするキャッチオール
}

foreach ($array as $key => $value)
{
	//ここでループする
}

for ($i = 0; $i < $max; $i++)
{
	//loop here
}

while ($i < $max)
{
	//ここでループする
}

do
{
	//ここでループする
}
while ($i < $max)

switch ($var)
{
	case 'value1':
		//ここで何かする
	break;
	default :
		//ここで何かする
	break;
}

もう 1 つの if 文

ある場合において、完全な if 文が単純な条件や関数呼び出しにしてはコードが多すぎることがあります。 このような場合、 より短い論理演算子構文を使用することで、PHP の実行ロジックを使用できます。 and を使用すると、最初の部分が true である場合のみ２番目の部分が実行されます。 or を使用すると、最初の部分が false である場合のみ２番目の部分が実行されます。
if や else が必要な場合は使用しないでください。単一の条件文のような場合にのみ使用してください。

// if (isset($var)) { Config::set('var', $var); } の代替
isset($var) and Config::set('var', $var);

// if ( ! isset($var)) { $var = Config::get('var'); } の代替
isset($var) or $var = Config::get('var');

// これをしてはいけません
Uri::segment(3) and $var = Uri::segment(3);
Uri::segment(3) or $var = 'default';

// こちらのほうがいいです:
if (Uri::segment(3))
{
	$var = Uri::segment(3);
}
else
{
	$var = 'default';
}

// またはこうします:
$var = Uri::segment(3) ? Uri::segment(3) : 'default';

// Or even better, this:
$var = Uri::segment(3) ?: 'default';

比較と論理演算子

関数/メソッドの返値や変数を比較するには型に注意します。たとえば、関数が false を返すときに、 この返値を === や !== のような型に注意した演算子を使用して比較します。 さらに and や or を使用することが、&& や || よりも読みやすさの観点から好ましいです。 場合によってはこれを避けることができないこともありますので、必要に応じて && や || を使用します。! を使用する場合は、両端にスペースを置きます。

if ($var == false and $other_var != 'some_value')
if ($var === false or my_function() !== false)
if ( ! $var)

クラス/インターフェースの定義

クラス/インターフェースの定義では次の行に開始ブレースを置きます:

class Session
{

}

クラスが空の場合、ブレースは定義と同じ行に置きます:

class Empty_Class { }

関数/メソッド/クロージャの宣言

関数/メソッド/クロージャの開始ブレースは常に次の行から始め、 構文と同じインデントにします。

class Session
{

	public static function get_flash($name, $data)
	{
		$closure = function($a, $b)
		{
			// クロージャのコードをここに
		}
	}

}

変数

変数を初期化する際に、1 行に 1 つの変数を宣言します。コードの可読性をあげるために、各変数は別の行にします。 値とコメントは適切に整形します。

$var        = ''; // 1 行に 1 つ
$other_var  = ''; //  1 行に 1 つ

ブラケットと丸カッコ

開始ブラケット/丸カッコの前後にはスペースをいれません。閉じブラケット/丸カッコの前にスペースをいれません。

$array = array(1, 2, 3, 4);
$array['my_index'] = 'something';
for ($i = 0; $i < $max; $i++)

文字列のクォート

Single quotes are preferred over double quotes. It prevents unwanted or unintended expansion of variables and control characters.

連結

文字列の連結は結合するパーツ間にスペースをいれません。

//yes
$string = 'my string '.$var.' the rest of my string';

//no
$string = 'my string ' . $var . ' the rest of my string';

演算子

$var = 'something';
if ($var == 'something') //論理演算子の前後にスペースをいれる
$var = $some_var + $other_var; //算術演算子の前後にスペースをいれる
$var++; // 加算演算子の前にスペースをいれない
++$var; //加算演算子の後にスペースをいれない

配列のドット表記

厳密に言えばコーディング標準ではありませんが、このフレームワークのクラス内やこのドキュメントで多用されていますし、 PHPでの表記として一般的でないため、このフレームワークに不慣れな人を混乱させるかも知れません。

// "always_load.packages = array()" は次のコードの省略表現です:
array("always_load" => array("packages" => array(...) ) );

この表記は Arr クラスで使われますが、Lang クラス、Config クラスそして Session クラスでも、多次元配列から個々の要素に素早くアクセスするために使われます。

// このような構造の配列がある場合
$array = array(
    "always_load" => array(
        "packages" => array(
            "orm",
            "package" => "/my/special/package.php",
        )
     )
);

// 次のコードは "/my/special/package.php" を返します:
$path = Arr::get($array, 'always_load.packages.package');