PHP 編碼風格規範指南

投稿發表於2015-03-14

本指羅列了通用的PHP程式碼格式規則和建議，意在減少不同作者的編碼風格差異帶來的認知障礙。

這裡的風格約定衍生自若干成員專案。指南作者們在多個專案中協作，推動了這些指導條款落地。指南的關鍵在於共享，而不是規則本身。

文中涉及的關鍵詞 “MUST 必須”, “MUST NOT 必須不”, “REQUIRED 必需”, “SHALL 會”, “SHALL NOT 不會”, “SHOULD 應該”, “SHOULD NOT 不應該”, “RECOMMENDED 推薦的”, “MAY 可能”, 和 “OPTIONAL 可選的” 在RFC 2119 中有具體描述.

概覽

程式碼必需遵循 “基礎編碼標準” PSR [PSR-1]。
程式碼縮排必須使用 4 空格，而不是tab。
行長度必須無硬性限制; 軟性限制必須為120字元；應該少於等於80字。
namespace宣告後必須有一個空行，use宣告後也必須有一個空行。
類的｛必須在類名的下一行, ｝必須在body的下一行。
方法的 { 必須在方法簽名的下一行，} 必須在body的下一行。
所有的屬性和方法都要設定可見性； abstract和 final必須在可見性之前宣告；static 必須在可見性後宣告。
結構控制關鍵詞後必須有一個空格；方法和函式必須沒有空格。
結構控制的 { 必須在同一行，} 必須在body的下一行。
結構控制的 ( 後必須有空格，結構控制的 ) 前必須沒有空格。

例子

下面是一個綜合的例子，可以幫助你對規則有一個概略的認識。

<?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()
    {
        // 方法 body
    }
}

基本規則

基本編碼標準

程式碼必須遵循PSR-1的條款。

檔案

所有檔案必須使用 Unix LF (linefeed) 換行。
所有PHP檔案必須使用單個空行結束。
只包含PHP的程式碼必須忽略php結束標記 ? >。

行

行長度必須沒有硬性限制。
長度的軟性限制必須為120字元；自動程式碼風格檢查必須將120字設定為警告，必須不能設定為錯誤。
行不應該超過80字元；超過這個長度的行應該切分為多個不超過80字元的行。
非空行的結束必須沒有尾隨空格。
為增強可讀性，可增加空行來標誌程式碼的關聯性。
每行包含的語句必須不能超過1條。

縮排

程式碼必須使用 4 空格的縮排, 必須不用tab作為縮排。

注意：只使用空格，不用tab，有助於避免diffs,patches, history和annotations的問題。使用空格也有助於對齊。

關鍵詞（保留字）和 true/false/null

PHP保留字必須小寫.
PHP常量 true, false和 null 必須小寫.

Namespace 和 Use 宣告

namespace 宣告之後必須有空行。
所有use 宣告，必須在namespace宣告之後。
每個宣告必須單獨使用一個use。
use宣告區之後必須有一個空行。

例如:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

類, 屬性和方法

這裡的“類”包括 class、interface 和 trait。

繼承和實現

extends 和 implements 關鍵字必須和類名在同一行宣告。

類的 { 必須獨佔一行； } 必須在body的下一行。

<?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 多個介面時，介面列表可以被分到多行，每個子行有一個縮排。如果這麼做，第一個介面必須在implements 下一行，每行只能有一個介面。

<?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
}

屬性

所有屬性都必須宣告 visibility（可見性）。

Var 關鍵字必須不能用於宣告屬性。

每行必須只宣告一個屬性。

不應該通過字首下劃線來標示protected和private的屬性。

例：

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

方法

所有方法都必須宣告可見性。

不應該通過字首下劃線來標示protected和private的方法。

宣告方法時，方法名的後必須沒有空格。 { 必須在同一行， } 必須在body的下一行。 (後必須沒有空格，) 前必須沒有空格。

一個方法宣告的例子如下，注意小括號,逗號,空格和花括號的位置：

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}

方法引數

方法的形參列表中, 每個逗號前必須沒有空格。有預設值的引數必須在引數列表的最後。

<?php
namespace Vendor\Package;

class ClassName
{
    public function foo($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}

引數列表可以切分為多行，每個子行要有一個縮排。如果這麼做，第一個引數必須獨佔一行，每行只能有一個引數。

引數列表切分為多行時，右括號)和左花括號{必須在同一行，之前必須有一個空格。

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // method body
    }
}

abstract, final 和 static

abstract和final宣告必須在可見性之前宣告。
static宣告必須在可見性之後。

<?php
namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

    final public static function bar()
    {
        // method body
    }
}

方法和函式呼叫

寫方法或函式呼叫時，方法／函式名和左括號( 之間，必須沒有空格，右括號 ) 之前必須沒有空格。在引數列表中，逗號間必須沒有逗號，每個逗號後必須有一個空格。

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

控制結構

控制結構通常遵循以下風格:

控制結構關鍵詞後必須有一個空格。
左括號後必須沒有空格。
右括號前必須沒有空格。
又括號和左花括號之間必須有一個空格。
body必須有一層縮排。
右花括號必須在body下一行。
每個控制結構的body必須用花括號括起來。即保證外觀統一，又減少了新增新行時引入的錯誤。

if, elseif, else

if 結構如下所示。注意括號、空格、花括號的位置；同時留意 else 和 elseif 與前一部分的 } 在同一行。

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}

elseif關鍵字不應該被 else if 代替。

switch, case

Switch結構如下所示。注意括號、空格和花括號的位置。 case 語句相對於switch必須有一個縮排， break關鍵字或者其他終結性的關鍵字必須和case body在同一縮排層級。在非空的case body，如果沒有終結性語句，必須加上註釋 // no break。

<?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;
}

while, do while

while結構如下所示。注意括號、空格和花括號的位置。

<?php
while ($expr) {
    // structure body
}

do-while介面如下所示。注意括號、空格和花括號的位置。

<?php
do {
    // structure body;
} while ($expr);

for

for 結構如下所示。注意括號、空格和花括號的位置。

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

foreach

foreach 結構如下所示。注意括號、空格和花括號的位置。

<?php
foreach ($iterable as $key => $value) {
    // foreach body
}

try, catch

try-catch區塊如下所示。注意括號、空格和花括號的位置。

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

Closure 閉包

宣告閉包必須在function關鍵字後留一個空格，在use關鍵字前後各留一個空格。

左花括號必須在同一行，右花括號必須在body的下一行。

引數或變數列表的左括號後和右括號前必須沒有空格。

引數和變數列表的逗號前必須沒有空格，每個逗號後必須有一個空格。

有預設值的引數必須排在最後。

閉包的宣告如下所示。注意括號，逗號，空格和花括號的位置：

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // body
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // body
};

引數列表和變數列表可以拆分到多行，每個子行有一層縮排。這麼做的時候，第一個列表成員必須獨佔一行，每行只能有一個列表成員。

引數或變數列表拆分為多行時，到了列表的末尾，右括號和左花括號必須放在同一行，中間有一個空格。

例子：

<?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
};

注意：當閉包被直接作為函式或方法呼叫的引數時，以上規則同樣適用。

<?php
$foo->bar(
    $arg1,
    function ($arg2) use ($var1) {
        // body
    },
    $arg3
);

結語

本指南刻意忽略了許多風格和實踐。包括但不限於：

宣告全域性變數和全域性常量。
宣告函式。
操作符和賦值。
行間對齊。
註釋和文件區。
類名前字尾。
最佳實踐。

Future recommendations MAY revise and extend this guide to address those or other elements of style and practice.

附錄A 調查

In writing this style guide, the group took a survey of member projects to determine common practices. The survey is retained herein for posterity.

調查資料

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

調查說明

indent_type: The type of indenting. tab = “Use a tab”, 2 or 4 = “number of spaces”

line_length_limit_soft: The “soft” line length limit, in characters. ? = not discernible or no response, no means no limit.

line_length_limit_hard: The “hard” line length limit, in characters. ? = not discernible or no response, no means no limit.

class_names: How classes are named. lower = lowercase only, lower_under = lowercase with underscore separators, studly = StudlyCase.

class_brace_line: Does the opening brace for a class go on the same line as the class keyword, or on the next line after it?

constant_names: How are class constants named? upper = Uppercase with underscore separators.

true_false_null: Are the true, false, and null keywords spelled as all lower case, or all upper case?

method_names: How are methods named? camel = camelCase, lower_under = lowercase with underscore separators.

method_brace_line: Does the opening brace for a method go on the same line as the method name, or on the next line?

control_brace_line: Does the opening brace for a control structure go on the same line, or on the next line?

control_space_after: Is there a space after the control structure keyword?

always_use_control_braces: Do control structures always use braces?

else_elseif_line: When using else or elseif, does it go on the same line as the previous closing brace, or does it go on the next line?

case_break_indent_from_switch: How many times are case and break indented from an opening switch statement?

function_space_after: Do function calls have a space after the function name and before the opening parenthesis?

closing_php_tag_required: In files containing only PHP, is the closing ?> tag required?

line_endings: What type of line ending is used?

static_or_visibility_first: When declaring a method, does static come first, or does the visibility come first?

control_space_parens: In a control structure expression, is there a space after the opening parenthesis and a space before the closing parenthesis? yes = if ( expr),no=if(expr).

blank_line_after_php: Is there a blank line after the opening PHP tag?

class_method_control_brace: A summary of what line the opening braces go on for classes, methods, and control structures.

調查結果

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編碼風格規範
2019-08-02
PHP
JavaScript 風格指南/編碼規範（Airbnb公司版）
2014-11-14
JavaScriptAI
前端程式碼規範 — JavaScript 風格指南
2019-08-22
前端JavaScript
編碼規範（四）之程式碼風格
2017-08-08
Go 語言程式碼風格規範-指南篇
2022-12-26
Go
PHP PSR-2 程式碼風格規範
2015-10-12
PHP
JavaScript編碼風格指南
2019-02-24
JavaScript
JavaScript 編碼風格指南
2018-07-24
JavaScript
PHP編碼規範
2017-11-25
PHP
Go 編碼規範指南
2016-10-09
Go
Go編碼規範指南
2016-10-09
Go
CoffeeScript 編碼風格指南
2014-08-27
Python 編碼風格指南
2016-03-30
Python
[轉]PHP編碼規範
2014-11-30
PHP
Android編碼規範指南
2016-05-18
Android
Python語言規範及風格規範
2016-07-28
Python
PHP – 編碼規範 v1.0
2019-02-16
PHP
求求你規範下你的程式碼風格
2019-01-24
統一規範化程式碼的命名風格
2023-05-10
Go 語言程式碼風格規範-概述篇
2022-12-26
Go
PEP 8 Python編碼風格指南概要
2017-02-25
Python
關於PHP開發編碼規範
2011-03-10
PHP
最全面的 Android 編碼規範指南
2016-04-21
Android
PHP 規範 - Symfony 程式碼規範
2019-11-06
PHP
PEP 8 程式程式碼的編寫風格指南
2019-12-24
編碼規範系列：css規範
2017-09-29
CSS
Vue專案使用eslint + prettier規範程式碼風格
2018-08-19
VueEsLint
如何使用 Pylint 來規範 Python 程式碼風格
2017-02-27
Python
JavaScript 程式碼風格指南
2015-04-26
JavaScript
程式碼規範之前端編寫碼規範
2020-10-20
前端
CSS編碼規範
2020-02-14
CSS
Javascript編碼規範
2020-02-14
JavaScript
html編碼規範
2020-02-14
HTML
Swift 編碼規範
2018-02-09
Swift
SQL 編碼規範
2016-03-16
SQL
Vue 前端程式碼風格指南
2021-12-17
Vue前端
Google JavaScript 程式碼風格指南
2018-10-24
GoJavaScript
統一規範化專案的命名風格
2023-05-09