PHP规范.doc

PHP规范一 基本代码规范这一部分标准包括，哪些应该被认为是标准的编码元素，以确保共享的PHP代码间具有较高程度的技术互通性。关键词“必须”(“MUST”)、“一定不可/一定不能”(“MUST NOT”)、“需要”(“REQUIRED”)、 “将会”(“SHALL”)、“不会”(“SHALL NOT”)、“应该”(“SHOULD”)、“不该”(“SHOULD NOT”)、 “推荐”(“RECOMMENDED”)、“可以”(“MAY”)和”可选“(“OPTIONAL”)的详细描述可参见 RFC 21191.概览PHP文件必须只使用 ?php 和 ? 这两种标签。PHP文件必须以不带BOM的UTF-8编码。PHP文件中应该只定义类、函数、常量等声明，或其他会产生从属效应 的操作（如：生成文件输出以及修改.ini配置文件等），但是不应该同时做着两件事情。命名空间以及类必须符合 PSR 的自动加载规范：PSR-0 或 PSR-4 中的一个；类的命名必须遵循以大写开头的驼峰命名规则（StudlyCaps）。类中的常量所有字母都必须大写，单词间用下划线分隔。方法名必须符合以小写开头的驼峰命名法（camelCase）。2.文件2.1PHP标签PHP代码必须使用长标签或短标签输出。一定不能使用其他标签。2.2字符编码PHP代码必须只可使用不带BOM的UFT-8编码2.3从属效应（副作用）一个文件应该要不就只定义声明（类，函数，常亮等），要不就只有产生从属效应的逻辑操作，但不应该两者都有。短语“副作用”（side effects）意味着执行的逻辑仅仅从包含文件，而没有直接关系到声明类，函数，常量等。“从属效应”包含却不仅限于：生成输出、直接的 require 或 include、连接外部服务、修改 ini 配置、抛出错误或异常、修改全局或静态变量、读或写文件等。下面是一个同时拥有声明和从属效应的例子，应该避免：?php/ side effect: change ini settingsini_set(error_reporting, E_ALL);/ side effect: loads a fileinclude file.php;/ side effect: generates outputecho n;/ declarationfunction foo() / function body下面是一个只包含声明而没有包含side effects的例子，应该被模仿：?php/ declarationfunction foo() / function body/ conditional declaration is *not* a side effectif (! function_exists(bar) function bar() / function body 3.命名空间和类命名空间Namespace和类class必须 遵循”autoloading” PSR标准: PSR-0, PSR-4.这就意味着每一个类必须独立为一个属于他自己的文件，且命名空间至少有一个层次：顶级的组织名称（vendor name）。类的命名必须遵循以大写开头的驼峰命名规则（StudlyCaps）。PHP5.3及以后的必须用正式的命名空间。例如：?php/ PHP 5.3 and later:namespace VendorModel;class Foo5.2.x及之前的版本应该使用以Vendor_为类名前缀的 伪命名空间的写法?php/ PHP 5.2.x and earlier:class Vendor_Model_Foo4.类的常量、属性和方法此处的“类”指代所有的类、接口以及可复用代码块（traits）译者注：trait在PHP5.4中泛指所有能被重复使用的函式。 /manual/en/language.oop5.traits.php4.1常量类的常量必须所有字母全部大写，用下划线分隔。例如：?phpnamespace VendorModel;class Foo const VERSION = 1.0; const DATE_APPROVED = 2012-06-01;4.2属性类的属性命名可以遵循 大写开头的驼峰式 ($StudlyCaps)、小写开头的驼峰式 ($camelCase) 又或者是 下划线分隔式 ($under_score)，本规范不做强制要求，但无论遵循哪种命名方式，都应该在一定的范围内保持一致。这个范围可以是整个团队、整个包、整个类或整个方法。4.3方法方法名必须符合以小写开头的驼峰命名法（camelCase()）。二 代码风格规范本规通过制定一系列规范化PHP代码的规则，以减少在浏览不同作者的代码时，因代码风格的不同而造成不便。这个风格规范是从各种各样的项目的共性中延伸出来的。当多名程序员在多个项目中合作时，它有助于有一套准则，在所有的项目中使用。因此，本指南的好处不是在规则本身，而是在这些规则的共享。关键词 “必须”(“MUST”)、“一定不可/一定不能”(“MUST NOT”)、“需要”(“REQUIRED”)、 “将会”(“SHALL”)、“不会”(“SHALL NOT”)、“应该”(“SHOULD”)、“不该”(“SHOULD NOT”)、 “推荐”(“RECOMMENDED”)、“可以”(“MAY”)和”可选“(“OPTIONAL”)的详细描述可参见 RFC 21191.概览代码必须遵循PSR-1基本代码规范。代码必须使用四个空格符进行缩进，而不是一个tab键。每行应该保持在80个字符以内，软限制必须是120个字符，但一定不能有硬性限制。每个namespace命名空间声明语句和use声明语句块后面，必须有一个空白行。类的开始花括号()必须写在函数声明后自成一行，结束花括号()也必须写在函数主体后自成一行。方法的开始花括号()必须写在函数声明后自成一行，结束花括号()也必须写在函数主体后自成一行。在所有的属性和方法上都必须声明可见性(译者注：private，protected以及public)；abstract和final必须声明在可见性之前；static必须声明在可见性之后。控制结构的关键词后面必须有一个空格符，方法和函数调用一定不能有。控制结构的开始花括号()必须写在声明的同一行，而结束花括号()必须写在主体后自成一行。控制结构的开始左括号（）之后一定不能有空格，右括号()之前一定不能有空格。1.1 例子以下这个例子简单的展示了以上的大部分规范。 $b) $foo-bar($arg1); else BazClass:bar($arg2, $arg3); final public static function bar() / method body 2. 通则2.1 基本编码规范代码必须符合PSR-1的所有规范2.2 文件所有PHP文件必须使用Unix LF (linefeed)作为行的结束符。所有PHP文件必须以一个空白行结束。纯PHP代码文件必须省略最后的 ? 结束标签。2.3 行行的长度一定不能有硬性的约束。行长度的软性约束一定限制在120个字符以内；如果超过此长度，代码规范检查器必须发出警告，一定不能报错。每行不应该超过80个字符；超过80个字符的行，应该被拆分成多个不超过80个字符的后续行。在非空白行的后面一定不能有多余的空格符。空行可以用来改善可读性和区分相关的代码块。每行一定不能多余一条语句。2.4 缩进代码必须使用四个空格符缩进，一定不能使用tab键。备注：只用空格，不于tab混合使用，有助于避免代码差异、打补丁、重阅代码以及注释时产生混淆。使用空格还可以使调整细微的缩进来改变对齐变得简单。2.5 关键字和True/False/NullPHP关键字必须全部小写。PHP常量true,false和null*必须*全部小写。3. 命名空间以及Use声明存在命名空间时，其后面必须有一个空白行。所有的use，必须在命名空间后声明。每条use声明语句，必须只有一个use关键字。use声明语句块后面必须有一个空白行。例如：?phpnamespace VendorPackage;use FooClass;use BarClass as Bar;use OtherVendorOtherPackageBazClass;/ . additional PHP code .4. 类、属性和方法此处的“类”泛指所有的class类、接口以及traits可复用代码块。4.1 扩展和继承关键词extends和implements必须和类名在同一行。类开始的花括号（）必须独占一行，类结束的花括号（）必须在类主体后独占一行。?phpnamespace VendorPackage;use FooClass;use BarClass as Bar;use OtherVendorOtherPackageBazClass;class ClassName extends ParentClass implements ArrayAccess, Countable / constants, properties, methodsimplements的接口列表也可以分成多行，当这样做时，列表中的第一个接口必须放在下一行中，每行必须只有一个接口?phpnamespace VendorPackage;use FooClass;use BarClass as Bar;use OtherVendorOtherPackageBazClass;class ClassName extends ParentClass implements ArrayAccess, Countable, Serializable / constants, properties, methods4.2 属性所有属性都必须声明可见性。一定不能使用关键字var声明一个属性。每条语句一定不能定义超过一个属性。属性名称不应该以单个下划线作为前缀来表示属性是protected或private。一个属性的声明应该像下面这样。?phpnamespace VendorPackage;class ClassName public $foo = null;4.3 方法所有方法都必须声明可见性（访问修饰符）。方法名称不应该以单个下划线作为前缀来表示是protected或private。方法名称后一定不能有空格符，其开始花括号必须独占一行，结束花括号也必须在方法主体后单独成一行。参数左括号后和右括号前一定不能有空格。一个方法定义应该像下面这样，注意括号，逗号，空格和花括号的位置：?phpnamespace VendorPackage;class ClassName public function fooBarBaz($arg1, &$arg2, $arg3 = ) / method body 4.4 方法参数在参数列表中，每个逗号之前一定不能有空格，每个逗号之后必须有一个空格。方法参数中，有默认值的，必须放到参数列表的末尾。?phpnamespace VendorPackage;class ClassName public function foo($arg1, &$arg2, $arg3 = ) / method body 参数列表可以被拆分成分别有一次缩进的多行，这样，列表中的第一项必须放在下一行，每一行必须只放一个参数。拆分成多行的参数列表后，结束括号以及方法开始花括号必须写在同一行，中间用一个空格分隔，一起自成一行。?phpnamespace VendorPackage;class ClassName public function aVeryLongMethodName( ClassTypeHint $arg1, &$arg2, array $arg3 = ) / method body 4.5 abstract,final和static当存在时，abstract和final声明必须放在可见性之前。当存在时，static声明必须放在可见性后。?phpnamespace VendorPackage;abstract class ClassName protected static $foo; abstract protected function zim(); final public static function bar() / method body 4.6 方法和函数调用方法及函数调用时，方法名或函数名与左括号之间一定不能有空格，参数右括号前也一定不能有空格。在参数列表中，每个逗号之前一定不能有空格，每个逗号之后必须有一个空格。bar($arg1);Foo:bar($arg2, $arg3);参数可以被拆分成多个有一个缩进的后续行，如果这么做，参数列表中的第一个必须放在下一行，并且每一行只能有一个参数。bar( $longArgument, $longerArgument, $muchLongerArgument);5. 控制结构控制结构基本样式规范如下：控制结构关键词后必须有一个空格。左括号(后面一定不能有空格。右括号)前一定不能有空格。右括号)和开始花括号之间必须有一个空格。结构体必须缩进一次。结束花括号必须在主体后自成一行。每个结构体的主题都必须被包含在成对的花括号中，这使结构体看起来更加规范以及减少加入新行时，出错的可能性。5.1 if,elseif,else一个if的结构如下所示。注意其括号、空格以及花括号的位置，并且else和elseif和前一个主体的结束花括号在同一行。?phpif ($expr1) / if body elseif ($expr2) / elseif body else / else body;应该使用elseif代替else if，使得所有的控制关键词看起来像一个单词。5.2 switch和case一个switch结构如下所示。注意其括号、空格以及花括号的位置。case语句必须相对于switch进行一次缩进，break关键字（或其他终止关键字）必须和case主体缩进同级。如果存在一个非空的case直穿语句，则必须有一个类似/ no break的注释。?phpswitch ($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语句如下所示。注意其括号、空格以及花括号的位置。?phpwhile ($expr) / structure body同样，一个do while语句如下所示。注意其括号、空格以及花括号的位置。?phpdo / structure body; while ($expr);5.4 for一个for语句看起来像下面这个样子。注意其括号、空格以及花括号的位置。?phpfor ($i = 0; $i 10; $i+) / for body5.5 foreach一个foreach语句看起来像下面这样。注意其括号、空格以及花括号的位置。 $value) / ch body5.6 try,catch一个try catch语句块看起来像下面这样。注意其括号、空格以及花括号的位置。?phptry / try body catch (FirstExceptionType $e) / catch body catch (OtherExceptionType $e) / catch body6. 闭包闭包声明时，关键词function后以及关键词use的前后都必须有一个空格。开始的花括号必须写在声明的同一行，结束的花括号必须紧跟在主体的下一行。参数列表和变量列表的左括号后(以及右括号)前，一定不能有空格。参数列表和变量列表中，逗号前一定不能有空格，逗号后必须有空格。闭包带默认值的参数必须放在参数列表后面。一个闭包声明看起来像下面这个样子。注意其括号、逗号、空格以及花括号的位置。?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;注意：如果闭包在函数或方法中当做一个参数直接调用时，以上规则仍然适用。bar( $arg1, function ($arg2) use ($var1) / body , $arg3);7. 结论有许多元素的风格和实践在本指南中被故意忽略掉。这些包括但不限于：全局变量和常量的定义函数的定义操作符和赋值行内对齐注释和文档描述块类名的前缀及后缀最佳实践未来的建议可能会修改和扩展本指南，以解决这些或其他元素的风格和实践。三 日志接口规范主要目标是让类库获得一个 PsrLogLoggerInterface对象并且通过简单和通用的方式来写日志。有自定义需求的框架和CMS系统，可以根据情况扩展这个接口，但是应该和本文档保持兼容。这能确保使用第三方类库文件时仍能写到集中的应用程序日志中。关键词 “必须”(“MUST”)、“一定不可/一定不能”(“MUST NOT”)、“需要”(“REQUIRED”)、 “将会”(“SHALL”)、“不会”(“SHALL NOT”)、“应该”(“SHOULD”)、“不该”(“SHOULD NOT”)、 “推荐”(“RECOMMENDED”)、“可以”(“MAY”)和”可选“(“OPTIONAL”)的详细描述可参见 RFC 2119单词implementor(实现者)在这个文档中被解释为：在日志相关的库或框架实现LoggerInterface接口的人。用这些实现者开发出来的类库的人都被称作user(用户)。1. 规范1.1 基础LoggerInterface接口对外定义了八个方法，分别用来记录RFC 5424中定义的八个等级的日志：debug、 info、 notice、 warning、 error、 critical、 alert 以及 emergency 。第九个方法log,其第一个参数为记录的等级。用一个日志等级常量来调用这个方法必须和直接调用指定等级方法的结果一致。如果传入的等级常量参数没有预先定义，则必须抛出PsrLogInvalidArgumentException类型的异常。在不确定的情况下，使用者不应该使用自定义的日志等级。1.2 信息每个方法都接受一个字符串类型或者是有_toString()方法的对象作为记录信息参数。实现者可以对传入的对象有特殊的处理。如果不是这样，实现者必须把它转换成字符串。message参数中可能包含一些可以被上下文数组所替换的占位符。其中占位符必须与上下文数组中的键名保持一致。占位符名字必须使用一对花括号来作为分隔符。在占位符和分隔符之间一定不能有任何空格。占位符的名称应该只由A-Z、a-z,0-9、下划线_、以及英文的句号.组成，其它的字符作为以后占位符规范的保留字。实现者可以通过对占位符采用不同的转义和转换策略，来生成最终的日志。而用户在不知道上下文的前提下，不应该提前转义占位符。下面提供一个占位符替换的例子，仅作为参考： /* * Interpolates context values into the message placeholders. */ function interpolate($message, array $context = array() / build a replacement array with braces around the context keys $replace = array(); foreach ($context as $key = $val) / check that the value can be casted to string if (!is_array($val) & (!is_object($val) | method_exists($val, _toString) $replace . $key . = $val; / interpolate replacement values into the message and return return strtr($message, $replace); / a message with brace-delimited placeholder names $message = User username created; / a context array of placeholder names = replacement values $context = array(username = bolivar); / echoes User bolivar created echo interpolate($message, $context);1.3 上下文每个记录函数都接受一个上下文数组参数，用来存储不适合在字符串中填充的信息。它可以装载任何信息，所以实现者必须确保能正确处理其装载的信息，对于其装载的数据，一定不能抛出异常，或产生PHP出错、警告或提醒信息（error、warning、notice）。如果在上下文参数中传入了一个异常对象，它必须以exception作为键名。记录异常信息是一种常见的模式，并且可以在日志系统支持的情况下从异常中提取出整个调用栈。实现者在使用它时，必须确保键名为 exception的键值是否真的是一个Exception，毕竟它可以装载任何信息。1.4 助手类和接口PsrLogAbstractLogger类让你通过继承它并实现通用的log方法来方便的实现LoggerInterface接口。而其他八个方法将会把消息和上下文转发给log方法。同样地，使用PsrLogLoggerTrait也只需实现其中的log方法。不过，需要特别注意的是，在traits可复用代码块还不能实现接口前，还需要implement LoggerInterface。PsrLogNullLogger是和接口一起提供的。它在没有可用的日志记录器时，可以为使用日志接口的用户们提供一个后备的“黑洞”。然而，当上下文的构建非常消耗资源时，带条件检查的日志记录或许是更好的办法。PsrLogLoggerAwareInterface只有一个setLogger(LoggerInterface $logger)方法，它可以在框架中用来随意设置一个日志记录器。PsrLogLoggerAwareTraittrait可复用代码块可以在任何的类里面使用，只需通过它提供的$this-logger，就可以轻松地实现等同的接口。PsrLogLogLevel 类装载了八个记录等级常量。2. 包psr/log中提供了上文描述过的接口和类，以及相关的异常类，还有一组用来验证你的实现的单元测试。3. PsrLogLoggerInterface?phpnamespace PsrLog;/* * Describes a logger instance * * The message MUST be a string or object implementing _toString(). * * The message MAY contain placeholders in the form: foo where foo * will be replaced by the context data in key foo. * * The context array can contain arbitrary data, the only assumption that * can be made by implementors is that if an Exception instance is given * to produce a stack trace, it MUST be in a key named exception. * * See /php-fig/fig-standards/blob/master/accepted/PSR-3-logger-interface.md * for the full ace specification. */interface LoggerInterface /* * System is unusable. * * param string $message * param array $context * return null */ public function emergency($message, array $context = array(); /* * Action must be taken immediately. * * Example: Entire website down, database unavailable, etc. This should * trigger the SMS alerts and wake you up. * * param string $message * param array $context * return null */ public function alert($message, array $context = array(); /* * Critical conditions. * * Example: Application component unavailable, unexpected exception. * * param string $message * param array $context * return null */ public function critical($message, array $context = array(); /* * Runtime errors that do not require immediate action but should typically * be logged and monitored. * * param string $message * param array $context * return null */ public function error($message, array $context = array(); /* * Exceptional occurrences that are not errors. * * Example: Use of deprecated APIs, poor use of an API, undesirable things * that are not necessarily wrong. * * param string $message * param array $context * return null */ public function warning($message, array $context = array(); /* * Normal but significant events. * * param string $message * param array $context * return null */ public function notice($message, array $context = array(); /* * Interesting events. * * Example: User logs in, SQL logs. * * param string $message * param array $context * return null */ public function info($message, array $context = array(); /* * Detailed debug information. * * param string $message * param array $context * return null */ public function debug($message, array $context = array(); /* * Logs with an arbitrary level. * * param mixed $level * param string $message * param array $context * return null */ public function log($level, $message, array $context = array();4. PsrLogLoggerAwareInterface?phpnamespace PsrLog;/* * Describes a logger-aware instance */interface LoggerAwareInterface /* * Sets a logger instance on the object * * param LoggerInterface $logger * return null *