|
|
PSR規(guī)范中文版
- PSR-0自動加載
- PSR-1基本代碼規(guī)范
- PSR-2代碼樣式
- PSR-3日志接口
摘錄翻譯了官方的一句話 本組織旨在通過討論我們代碼項目的共同點以找出一個協(xié)作編程的方法。
在此想到了一篇文章《Google為何要執(zhí)行嚴(yán)格的代碼規(guī)范》中有這么一段話：
復(fù)制代碼 代碼如下:
在谷歌，我可以查看任何的代碼，進(jìn)入所有谷歌的代碼庫，我有權(quán)查看它們。事實上，這種權(quán)限是很少人能擁有的。但是，讓我感到驚訝的卻是，如此多的編碼規(guī)范―縮進(jìn)，命名，文件結(jié)構(gòu)，注釋風(fēng)格―這一切讓我出乎意料的輕松的閱讀任意一段代碼，并輕易的看懂它們。這讓我震驚―因為我以為這些規(guī)范是微不足道的東西。它們不可能有這么大的作用―但它們卻起到了這么大的作用。當(dāng)你發(fā)現(xiàn)只通過看程序的基本語法結(jié)構(gòu)就能讀懂一段代碼，這種時間上的節(jié)省不能不讓人震撼！
各位看官我就不用多說關(guān)于規(guī)范的事情了。
寫在最后
規(guī)范不是義務(wù)的，當(dāng)然你也可以選擇自己的方式，但使用規(guī)范會讓你的合作更輕松。如今各種更現(xiàn)代化應(yīng)用的編寫已不像從前，一個應(yīng)用一般都有非常多的模塊組成，如果不執(zhí)行規(guī)范，只會讓整個項目的理解和溝通更加復(fù)雜。
若使用了規(guī)范，對項目和自己的好處當(dāng)然不言而喻的。
所有已接受的規(guī)范參考：https://github.com/hfcorriez/fig-standards/tree/zh_CN/%E6%8E%A5%E5%8F%97
代碼樣式規(guī)范
本指南的意圖是為了減少不同開發(fā)者在瀏覽代碼時減少認(rèn)知的差異。 為此列舉一組如何格式化php代碼的共用規(guī)則。
各個成員項目的共性組成了本文的樣式規(guī)則。當(dāng)不同的開發(fā)者在不同的項目中合作時，將會在這些不同的項目中使用一個共同的標(biāo)準(zhǔn)。 因此，本指南的好處不在于規(guī)則本身，而在于共用這些規(guī)則。
在 RFC 2119中的特性關(guān)鍵詞"必須"(MUST)，“不可”(MUST NOT)，“必要”(REQUIRED)，“將會”(SHALL)，“不會”(SHALL NOT)，“應(yīng)當(dāng)”(SHOULD)，“不應(yīng)”(SHOULD NOT)，“推薦”(RECOMMENDED)，“可以”(MAY)和“可選”(OPTIONAL)在這文檔中將被用來描述。
1. 大綱
代碼必須遵守 PSR-1。
代碼必須使用4個空格的縮進(jìn)，而不是制表符。
一行代碼長度不應(yīng)硬性限制；軟限制必須為120個字符；也應(yīng)當(dāng)是80個字符或者更少。
在namespace聲明下面必須有一個空行，并且use聲明代碼塊下面也必須有一個空行。
類的左花括號必須放到下一行，右花括號必須放在類主體的下一行。
方法的左花括號必須放在下一行，右花括號必須放在方法主體下面。
所有的屬性和方法必須有可見性(譯者注：Public, Protect, Private)聲明；abstract和final聲明必須在可見性之前；static聲明必須在可見性之后。
控制結(jié)構(gòu)的關(guān)鍵詞必須在后面有一個空格； 方法和函數(shù)不可有。
控制結(jié)構(gòu)的左花括號必須放在同一行，右花括號必須放在控制主體的下一行。
控制結(jié)構(gòu)的左括號后面不可有空格，右括號之前不可有空格。
1.1. 示例
本示例包含上面的一些規(guī)則簡單展示：
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
use FooInterface;
use BarClass as Bar;
use OtherVendor/OtherPackage/BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleFunction($a, $b = null)
{
if ($a === $b) {
bar();
} elseif ($a > $b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
2. 概括
2.1 基礎(chǔ)代碼規(guī)范
代碼必須遵守 PSR-1 的所有規(guī)則。
2.2 文件
所有的php文件必須使用Unix LF(換行)作為行結(jié)束符。
所有php文件必須以一個空行結(jié)束。
純php代碼的文件關(guān)閉標(biāo)簽?>必須省略
2.3. 行
行長度不可有硬限制。
行長度的軟限制必須是120個字符；對于軟限制，自動樣式檢查器必須警告但不可報錯。
行實際長度不應(yīng)超過80個字符；較長的行應(yīng)當(dāng)被拆分成多個不超過80個字符的后續(xù)行。
在非空行后面不可有空格。
空行可以用來改善可讀性和區(qū)分相關(guān)的代碼塊。
一行不應(yīng)多于一個語句。
2.4. 縮進(jìn)
代碼必須使用4個空格的縮進(jìn)，并且不可使用制表符作為縮進(jìn)。
注意：只用空格，不和制表符混合使用，將會對避免代碼差異，補丁，歷史和注解中的一些問題有幫助。使用空格還可以使調(diào)整細(xì)微的縮進(jìn)來改進(jìn)行間對齊變得非常簡單。
2.5. 關(guān)鍵詞和 True/False/Null
php keywords 必須使用小寫。
php常量true, false和null必須使用小寫。
3. Namespace和Use聲明
如果存在，namespace聲明之后必須有一個空行。
如果存在，所有的use聲明必須放在namespace聲明的下面。
一個use關(guān)鍵字必須只用于一個聲明。
在use聲明代碼塊后面必須有一個空行。
示例:
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
use FooClass;
use BarClass as Bar;
use OtherVendor/OtherPackage/BazClass;
// ... additional php code ...
4. 類，屬性和方法
術(shù)語“類”指所有的類，接口和特性（traits）。
4.1. 擴展和繼承
一個類的extends和implements關(guān)鍵詞必須和類名在同一行。
類的左花括號必須放在下面自成一行；右花括號必須放在類主體的后面自成一行。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
use FooClass;
use BarClass as Bar;
use OtherVendor/OtherPackage/BazClass;
class ClassName extends ParentClass implements /ArrayAccess, /Countable
{
// constants, properties, methods
}
implements一個列表可以被拆分為多個有一次縮進(jìn)的后續(xù)行。如果這么做，列表的第一項必須要放在下一行，并且每行必須只有一個接口。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
use FooClass;
use BarClass as Bar;
use OtherVendor/OtherPackage/BazClass;
class ClassName extends ParentClass implements
/ArrayAccess,
/Countable,
/Serializable
{
// constants, properties, methods
}
4.2. 屬性
所有的屬性必須聲明可見性。
var關(guān)鍵詞不可用來聲明屬性。
一個語句不可聲明多個屬性。
屬性名稱不應(yīng)使用單個下劃線作為前綴來表明保護(hù)或私有的可見性。
一個屬性聲明看起來應(yīng)該下面這樣的。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
class ClassName
{
public $foo = null;
}
4.3. 方法
所有的方法必須聲明可見性。
方法名不應(yīng)只使用單個下劃線來表明是保護(hù)或私有的可見性。
方法名在聲明之后不可跟隨一個空格。左花括號必須放在下面自成一行，并且右花括號必須放在方法主體的下面自成一行。左括號后面不可有空格，右括號前面不可有空格。
一個方法定義看來應(yīng)該像下面這樣。 注意括號，逗號，空格和花括號：
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
class ClassName
{
public function fooBarBaz($arg1, &$arg2, $arg3 = [])
{
// method body
}
}
4.4. 方法參數(shù)
在參數(shù)列表中，逗號之前不可有空格，逗號之后必須要有一個空格。
方法中有默認(rèn)值的參數(shù)必須放在參數(shù)列表的最后面。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
class ClassName
{
public function foo($arg1, &$arg2, $arg3 = [])
{
// method body
}
}
參數(shù)列表可以被分為多個有一次縮進(jìn)的多個后續(xù)行。如果這么做，列表的第一項必須放在下一行，并且每行必須只放一個參數(shù)。
當(dāng)參數(shù)列表被分為多行，右括號和左花括號必須夾帶一個空格放在一起自成一行。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint $arg1,
&$arg2,
array $arg3 = []
) {
// method body
}
}
4.5. abstract，final和 static
如果存在，abstract和final聲明必須放在可見性聲明前面。
如果存在，static聲明必須跟著可見性聲明。
復(fù)制代碼 代碼如下:
<?php
namespace Vendor/Package;
abstract class ClassName
{
protected static $foo;
abstract protected function zim();
final public static function bar()
{
// method body
}
}
4.6. 調(diào)用方法和函數(shù)
要調(diào)用一個方法或函數(shù)，在方法或者函數(shù)名和左括號之間不可有空格，左括號之后不可有空格，右括號之前不可有空格。函數(shù)列表中，逗號之前不可有空格，逗號之后必須有一個空格。
<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
參數(shù)列表可以被拆分成多個有一個縮進(jìn)的后續(xù)行。如果這么做，列表中的第一項必須放在下一行，并且每一行必須只有一個參數(shù)。
復(fù)制代碼 代碼如下:
<?php
$foo->bar(
$longArgument,
$longerArgument,
$muchLongerArgument
);
5. 控制結(jié)構(gòu)
對于控制結(jié)構(gòu)的樣式規(guī)則概括如下：
控制結(jié)構(gòu)關(guān)鍵詞之后必須有一個空格
左括號之后不可有空格
右括號之前不可有空格
在右括號和左花括號之間必須有一個空格
代碼主體必須有一次縮進(jìn)
右花括號必須主體的下一行
每個結(jié)構(gòu)的主體必須被括在花括號里。這結(jié)構(gòu)看上去更標(biāo)準(zhǔn)化，并且當(dāng)加新行的時候可以減少引入錯誤的可能性。
5.1. if，elseif，else
一個if結(jié)構(gòu)看起來應(yīng)該像下面這樣。注意括號，空格，花括號的位置；并且else和elseif和前一個主體的右花括號在同一行。
復(fù)制代碼 代碼如下:
<?php
if ($expr1) {
// if body
} elseif ($expr2) {
// elseif body
} else {
// else body;
}
關(guān)鍵詞elseif應(yīng)該替代else if使用以保持所有的控制關(guān)鍵詞像一個單詞。
5.2. switch，case
一個switch結(jié)構(gòu)看起來應(yīng)該像下面這樣。注意括號，空格和花括號。case語句必須從switch處縮進(jìn)，并且break關(guān)鍵字（或其他中止關(guān)鍵字）必須和case主體縮進(jìn)在同級。如果一個非空的case主體往下落空則必須有一個類似// no break的注釋。
復(fù)制代碼 代碼如下:
<?php
switch ($expr) {
case 0:
echo 'First case, with a break';
break;
case 1:
echo 'Second case, which falls through';
// no break
case 2:
case 3:
case 4:
echo 'Third case, return instead of break';
return;
default:
echo 'Default case';
break;
}
5.3. while，do while
一個while語句看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
while ($expr) {
// structure body
}
同樣的，一個do while語句看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
do {
// structure body;
} while ($expr);
5.4. for
一個for語句看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
for ($i = 0; $i < 10; $i++) {
// for body
}
5.5. foreach
一個foreach語句看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
foreach ($iterable as $key => $value) {
// foreach body
}
5.6. try, catch
一個try catch語句看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
try {
// try body
} catch (FirstExceptionType $e) {
// catch body
} catch (OtherExceptionType $e) {
// catch body
}
6. 閉包
閉包在聲明時function關(guān)鍵詞之后必須有一個空格，并且use之前也需要一個空格。
左花括號必須在同一行，右花括號必須在主體的下一行。
參數(shù)列表和變量列表的左括號之后不可有空格，其右括號之前也不可有空格。
在參數(shù)列表和變量列表中，逗號之前不可有空格，逗號之后必須有空格。
閉包帶默認(rèn)值的參數(shù)必須放在參數(shù)列表后面。
一個閉包聲明看起來應(yīng)該像下面這樣。注意括號，空格和花括號的位置。
復(fù)制代碼 代碼如下:
<?php
$closureWithArgs = function ($arg1, $arg2) {
// body
};
$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
// body
};
參數(shù)和變量列表可以被分成多個帶一次縮進(jìn)的后續(xù)行。如果這么做，列表的第一項必須放在下一行，并且一行必須只放一個參數(shù)或變量。
當(dāng)最終列表（不管是參數(shù)還是變量）被分成多行，右括號和左花括號必須夾帶一個空格放在一起自成一行。
下面是一個參數(shù)和變量列表被分割成多行的示例。
復(fù)制代碼 代碼如下:
<?php
$longArgs_noVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) {
// body
};
$noArgs_longVars = function () use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// body
};
$longArgs_longVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// body
};
$longArgs_shortVars = function (
$longArgument,
$longerArgument,
$muchLongerArgument
) use ($var1) {
// body
};
$shortArgs_longVars = function ($arg) use (
$longVar1,
$longerVar2,
$muchLongerVar3
) {
// body
};
注意如果在函數(shù)或者方法中把閉包作為一個參數(shù)調(diào)用，如上格式規(guī)則同樣適用。
復(fù)制代碼 代碼如下:
<?php
$foo->bar(
$arg1,
function ($arg2) use ($var1) {
// body
},
$arg3
);
7. 結(jié)論
在該指南中有很多風(fēng)格的元素和做法有意被忽略掉。這些包括但不局限于：
全局變量和全局常量的聲明
方法聲明
操作符和賦值
行間對齊
注釋和文檔塊
類名給你前綴和后綴
最佳實踐
以后的建議可以修改和擴展該指南以滿足這些或其他風(fēng)格的元素和實踐。
附錄A 調(diào)查
為了寫這個風(fēng)格指南，我們采用了調(diào)查個項目以確定共同的做法。這個調(diào)查在這里供他人查看。
A.1. 調(diào)查數(shù)據(jù)
url,http://www.horde.org/apps/horde/docs/CODING_STANDARDS,http://pear.php.NET/manual/en/standards.php,http://solarphp.com/manual/appendix-standards.style,http://framework.zend.com/manual/en/coding-standard.html,http://symfony.com/doc/2.0/contributing/code/standards.html,http://www.ppi.io/docs/coding-standards.html,https://github.com/ezsystems/ezp-next/wiki/codingstandards,http://book.cakephp.org/2.0/en/contributing/cakephp-coding-conventions.html,https://github.com/UnionOfRAD/lithium/wiki/Spec%3A-Coding,http://drupal.org/coding-standards,http://code.google.com/p/sabredav/,http://area51.phpbb.com/docs/31x/coding-guidelines.html,https://docs.google.com/a/zikula.org/document/edit?authkey=CPCU0Us&hgd=1&id=1fcqb93Sn-hR9c0mkN6m_tyWnmEvoswKBtSc0tKkZmJA,http://www.chisimba.com,n/a,https://github.com/Respect/project-info/blob/master/coding-standards-sample.php,n/a,Object Calisthenics for php,http://doc.NETte.org/en/coding-standard,http://flow3.typo3.org,https://github.com/propelorm/Propel2/wiki/Coding-Standards,http://developer.joomla.org/coding-standards.html
voting,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,no,no,no,?,yes,no,yes
indent_type,4,4,4,4,4,tab,4,tab,tab,2,4,tab,4,4,4,4,4,4,tab,tab,4,tab
line_length_limit_soft,75,75,75,75,no,85,120,120,80,80,80,no,100,80,80,?,?,120,80,120,no,150
line_length_limit_hard,85,85,85,85,no,no,no,no,100,?,no,no,no,100,100,?,120,120,no,no,no,no
class_names,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,studly,lower_under,studly,lower,studly,studly,studly,studly,?,studly,studly,studly
class_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,next,next,next,next,next,next,same,next,next
constant_names,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper,upper
true_false_null,lower,lower,lower,lower,lower,lower,lower,lower,lower,upper,lower,lower,lower,upper,lower,lower,lower,lower,lower,upper,lower,lower
method_names,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel,lower_under,camel,camel,camel,camel,camel,camel,camel,camel,camel,camel
method_brace_line,next,next,next,next,next,same,next,same,same,same,same,next,next,same,next,next,next,next,next,same,next,next
control_brace_line,same,same,same,same,same,same,next,same,same,same,same,next,same,same,next,same,same,same,same,same,same,next
control_space_after,yes,yes,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes,yes
always_use_control_braces,yes,yes,yes,yes,yes,yes,no,yes,yes,yes,no,yes,yes,yes,yes,no,yes,yes,yes,yes,yes,yes
else_elseif_line,same,same,same,same,same,same,next,same,same,next,same,next,same,next,next,same,same,same,same,same,same,next
case_break_indent_from_switch,0/1,0/1,0/1,1/2,1/2,1/2,1/2,1/1,1/1,1/2,1/2,1/1,1/2,1/2,1/2,1/2,1/2,1/2,0/1,1/1,1/2,1/2
function_space_after,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no,no
closing_php_tag_required,no,no,no,no,no,no,no,no,yes,no,no,no,no,yes,no,no,no,no,no,yes,no,no
line_endings,LF,LF,LF,LF,LF,LF,LF,LF,?,LF,?,LF,LF,LF,LF,?,,LF,?,LF,LF,LF
static_or_visibility_first,static,?,static,either,either,either,visibility,visibility,visibility,either,static,either,?,visibility,?,?,either,either,visibility,visibility,static,?
control_space_parens,no,no,no,no,no,no,yes,no,no,no,no,no,no,yes,?,no,no,no,no,no,no,no
blank_line_after_php,no,no,no,no,yes,no,no,no,no,yes,yes,no,no,yes,?,yes,yes,no,yes,no,yes,no
class_method_control_brace,next/next/same,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/next,same/same/same,same/same/same,same/same/same,same/same/same,next/next/next,next/next/same,next/same/same,next/next/next,next/next/same,next/next/same,next/next/same,next/next/same,same/same/same,next/next/same,next/next/next
A.2. 調(diào)查說明
indent_type: 縮進(jìn)類型。 tab = "使用制表符"，2 or 4 = "空格數(shù)量"
line_length_limit_soft: 行長度的“軟”限制，用字符。 ? = 不表示或者數(shù)字 no 意為不限制.
line_length_limit_hard: 行長度的"硬"限制，用字符。 ? = 不表示或者數(shù)字, no 意為不限制.
class_names: 類名如何命名 lower = 只是小寫, lower_under = 小寫加下劃線, studly = 駱駝型.
class_brace_line: 類的左花括號是放在同(same)一行還是在下(next)一行？
constant_names: 類常量如何命名？upper = 大寫加下劃線分隔符。
true_false_null: 全校寫或者全大寫？
method_names: 方法名如何命名？camel = 駝峰式, lower_under = 小寫加下劃線分隔符。
method_brace_line: 方法的左花括號在同(same)一行還是在下(next)一行？
control_brace_line: 控制結(jié)構(gòu)的左花括號在同(same)一行還是在下(next)一行？
control_space_after: 控制結(jié)構(gòu)關(guān)鍵詞后是否有空格？
always_use_control_braces: 控制結(jié)構(gòu)總是使用花括號？
else_elseif_line: 當(dāng)使用else和elseif，是否放在同(same)一行還是在下(next)一行？
case_break_indent_from_switch: case和break分別從swith語句處縮進(jìn)多少次？
function_space_after: 函數(shù)調(diào)用的函數(shù)名和左括號是否有空格？
closing_php_tag_required: 如過是純php文件，關(guān)閉標(biāo)簽?>是否需要？
line_endings: 使用何種的行結(jié)束符？
static_or_visibility_first: 在定義方法的時候static和可見性誰在前面？
control_space_parens: 在控制結(jié)構(gòu)表達(dá)式中，左括號后面和右括號前面是否要有一個空格？yes = if ( $expr ), no =if ($expr).
blank_line_after_php: php的開始標(biāo)簽后面是否需要一個空行？
class_method_control_brace: 左花括號在類，方法和控制結(jié)構(gòu)中的位置。
A.3. 調(diào)查結(jié)果
indent_type:
tab: 7
2: 1
4: 14
line_length_limit_soft:
?: 2
no: 3
75: 4
80: 6
85: 1
100: 1
120: 4
150: 1
line_length_limit_hard:
?: 2
no: 11
85: 4
100: 3
120: 2
class_names:
?: 1
lower: 1
lower_under: 1
studly: 19
class_brace_line:
next: 16
same: 6
constant_names:
upper: 22
true_false_null:
lower: 19
upper: 3
method_names:
camel: 21
lower_under: 1
method_brace_line:
next: 15
same: 7
control_brace_line:
next: 4
same: 18
control_space_after:
no: 2
yes: 20
always_use_control_braces:
no: 3
yes: 19
else_elseif_line:
next: 6
same: 16
case_break_indent_from_switch:
0/1: 4
1/1: 4
1/2: 14
function_space_after:
no: 22
closing_php_tag_required:
no: 19
yes: 3
line_endings:
?: 5
LF: 17
static_or_visibility_first:
?: 5
either: 7
static: 4
visibility: 6
control_space_parens:
?: 1
no: 19
yes: 2
blank_line_after_php:
?: 1
no: 13
yes: 8
class_method_control_brace:
next/next/next: 4
next/next/same: 11
next/same/same: 1
same/same/same: 6
php技術(shù)：PHP的PSR規(guī)范中文版，轉(zhuǎn)載需保留來源！
鄭重聲明：本文版權(quán)歸原作者所有，轉(zhuǎn)載文章僅為傳播更多信息之目的，如作者信息標(biāo)記有誤，請第一時間聯(lián)系我們修改或刪除，多謝。
