编码标准 - 一般
这些程式码格式与文件的标准,必须被任何对 Fuel 贡献的人遵循, 任何不符合这些准则的贡献将不被接受。
档案格式
PHP 结束标籤
只包含 PHP 程式码的文件应该总是省略 PHP 结束标籤(?>)。 这可以防止许多难以捉摸的死亡白萤幕。
缩排
所有缩排应该使用真正的 Tab,而非空格。
但对齐缩排后的物件应该使用空格,而非 Tab。
// 缩排 2 个 Tab
$var = 'something'; // 用 Tab 缩排并在值和注解
$variable = 'else'; // 前/后使用空格对齐
行结尾
行结尾应为 Unix-style LF。
档案命名
所有档案名称必须全小写,没有例外。
编码
档案应以 UTF-8 编码储存且不应该使用 BOM。
命名惯例
命名空间
所有核心类别必须在 Fuel\Core 命名空间底下。
namespace Fuel\Core;
类别
类别名称应该使用底线来分隔单词,而且类别名称的每个单词应以大写字母开始。 然而,在自动载入期间,底线会被转换成目录分隔。 驼峰式的使用是被劝阻的,但在某些情况下不能防止, 当放置类别在一个子目录时是没有意义的。
namespace Fuel\Core;
class Session
{
}
namespace Fuel\Core;
class Session_Cookie extends Session_Driver
{
}
这将会是下列档案路径:
core/classes/session.php
core/classes/session/cookie.php
方法
如同类别名称,方法名称应该使用底线来分隔单词,而非驼峰式。 方法名称也应该全部小写,可见性应始终包括在(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++)
常数
常数遵循相同的准则如同变数,例外的是, 常数应该是全部大写的。
MY_CONSTANT
TEMPLATE_PATH
TEXT_DEFAULT
关键字
如 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)
控制结构
结构关键字例如 if、for、foreach、while、switch 应该在一个空格后面加参数/变数列表和值。 大括号应该被放在新的一行,并且 break 在它的情况也应该有相同的标籤。
if ($arg === true)
{
// 做点什幺
}
elseif ($arg === null)
{
// 做些其他事情
}
else
{
// 捕捉所有的做点什幺
}
foreach ($array as $key => $value)
{
// 迴圈
}
for ($i = 0; $i < $max; $i++)
{
// 迴圈
}
while ($i < $max)
{
// 迴圈
}
do
{
// 迴圈
}
while ($i < $max)
switch ($var)
{
case 'value1':
// 做点什幺
break;
default :
// 做点什幺
break;
}
替代的 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';
// 或实际上是这样:
$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 { }
函式/方法/闭包(closure)宣告
函式/方法/闭包(closure)的左大括号必须总是在新的一行开始, 其结构具有相同的缩排。
class Session
{
public static function get_flash($name, $data)
{
$closure = function($a, $b)
{
// 你的闭包(closure)程式码
}
}
}
变数
当初始化变数时,应每一行宣告一个变数。为了提高程式码的可读性, 这些都应该是独立的一行。适当的对齐值和注解。
$var = ''; // 每一个都在自己的行处理
$other_var = ''; // 每一个都在自己的行处理
中括号和括号
左中括号/括号前后应该没有空格,右中括号/括号前不应该有空格。
$array = array(1, 2, 3, 4);
$array['my_index'] = 'something';
for ($i = 0; $i < $max; $i++)
字串引号
多用单引号,少用双引号。
连接
在组合字串连接部分的两边不应该包含空格。
// 是
$string = 'my string '.$var.' the rest of my string';
// 否
$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');