From 7aecff17904fed38e86f38bd47290b356f05ace8 Mon Sep 17 00:00:00 2001 From: hfcorriez Date: Sat, 2 Mar 2013 14:45:29 +0800 Subject: [PATCH 01/15] translate PSR-0 --- accepted/zh_CN/PSR-0.md | 59 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 accepted/zh_CN/PSR-0.md diff --git a/accepted/zh_CN/PSR-0.md b/accepted/zh_CN/PSR-0.md new file mode 100644 index 000000000..c75c6e1a5 --- /dev/null +++ b/accepted/zh_CN/PSR-0.md @@ -0,0 +1,59 @@ +下面描述了关于自动加载器特性强制性要求: + +强制性 +--------- + +* 一个完全标准的命名空间必须要有一下的格式结构`\\(\)*` +* 命名空间必须有一个顶级的组织名称 ("Vendor Name"). +* 命名空间中可以根据情况决定使用多少个子空间 +* 命名空间中的分隔符当从文件系统加载的时候将被映射为 `DIRECTORY_SEPARATOR` +* 命名空间中的类名中的`_`没有特殊含义,也将被作为`DIRECTORY_SEPARATOR`对待. +* 命名空间中的类名在从文件系统加载时文件名都需要以`.php`结尾 +* 组织名,空间名,类名都可以随意选择使用大小写英文字符 + +示例 +-------- + +* `\Doctrine\Common\IsolatedClassLoader` => `/path/to/project/lib/vendor/Doctrine/Common/IsolatedClassLoader.php` +* `\Symfony\Core\Request` => `/path/to/project/lib/vendor/Symfony/Core/Request.php` +* `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` +* `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` + +命名空间和类名中的下划线 +----------------------------------------- + +* `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` +* `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` + +以上是我们为实现无痛的自动加载特性设定的最低标准。你可以按照此标准实现一个SplClassLoader在PHP 5.3中去加载类。 + +实例 +---------------------- + +下面是一个函数实例简单展示如何使用上面建议的标准进行自动加载 +```php + Date: Sun, 3 Mar 2013 23:57:56 +0800 Subject: [PATCH 02/15] tranlsate PSR-1 --- accepted/zh_CN/PSR-1-basic-coding-standard.md | 152 ++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 accepted/zh_CN/PSR-1-basic-coding-standard.md diff --git a/accepted/zh_CN/PSR-1-basic-coding-standard.md b/accepted/zh_CN/PSR-1-basic-coding-standard.md new file mode 100644 index 000000000..f70e10fec --- /dev/null +++ b/accepted/zh_CN/PSR-1-basic-coding-standard.md @@ -0,0 +1,152 @@ +基本代码规范 +===================== + +本节标准包含了成为标准代码所需要的基本元素,以确保高级技术特性可以在PHP代码中共享。 + +在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“应当”(SHALL),“不应”(SHALL NOT),“可以”(SHOULD),“不可”(SHOULD NOT),“推荐”(RECOMMENDED),“或许”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 + +[RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt +[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md + + +1. 大纲 +----------- + +- 文件`必须`使用 ``或者短输出式``标签;它`不可`使用其他的标签变种。 + +### 2.2. 字符编码 + +PHP代码`必须`只使用不带BOM的UTF-8。 + +### 2.3. 边缘效应 + +一个文件`可以`声明新符号 (类名,函数名,常量等)并且不产生边缘效应,或者`可以`执行有边缘影响的逻辑,但不能同时使用。 + +短语"边缘效应"意思是不直接执行逻辑的类,函数,常量等 *仅包括文件* + +“边缘效应”包含但不局限于:生成输出,明确使用`require`和`include`,连接外部服务,修改ini配置,触发错误和异常,修改全局或者静态变量,读取或修改文件等等 + +下面是一个例子文件同时包含声明和边缘效应 +即避免的例子: + +```php +\n"; + +// declaration +function foo() +{ + // function body +} +``` + +下面这个例子仅仅包含声明并且没有边缘效应; +即需要提倡的例子: + +```php + Date: Fri, 5 Apr 2013 19:31:04 +0800 Subject: [PATCH 03/15] Fix url and add PSR-2 and PSR-3 --- accepted/zh_CN/PSR-0.md | 3 +- accepted/zh_CN/PSR-1-basic-coding-standard.md | 26 +- accepted/zh_CN/PSR-2-coding-style-guide.md | 721 ++++++++++++++++++ accepted/zh_CN/PSR-3-logger-interface.md | 259 +++++++ 4 files changed, 994 insertions(+), 15 deletions(-) create mode 100644 accepted/zh_CN/PSR-2-coding-style-guide.md create mode 100644 accepted/zh_CN/PSR-3-logger-interface.md diff --git a/accepted/zh_CN/PSR-0.md b/accepted/zh_CN/PSR-0.md index c75c6e1a5..65eeb34e9 100644 --- a/accepted/zh_CN/PSR-0.md +++ b/accepted/zh_CN/PSR-0.md @@ -55,5 +55,4 @@ SplClassLoader实现 下面的gist是一个SplClassLoader实例可以按照上面建议的自动加载特性来加载类。这也是我们当前推荐在PHP5.3中按照上述标准加载类的方式 -* [http://gist.github.com/221634](http://gist.github.com/221634) - +* [http://gist.github.com/221634](http://gist.github.com/221634) \ No newline at end of file diff --git a/accepted/zh_CN/PSR-1-basic-coding-standard.md b/accepted/zh_CN/PSR-1-basic-coding-standard.md index f70e10fec..d1f380d81 100644 --- a/accepted/zh_CN/PSR-1-basic-coding-standard.md +++ b/accepted/zh_CN/PSR-1-basic-coding-standard.md @@ -3,10 +3,10 @@ 本节标准包含了成为标准代码所需要的基本元素,以确保高级技术特性可以在PHP代码中共享。 -在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“应当”(SHALL),“不应”(SHALL NOT),“可以”(SHOULD),“不可”(SHOULD NOT),“推荐”(RECOMMENDED),“或许”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 +在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“将会”(SHALL),“不会”(SHALL NOT),“应当”(SHOULD),“不应”(SHOULD NOT),“推荐”(RECOMMENDED),“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 [RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt -[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md +[PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/zh_CN/PSR-0.md 1. 大纲 @@ -16,7 +16,7 @@ - 文件`必须`使用不带BOM的UTF-8代码文件。 -- 文件`可以`声明符号(类,函数,常量等...)或者引起边缘效应(例如:生成输出,修改.ini配置等),但不能同时存在。 +- 文件`应当`声明符号(类,函数,常量等...)或者引起副作用(例如:生成输出,修改.ini配置等),但不能同时存在。 - 命名空间和类名`必须`遵守 [PSR-0][]。 @@ -38,19 +38,19 @@ PHP代码`必须`使用长标签``或者短输出式``标签;它 PHP代码`必须`只使用不带BOM的UTF-8。 -### 2.3. 边缘效应 +### 2.3. 副作用 -一个文件`可以`声明新符号 (类名,函数名,常量等)并且不产生边缘效应,或者`可以`执行有边缘影响的逻辑,但不能同时使用。 +一个文件`应当`声明新符号 (类名,函数名,常量等)并且不产生副作用,或者`应当`执行有边缘影响的逻辑,但不能同时使用。 -短语"边缘效应"意思是不直接执行逻辑的类,函数,常量等 *仅包括文件* +短语"副作用"意思是不直接执行逻辑的类,函数,常量等 *仅包括文件* -“边缘效应”包含但不局限于:生成输出,明确使用`require`和`include`,连接外部服务,修改ini配置,触发错误和异常,修改全局或者静态变量,读取或修改文件等等 +“副作用”包含但不局限于:生成输出,明确使用`require`和`include`,连接外部服务,修改ini配置,触发错误和异常,修改全局或者静态变量,读取或修改文件等等 -下面是一个例子文件同时包含声明和边缘效应 +下面是一个例子文件同时包含声明和副作用 即避免的例子: ```php - $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(换行)作为行结束符。 + +所有PHP文件`必须`结束必须有一个空行。 + +纯PHP代码的文件关闭标签`?>``必须`省略 + +### 2.3. 行 + +行长度`不可`有硬限制。 + +行长度的软限制必须是120个字符;对于软限制,自动样式检查器`必须`警告但`不可`报错。 + +行实际长度`不应`超过80个字符;较长的行`应当`被拆分成多个不超过80个字符的后续行。 + +在非空行后面`不可`有空格。 + +空行`可以`用来改善可读性和区分相关的代码块。 + +一行`不应`多于一个语句。 + +### 2.4. 缩进 + +代码必须使用4个空格的缩进,并且`不可`使用制表符作为缩进。 + +> 注意:只用空格,不和制表符混合使用,将会帮助避免代码差异,补丁,历史和注解中的一些问题。使用空格还可以使调整细微的缩进来改进行间对齐变得非常简单。 + +### 2.5. 关键词和 True/False/Null + +PHP [keywords][] `必须`使用小写。 + +PHP常量`true`, `false`和`null``必须`使用小写。 + +[keywords]: http://php.net/manual/en/reserved.keywords.php + + +3. Namespace和Use声明 +--------------------------------- + +如果存在,`namespace`声明之后`必须`有一个空行。 + +如果存在,所有的`use`声明`必须`放在`namespace`声明的下面。 + +使用一个`use`关键字`必须`只用于一个声明。 + +在`use`声明后面`必须`有一个空行。 + +示例: + +```php +bar($arg1); +Foo::bar($arg2, $arg3); +``` + +参数列表`可以`被拆分成多个有一个缩进的后续行。如果这么做,列表中的第一项必须放在下一行,并且每一行`必须`只有一个参数。 + +```php +bar( + $longArgument, + $longerArgument, + $muchLongerArgument +); +``` + +5. 控制结构 +--------------------- + +对于控制结构的样式规则概括如下: + +- 控制结构关键词只有`必须`有一个空格 +- 左括号之后`不可`有空格 +- 右括号之前`不可`有空格 +- 在右括号和左花括号之间`必须`有一个空格 +- 结构体`必须`有一次缩进 +- 右花括号`必须`主体的下一行 + +每个结构的主体`必须`被括在花括号里。这结构看上去更标准化,并且当加新行的时候可以减少引入错误的可能性。 + +### 5.1. `if`,`elseif`,`else` + +一个`if`结构看起来应该像下面这样。注意括号,空格,花括号的位置;并且`else`和`elseif`和前一个主体的右花括号在同一行。 + +```php + $value) { + // foreach body +} +``` + +### 5.6. `try`, `catch` + +一个`try catch`语句看起来应该像下面这样。注意括号,空格和花括号的位置。 + +```php +bar( + $arg1, + function ($arg2) use ($var1) { + // body + }, + $arg3 +); +``` + + +7. 结论 +-------------- + +在该指南中有很多风格的元素和做法有意被忽略掉。这些包括但不局限于: + +- 全局变量和全局常量的声明 + +- 方法声明 + +- 操作符和赋值 + +- 行间对齐 + +- 注释和文档块 + +- 类名给你前缀和后缀 + +- 最佳实践 + +以后的建议`可以`修改和扩展该指南以满足这些或其他风格的元素和实践。 + +附录A 调查 +------------------ + +为了写这个风格指南,我们采用了调查个项目以确定共同的做法。这个调查在这里供他人查看。 + +### A.1. 调查数据 + + 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. 调查说明 + +`indent_type`: +缩进类型。 `tab` = "使用制表符",`2` or `4` = "空格数量" + +`line_length_limit_soft`: +行长度的“软”限制,用字符。 `?` = 不表示或者数字 `no` 意为不限制. + +`line_length_limit_hard`: +行长度的"硬"限制,用字符。 `?` = 不表示或者数字, `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`: +控制结构的左花括号在同(`same`)一行还是在下(`next`)一行? + +`control_space_after`: +控制结构关键词后是否有空格? + +`always_use_control_braces`: +控制结构总是使用花括号? + +`else_elseif_line`: +当使用`else`和`elseif`,是否放在同(`same`)一行还是在下(`next`)一行? + +`case_break_indent_from_switch`: +`case`和`break`分别从`swith`语句处缩进多少次? + +`function_space_after`: +函数调用的函数名和左括号是否有空格? + +`closing_php_tag_required`: +如过是纯PHP文件,关闭标签`?>`是否需要? + +`line_endings`: +使用何种的行结束符? + +`static_or_visibility_first`: +在定义方法的时候`static`和可见性谁在前面? + +`control_space_parens`: +在控制结构表达式中,左括号后面和右括号前面是否要有一个空格?`yes` = `if ( $expr )`, `no` = `if ($expr)`. + +`blank_line_after_php`: +PHP的开始标签后面是否需要一个空行? + +`class_method_control_brace`: +左花括号在类,方法和控制结构中的位置。 + +### A.3. 调查结果 + + 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 diff --git a/accepted/zh_CN/PSR-3-logger-interface.md b/accepted/zh_CN/PSR-3-logger-interface.md new file mode 100644 index 000000000..cdddb5431 --- /dev/null +++ b/accepted/zh_CN/PSR-3-logger-interface.md @@ -0,0 +1,259 @@ +日志接口 +================ + +本文档用来描述日志类库的通用接口。 + +主要目标是让类库获得一个`Psr\Log\LoggerInterface`对象并且使用一个简单通用的方式来写日志。有自定义需求的框架和CMS`可以`根据情况扩展这个接口,但`应当`保持和该文档的兼容性,这将确保使用第三方库和应用能统一的写应用日志。 + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [RFC 2119][]. + +关键词`实现者`在这个文档被解释为:在日志相关的库和框架实现`LoggerInterface`接口的人。用这些实现的人都被称作`用户`。 + +[RFC 2119]: http://tools.ietf.org/html/rfc2119 + +1. 规范 +----------------- + +### 1.1 基础 + +- `LoggerInterface`暴露八个接口用来记录八个等级(debug, info, notice, warning, error, critical, alert, emergency)的日志。 + +- 第九个方法是`log`,接受日志等级作为第一个参数。用一个日志等级常量来调用这个方法的结果`必须`和调用具体等级方法的一致。如果具体的实现不知道传入的不按规范的等级来调用这个方法`必须`抛出一个`Psr\Log\InvalidArgumentException`。用户`不应`自定义一个当前不支持的未知等级。 + +[RFC 5424]: http://tools.ietf.org/html/rfc5424 + +### 1.2 消息 + +- 每个方法都接受字符串,或者有`__toString`方法的对象作为消息。实现者可以对传入的对象有特殊的处理。如果不是,实现者`必须`将它转换成字符串。 + +- 消息`可以`包含`可以`被上下文数组的数值替换的占位符。 + + 占位符名字`必须`和上下文数组键名对应。 + + 占位符名字`必须`使用使用一对花括号为分隔。在占位符和分隔符之间`不能`有任何空格。 + + 占位符名字`应该`由`A-Z`,`a-z`,`0-9`,下划线`_`和句号`.`。其它的字符作为以后占位符规范的保留。 + + 实现者可以使用占位符来实现不同的转义和翻译日志成文。用户在不知道上下文数据是什么的时候`不应`提前转义占位符。 + + 下面提供一个占位符替换的例子,仅作为参考: + + ```php + /** + * 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) { + $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 "Username bolivar created" + echo interpolate($message, $context); + ``` + +### 1.3 上下文 + +- 每个方法接受一个数组作为上下文数据,用来存储不适合在字符串中填充的信息。数组可以包括任何东西。实现者`必须`确保他们对上下文数据足够的掌控。在上下文中一个给定值`不可`抛出一个异常,也`不可`产生任何PHP错误,警告或者提醒。 + +- 如果在上下文中传入了一个`异常`对象,它必须以`exception`作为键名。记录异常轨迹是通用的模式,如果日志底层支持这样也是可以被允许的。实现者在使用它之前`必须`验证`exception`的键值是不是一个`异常`对象,因为它`可以`允许是任何东西。 + +### 1.4 助手类和接口 + +- `Psr\Log\AbstractLogger`类让你非常简单的实现和扩展`LoggerInterface`接口以实现通用的`log`方法。其他八个方法将会把消息和上下文转发给它。 + +- 类似的,使用`Psr\Log\LoggerTrait`只需要你实现通用的`log`方法。记住traits不能实现接口前,你依然需要`implement LoggerInterface`。 + +- `Psr\Log\NullLogger`是和接口一个提供的。它`可以`为使用接口的用户提供一个后备的“黑洞”。如果上下文数据非常重要,这不失为一个记录日志更好的办法。 + +- `Psr\Log\LoggerAwareInterface`只有一个`setLogger(LoggerInterface $logger)`方法可以用来随意设置一个日志记录器。 + +- `Psr\Log\LoggerAwareTrait`trait可以更简单的实现等价于接口。通过它可以访问到`$this->logger`。 + +- `Psr\Log\LogLevel`类拥有八个等级的常量。 + +2. 包 +---------- + +作为[psr/log](https://packagist.org/packages/psr/log) 的一部分,提供接口和相关异常类的一些描述以及一些测试单元用来验证你的实现。 + +3. `Psr\Log\LoggerInterface` +---------------------------- + +```php + Date: Mon, 8 Apr 2013 21:04:00 +0800 Subject: [PATCH 04/15] =?UTF-8?q?fix=204.3=E8=87=AA=E6=88=90=E4=B8=80?= =?UTF-8?q?=E8=A1=8C=E7=9A=84=E9=97=AE=E9=A2=98=20thx=20WangTaizhou?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- accepted/zh_CN/PSR-2-coding-style-guide.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/accepted/zh_CN/PSR-2-coding-style-guide.md b/accepted/zh_CN/PSR-2-coding-style-guide.md index 96b59522c..b32d07d26 100644 --- a/accepted/zh_CN/PSR-2-coding-style-guide.md +++ b/accepted/zh_CN/PSR-2-coding-style-guide.md @@ -148,7 +148,7 @@ use OtherVendor\OtherPackage\BazClass; 一个类的`extends`和`implements`关键词`必须`和类名在同一行。 -类的左花括号`必须`放在下一行;右花括号必须放在类的主体后面。 +类的左花括号`必须`放在下面自成一行;右花括号必须放在类主体的后面自成一行。 ```php @@ -212,7 +212,7 @@ class ClassName 方法名`不应`只使用单个下划线来表明是保护或私有的可见性。 -方法名在声明之后`不可`跟随一个空格。左花括号`必须`放在同一行,并且右花括号`必须`放在接下来的主体下面。左括号后面`不可`有空格,右括号前面`不可`有空格。 +方法名在声明之后`不可`跟随一个空格。左花括号`必须`放在下面自成一行,并且右花括号`必须`放在方法主体的下面自成一行。左括号后面`不可`有空格,右括号前面`不可`有空格。 一个方法定义看来应该像下面这样。 注意括号,逗号,空格和花括号: @@ -250,7 +250,7 @@ class ClassName 参数列表`可以`被分为多个有一次缩进的多个后续行。如果这么做,列表的第一项`必须`放在下一行,并且每行`必须`只放一个参数。 -当参数列表被分为多行,右花括号和左括号`必须`在用一个空格连起来放在一起。 +当参数列表被分为多行,右花括号和左括号`必须`夹带一个空格放在一起自成一行。 ```php Date: Wed, 10 Apr 2013 09:47:33 +0800 Subject: [PATCH 05/15] =?UTF-8?q?PSR-0=20=E9=83=A8=E5=88=86=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- accepted/zh_CN/PSR-0.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/accepted/zh_CN/PSR-0.md b/accepted/zh_CN/PSR-0.md index 65eeb34e9..c06dbe185 100644 --- a/accepted/zh_CN/PSR-0.md +++ b/accepted/zh_CN/PSR-0.md @@ -3,13 +3,13 @@ 强制性 --------- -* 一个完全标准的命名空间必须要有一下的格式结构`\\(\)*` +* 一个完全标准的命名空间必须要有以下的格式结构`\\(\)*` * 命名空间必须有一个顶级的组织名称 ("Vendor Name"). -* 命名空间中可以根据情况决定使用多少个子空间 -* 命名空间中的分隔符当从文件系统加载的时候将被映射为 `DIRECTORY_SEPARATOR` -* 命名空间中的类名中的`_`没有特殊含义,也将被作为`DIRECTORY_SEPARATOR`对待. -* 命名空间中的类名在从文件系统加载时文件名都需要以`.php`结尾 -* 组织名,空间名,类名都可以随意选择使用大小写英文字符 +* 命名空间中可以根据情况使用任意数量的子空间 +* 从文件系统中加载源文件的时,命名空间中的分隔符将被映射为 `DIRECTORY_SEPARATOR` +* 命名空间中的类名中的`_`没有特殊含义,也将被作为`DIRECTORY_SEPARATOR`对待. +* 标准的命名空间和类从文件系统加载源文件时只需要加上`.php`后缀即可 +* 组织名,空间名,类名都可以随意使用大小写英文字符的组合 示例 -------- @@ -25,7 +25,7 @@ * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` -以上是我们为实现无痛的自动加载特性设定的最低标准。你可以按照此标准实现一个SplClassLoader在PHP 5.3中去加载类。 +以上是我们为轻松实现自动加载特性设定的最低标准。你可以利用下面这个可以自动加载 PHP 5.3 类的SplClassLoader来测试你的代码是否符合以上这些标准。 实例 ---------------------- @@ -53,6 +53,6 @@ function autoload($className) SplClassLoader实现 ----------------------------- -下面的gist是一个SplClassLoader实例可以按照上面建议的自动加载特性来加载类。这也是我们当前推荐在PHP5.3中按照上述标准加载类的方式 +下面的gist是一个可以按照上面建议的自动加载特性来加载类的SplClassLoader实例。这也是我们当前在PHP5.3中依据以上标准加载类时推荐的方。 -* [http://gist.github.com/221634](http://gist.github.com/221634) \ No newline at end of file +* [http://gist.github.com/221634](http://gist.github.com/221634) From 41d82ed27a5c5e52b57c577126acf36f1a718b0d Mon Sep 17 00:00:00 2001 From: thbourlove Date: Wed, 10 Apr 2013 10:13:57 +0800 Subject: [PATCH 06/15] =?UTF-8?q?PSR-1=20=E9=83=A8=E5=88=86=E4=BF=AE?= =?UTF-8?q?=E6=AD=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- accepted/zh_CN/PSR-1-basic-coding-standard.md | 44 +++++++++---------- 1 file changed, 21 insertions(+), 23 deletions(-) diff --git a/accepted/zh_CN/PSR-1-basic-coding-standard.md b/accepted/zh_CN/PSR-1-basic-coding-standard.md index d1f380d81..cf6550d7d 100644 --- a/accepted/zh_CN/PSR-1-basic-coding-standard.md +++ b/accepted/zh_CN/PSR-1-basic-coding-standard.md @@ -1,7 +1,7 @@ 基本代码规范 ===================== -本节标准包含了成为标准代码所需要的基本元素,以确保高级技术特性可以在PHP代码中共享。 +本节标准包含了成为标准代码所需要的基本元素,以确保开源出来的PHP代码之间有较高度的技术互用性。 在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“将会”(SHALL),“不会”(SHALL NOT),“应当”(SHOULD),“不应”(SHOULD NOT),“推荐”(RECOMMENDED),“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 @@ -9,20 +9,20 @@ [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/zh_CN/PSR-0.md -1. 大纲 +1. 大纲 ----------- -- 文件`必须`使用 ``或者短输出式``标签;它`不可`使用其他的标签变种。 +PHP代码`必须`只使用长标签``或者短输出式``标签;它`不可`使用其他的标签变种。 ### 2.2. 字符编码 @@ -40,17 +40,16 @@ PHP代码`必须`只使用不带BOM的UTF-8。 ### 2.3. 副作用 -一个文件`应当`声明新符号 (类名,函数名,常量等)并且不产生副作用,或者`应当`执行有边缘影响的逻辑,但不能同时使用。 +一个文件`应当`声明新符号 (类名,函数名,常量等)并且不产生副作用,或者`应当`执行有副作用的逻辑,但不能同时做这两件事。 短语"副作用"意思是不直接执行逻辑的类,函数,常量等 *仅包括文件* -“副作用”包含但不局限于:生成输出,明确使用`require`和`include`,连接外部服务,修改ini配置,触发错误和异常,修改全局或者静态变量,读取或修改文件等等 +“副作用”包含但不局限于:生成输出,显式地使用`require`或`include`,连接外部服务,修改ini配置,触发错误或异常,修改全局或者静态变量,读取或修改文件等等 -下面是一个例子文件同时包含声明和副作用 -即避免的例子: +下面是一个既包含声明又有副作用的示例文件;即应避免的例子: ```php - Date: Wed, 10 Apr 2013 12:29:02 +0800 Subject: [PATCH 07/15] =?UTF-8?q?PSR-2=20=E9=83=A8=E5=88=86=E4=BF=AE?= =?UTF-8?q?=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- accepted/zh_CN/PSR-2-coding-style-guide.md | 38 +++++++++++----------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/accepted/zh_CN/PSR-2-coding-style-guide.md b/accepted/zh_CN/PSR-2-coding-style-guide.md index b32d07d26..91204fb58 100644 --- a/accepted/zh_CN/PSR-2-coding-style-guide.md +++ b/accepted/zh_CN/PSR-2-coding-style-guide.md @@ -1,11 +1,11 @@ 代码样式规范 ================== -本手册是从 [PSR-1][]基础代码规范的继承和扩展 +本手册是 [PSR-1][]基础代码规范的继承和扩展 -本指南的意图是为了减少不同开发者在浏览代码时减少认知的差异。 通过列举一组共用规则来展示如何格式化代码。 +本指南的意图是为了减少不同开发者在浏览代码时减少认知的差异。 为此列举一组如何格式化PHP代码的共用规则。 -各个成员项目的共性组成了本文的样式规则。当不同的开发者在不同的项目中合作时,这将会有一个共同的准则在这些项目中使用。 因此,本指南的好处不是规则本身,而是在共同使用这些规则。 +各个成员项目的共性组成了本文的样式规则。当不同的开发者在不同的项目中合作时,将会在这些不同的项目中使用一个共同的标准。 因此,本指南的好处不在于规则本身,而在于共用这些规则。 在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“将会”(SHALL),“不会”(SHALL NOT),“应当”(SHOULD),“不应”(SHOULD NOT),“推荐”(RECOMMENDED),“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 @@ -22,18 +22,18 @@ - 代码`必须`使用4个空格的缩进,而不是制表符。 - 一行代码长度`不应`硬性限制;软限制`必须`为120个字符;也`应当`是80个字符或者更少。 - + - 在`namespace`声明下面`必须`有一个空行,并且`use`声明代码块下面也`必须`有一个空行。 - 类的左花括号`必须`放到下一行,右花括号`必须`放在类主体的下一行。 -- 方法的左花括号`必须`放在下一行,右花括号`必须`放在函数主体下面。 +- 方法的左花括号`必须`放在下一行,右花括号`必须`放在方法主体下面。 - 所有的属性和方法`必须`有可见性(译者注:Public, Protect, Private)声明;`abstract`和`final`声明`必须`在可见性之前;`static`声明`必须`在可见性之后。 - + - 控制结构的关键词`必须`在后面有一个空格; 方法和函数`不可`有。 -- 控制结构的左花括号必须放在同一行,右花括号`必须`放在控制主体的下一行。 +- 控制结构的左花括号`必须`放在同一行,右花括号`必须`放在控制主体的下一行。 - 控制结构的左括号后面`不可`有空格,右括号之前`不可`有空格。 @@ -80,7 +80,7 @@ class Foo extends Bar implements FooInterface 所有的PHP文件`必须`使用Unix LF(换行)作为行结束符。 -所有PHP文件`必须`结束必须有一个空行。 +所有PHP文件`必须`以一个空行结束。 纯PHP代码的文件关闭标签`?>``必须`省略 @@ -88,7 +88,7 @@ class Foo extends Bar implements FooInterface 行长度`不可`有硬限制。 -行长度的软限制必须是120个字符;对于软限制,自动样式检查器`必须`警告但`不可`报错。 +行长度的软限制`必须`是120个字符;对于软限制,自动样式检查器`必须`警告但`不可`报错。 行实际长度`不应`超过80个字符;较长的行`应当`被拆分成多个不超过80个字符的后续行。 @@ -100,9 +100,9 @@ class Foo extends Bar implements FooInterface ### 2.4. 缩进 -代码必须使用4个空格的缩进,并且`不可`使用制表符作为缩进。 +代码`必须`使用4个空格的缩进,并且`不可`使用制表符作为缩进。 -> 注意:只用空格,不和制表符混合使用,将会帮助避免代码差异,补丁,历史和注解中的一些问题。使用空格还可以使调整细微的缩进来改进行间对齐变得非常简单。 +> 注意:只用空格,不和制表符混合使用,将会对避免代码差异,补丁,历史和注解中的一些问题有帮助。使用空格还可以使调整细微的缩进来改进行间对齐变得非常简单。 ### 2.5. 关键词和 True/False/Null @@ -120,9 +120,9 @@ PHP常量`true`, `false`和`null``必须`使用小写。 如果存在,所有的`use`声明`必须`放在`namespace`声明的下面。 -使用一个`use`关键字`必须`只用于一个声明。 +一个`use`关键字`必须`只用于一个声明。 -在`use`声明后面`必须`有一个空行。 +在`use`声明代码块后面`必须`有一个空行。 示例: @@ -227,13 +227,13 @@ class ClassName // method body } } -``` +``` ### 4.4. 方法参数 在参数列表中,逗号之前`不可`有空格,逗号之后`必须`要有一个空格。 -方法参数中有默认值的必须放在参数列表的后面。 +方法中有默认值的参数必须放在参数列表的最后面。 ```php bar( 对于控制结构的样式规则概括如下: -- 控制结构关键词只有`必须`有一个空格 +- 控制结构关键词之后`必须`有一个空格 - 左括号之后`不可`有空格 - 右括号之前`不可`有空格 - 在右括号和左花括号之间`必须`有一个空格 -- 结构体`必须`有一次缩进 +- 代码主体`必须`有一次缩进 - 右花括号`必须`主体的下一行 每个结构的主体`必须`被括在花括号里。这结构看上去更标准化,并且当加新行的时候可以减少引入错误的可能性。 @@ -402,7 +402,7 @@ for ($i = 0; $i < 10; $i++) { ``` ### 5.5. `foreach` - + 一个`foreach`语句看起来应该像下面这样。注意括号,空格和花括号的位置。 ```php @@ -432,7 +432,7 @@ try { 闭包在声明时`function`关键词之后`必须`有一个空格,并且`use`之前也需要一个空格。 -左花括号`必须`在同一行,右花括号在主体的下一行。 +左花括号`必须`在同一行,右花括号`必须`在主体的下一行。 参数列表和变量列表的左括号之后`不可`有空格,其右括号之前也`不可`有空格。 From d48daaefeb2c3370b1af8e782791453c44a9a5e9 Mon Sep 17 00:00:00 2001 From: hfcorriez Date: Wed, 17 Apr 2013 23:47:44 +0800 Subject: [PATCH 08/15] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E6=8B=AC=E5=8F=B7?= =?UTF-8?q?=E5=92=8C=E8=8A=B1=E6=8B=AC=E5=8F=B7=E9=97=AE=E9=A2=98.=20thx?= =?UTF-8?q?=20deloz!?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- accepted/zh_CN/PSR-2-coding-style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/accepted/zh_CN/PSR-2-coding-style-guide.md b/accepted/zh_CN/PSR-2-coding-style-guide.md index 91204fb58..1ecaa5984 100644 --- a/accepted/zh_CN/PSR-2-coding-style-guide.md +++ b/accepted/zh_CN/PSR-2-coding-style-guide.md @@ -250,7 +250,7 @@ class ClassName 参数列表`可以`被分为多个有一次缩进的多个后续行。如果这么做,列表的第一项`必须`放在下一行,并且每行`必须`只放一个参数。 -当参数列表被分为多行,右花括号和左括号`必须`夹带一个空格放在一起自成一行。 +当参数列表被分为多行,右括号和左花括号`必须`夹带一个空格放在一起自成一行。 ```php Date: Sat, 31 Aug 2013 23:57:02 +0800 Subject: [PATCH 09/15] optimize PSR-3 --- accepted/zh_CN/PSR-3-logger-interface.md | 79 ++++++++++++------------ 1 file changed, 40 insertions(+), 39 deletions(-) diff --git a/accepted/zh_CN/PSR-3-logger-interface.md b/accepted/zh_CN/PSR-3-logger-interface.md index cdddb5431..763d604e9 100644 --- a/accepted/zh_CN/PSR-3-logger-interface.md +++ b/accepted/zh_CN/PSR-3-logger-interface.md @@ -3,13 +3,13 @@ 本文档用来描述日志类库的通用接口。 -主要目标是让类库获得一个`Psr\Log\LoggerInterface`对象并且使用一个简单通用的方式来写日志。有自定义需求的框架和CMS`可以`根据情况扩展这个接口,但`应当`保持和该文档的兼容性,这将确保使用第三方库和应用能统一的写应用日志。 +主要目标是让类库获得一个`Psr\Log\LoggerInterface`对象并能通过简单通用的方式来写日志。有自定义需求的框架和CMS`可以`根据情况扩展这个接口,但`应当`保持和该文档的兼容性,以确保应用中使用到的第三方库能将日志集中写到应用日志里。 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][]. -关键词`实现者`在这个文档被解释为:在日志相关的库和框架实现`LoggerInterface`接口的人。用这些实现的人都被称作`用户`。 +关键词`实现者`在这个文档被解释为:在日志相关的库或框架实现`LoggerInterface`接口的人。用这些实现的人都被称作`用户`。 [RFC 2119]: http://tools.ietf.org/html/rfc2119 @@ -20,76 +20,77 @@ interpreted as described in [RFC 2119][]. - `LoggerInterface`暴露八个接口用来记录八个等级(debug, info, notice, warning, error, critical, alert, emergency)的日志。 -- 第九个方法是`log`,接受日志等级作为第一个参数。用一个日志等级常量来调用这个方法的结果`必须`和调用具体等级方法的一致。如果具体的实现不知道传入的不按规范的等级来调用这个方法`必须`抛出一个`Psr\Log\InvalidArgumentException`。用户`不应`自定义一个当前不支持的未知等级。 +- 第九个方法是`log`,接受日志等级作为第一个参数。用一个日志等级常量来调用这个方法`必须`和直接调用指定等级方法的结果一致。用一个本规范中未定义且不为具体实现所知的日志等级来调用该方法`必须`抛出一个`Psr\Log\InvalidArgumentException`。用户确定某自定义日志等级被当前实现所支持前,`不应`使用它。 [RFC 5424]: http://tools.ietf.org/html/rfc5424 ### 1.2 消息 -- 每个方法都接受字符串,或者有`__toString`方法的对象作为消息。实现者可以对传入的对象有特殊的处理。如果不是,实现者`必须`将它转换成字符串。 +- 每个方法都接受一个字符串,或者一个有`__toString`方法的对象作为`message`参数。`实现者``可以`对传入的对象有特殊的处理。如果没有,`实现者``必须`将它转换成字符串。 -- 消息`可以`包含`可以`被上下文数组的数值替换的占位符。 +- `message`参数中`可能`包含一些`可以`被`context`参数的数值所替换的占位符。 - 占位符名字`必须`和上下文数组键名对应。 + 占位符名字`必须`和`context`数组类型参数的键名对应。 - 占位符名字`必须`使用使用一对花括号为分隔。在占位符和分隔符之间`不能`有任何空格。 + 占位符名字`必须`使用一对花括号来作为分隔符。在占位符和分隔符之间`不能`有任何空格。 - 占位符名字`应该`由`A-Z`,`a-z`,`0-9`,下划线`_`和句号`.`。其它的字符作为以后占位符规范的保留。 + 占位符名字`应该`只能由`A-Z`,`a-z`,`0-9`,下划线`_`和句号`.`组成。其它的字符作为以后占位符规范的保留字。 - 实现者可以使用占位符来实现不同的转义和翻译日志成文。用户在不知道上下文数据是什么的时候`不应`提前转义占位符。 + `实现者``可以`使用占位符来实现不同的转义和翻译日志成文。因为`用户`并不知道上下文数据会是什么,所以他们`不应`提前转义占位符。 下面提供一个占位符替换的例子,仅作为参考: - ```php - /** - * 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) { - $replace['{' . $key . '}'] = $val; - } + ```php + $val) { + $replace['{' . $key . '}'] = $val; + } - // interpolate replacement values into the message and return - return strtr($message, $replace); - } + // interpolate replacement values into the message and return + return strtr($message, $replace); + } - // a message with brace-delimited placeholder names - $message = "User {username} created"; + // a message with brace-delimited placeholder names + $message = "User {username} created"; - // a context array of placeholder names => replacement values - $context = array('username' => 'bolivar'); + // a context array of placeholder names => replacement values + $context = array('username' => 'bolivar'); - // echoes "Username bolivar created" - echo interpolate($message, $context); - ``` + // echoes "Username bolivar created" + echo interpolate($message, $context); + ``` ### 1.3 上下文 -- 每个方法接受一个数组作为上下文数据,用来存储不适合在字符串中填充的信息。数组可以包括任何东西。实现者`必须`确保他们对上下文数据足够的掌控。在上下文中一个给定值`不可`抛出一个异常,也`不可`产生任何PHP错误,警告或者提醒。 +- 每个方法接受一个数组作为`context`参数,用来存储不适合在字符串中填充的信息。数组可以包括任何东西。`实现者``必须`确保他们尽可能包容的对`context`参数进行处理。一个`context`参数的给定值`不可`导致抛出异常,也`不可`产生任何PHP错误,警告或者提醒。 -- 如果在上下文中传入了一个`异常`对象,它必须以`exception`作为键名。记录异常轨迹是通用的模式,如果日志底层支持这样也是可以被允许的。实现者在使用它之前`必须`验证`exception`的键值是不是一个`异常`对象,因为它`可以`允许是任何东西。 +- 如果在`context`参数中传入了一个`异常`对象,它必须以`exception`作为键名。记录异常轨迹是通用的模式,并且可以在日志系统支持的情况下从异常中提取出整个调用栈。`实现者`在将`exception`当做`异常`对象来使用之前`必须`去验证它是不是一个`异常`对象,因为它`可能`包含着任何东西。 ### 1.4 助手类和接口 -- `Psr\Log\AbstractLogger`类让你非常简单的实现和扩展`LoggerInterface`接口以实现通用的`log`方法。其他八个方法将会把消息和上下文转发给它。 +- `Psr\Log\AbstractLogger`类可以让你通过继承它并实现通用的`log`方法来方便的实现`LoggerInterface`接口。而其他八个方法将会把消息和上下文转发给`log`方法。 -- 类似的,使用`Psr\Log\LoggerTrait`只需要你实现通用的`log`方法。记住traits不能实现接口前,你依然需要`implement LoggerInterface`。 +- 类似的,使用`Psr\Log\LoggerTrait`只需要你实现通用的`log`方法。注意特性是不能用来实现接口的,所以你依然需要在你的类中`implement LoggerInterface`。 -- `Psr\Log\NullLogger`是和接口一个提供的。它`可以`为使用接口的用户提供一个后备的“黑洞”。如果上下文数据非常重要,这不失为一个记录日志更好的办法。 +- `Psr\Log\NullLogger`是和接口一起提供的。它在没有可用的日志记录器时,`可以`为使用日志接口的`用户`们提供一个后备的“黑洞”。但是,当`context`参数的构建非常耗时的时候,直接判断是否需要记录日志可能是个更好的选择。 -- `Psr\Log\LoggerAwareInterface`只有一个`setLogger(LoggerInterface $logger)`方法可以用来随意设置一个日志记录器。 +- `Psr\Log\LoggerAwareInterface`只有一个`setLogger(LoggerInterface $logger)`方法,它可以在框架中用来随意设置一个日志记录器。 -- `Psr\Log\LoggerAwareTrait`trait可以更简单的实现等价于接口。通过它可以访问到`$this->logger`。 +- `Psr\Log\LoggerAwareTrait`特性可以被用来在各个类中轻松实现相同的接口。通过它可以访问到`$this->logger`。 -- `Psr\Log\LogLevel`类拥有八个等级的常量。 +- `Psr\Log\LogLevel`类拥有八个日志等级的常量。 2. 包 ---------- -作为[psr/log](https://packagist.org/packages/psr/log) 的一部分,提供接口和相关异常类的一些描述以及一些测试单元用来验证你的实现。 +[psr/log](https://packagist.org/packages/psr/log)中提供了上文描述过的接口和类,以及相关的异常类,还有一组用来验证你的实现的单元测试。 3. `Psr\Log\LoggerInterface` ---------------------------- From 3cfb6e4042b96a5861c1616ba40be72fbc2ec539 Mon Sep 17 00:00:00 2001 From: thbourlove Date: Thu, 5 Sep 2013 09:59:53 +0800 Subject: [PATCH 10/15] optimize PSR-0 --- accepted/zh_CN/PSR-0.md | 29 +++++++++++++++-------------- 1 file changed, 15 insertions(+), 14 deletions(-) diff --git a/accepted/zh_CN/PSR-0.md b/accepted/zh_CN/PSR-0.md index c06dbe185..fe4ae0411 100644 --- a/accepted/zh_CN/PSR-0.md +++ b/accepted/zh_CN/PSR-0.md @@ -1,15 +1,15 @@ -下面描述了关于自动加载器特性强制性要求: +下文描述了若要使用一个通用的`自动加载器(autoloader)`,你所需要遵守的规范: -强制性 +规范 --------- -* 一个完全标准的命名空间必须要有以下的格式结构`\\(\)*` -* 命名空间必须有一个顶级的组织名称 ("Vendor Name"). -* 命名空间中可以根据情况使用任意数量的子空间 -* 从文件系统中加载源文件的时,命名空间中的分隔符将被映射为 `DIRECTORY_SEPARATOR` -* 命名空间中的类名中的`_`没有特殊含义,也将被作为`DIRECTORY_SEPARATOR`对待. -* 标准的命名空间和类从文件系统加载源文件时只需要加上`.php`后缀即可 -* 组织名,空间名,类名都可以随意使用大小写英文字符的组合 +* 一个完全标准的`命名空间(namespace)`和`类(class)`的结构是这样的:`\\(\)*` +* 每个`命名空间(namespace)`都必须有一个顶级的`空间名(namespace)`("`组织名(Vendor Name)`")。 +* 每个`命名空间(namespace)`中可以根据需要使用任意数量的`子命名空间(sub-namespace)`。 +* 从文件系统中加载源文件时,`空间名(namespace)`中的分隔符将被转换为 `DIRECTORY_SEPARATOR`。 +* `类名(class name)`中的每个下划线`_`都将被转换为一个`DIRECTORY_SEPARATOR`。下划线`_`在`空间名(namespace)`中没有什么特殊的意义。 +* 完全标准的`命名空间(namespace)`和`类(class)`从文件系统加载源文件时将会加上`.php`后缀。 +* `组织名(vendor name)`,`空间名(namespace)`,`类名(class name)`都由大小写字母组合而成。 示例 -------- @@ -19,18 +19,19 @@ * `\Zend\Acl` => `/path/to/project/lib/vendor/Zend/Acl.php` * `\Zend\Mail\Message` => `/path/to/project/lib/vendor/Zend/Mail/Message.php` -命名空间和类名中的下划线 +`空间名(namespace)`和`类名(class name)`中的下划线 ----------------------------------------- * `\namespace\package\Class_Name` => `/path/to/project/lib/vendor/namespace/package/Class/Name.php` * `\namespace\package_name\Class_Name` => `/path/to/project/lib/vendor/namespace/package_name/Class/Name.php` -以上是我们为轻松实现自动加载特性设定的最低标准。你可以利用下面这个可以自动加载 PHP 5.3 类的SplClassLoader来测试你的代码是否符合以上这些标准。 +以上是我们为实现通用的自动加载而制定的最低标准。你可以利用能够自动加载`PHP 5.3`类的`SplClassLoader`来测试你的代码是否符合这些标准。 实例 ---------------------- -下面是一个函数实例简单展示如何使用上面建议的标准进行自动加载 +下面是一个怎样利用上述标准来实现自动加载的示例函数。 + ```php Date: Thu, 5 Sep 2013 10:00:37 +0800 Subject: [PATCH 11/15] optimize PSR-1 --- accepted/zh_CN/PSR-1-basic-coding-standard.md | 78 +++++++++---------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/accepted/zh_CN/PSR-1-basic-coding-standard.md b/accepted/zh_CN/PSR-1-basic-coding-standard.md index cf6550d7d..fbed2f43b 100644 --- a/accepted/zh_CN/PSR-1-basic-coding-standard.md +++ b/accepted/zh_CN/PSR-1-basic-coding-standard.md @@ -1,30 +1,30 @@ 基本代码规范 ===================== -本节标准包含了成为标准代码所需要的基本元素,以确保开源出来的PHP代码之间有较高度的技术互用性。 +本节我们将会讨论一些基本的代码规范问题,以此作为将来讨论更高级别的代码分享和技术互用的基础。 -在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“将会”(SHALL),“不会”(SHALL NOT),“应当”(SHOULD),“不应”(SHOULD NOT),“推荐”(RECOMMENDED),“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 +[RFC 2119][]中的`必须(MUST)`,`不可(MUST NOT)`,`建议(SHOULD)`,`不建议(SHOULD NOT)`,`可以/可能(MAY)`等关键词将在本节用来做一些解释性的描述。 [RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/zh_CN/PSR-0.md -1. 大纲 +1. 概述 ----------- -- 源文件`必须`只使用 ``或者短输出式``标签;它`不可`使用其他的标签变种。 +PHP代码`必须`只使用`长标签()`或者`短输出式标签()`;而`不可`使用其他标签。 ### 2.2. 字符编码 -PHP代码`必须`只使用不带BOM的UTF-8。 +PHP代码的编码格式`必须`只使用不带`字节顺序标记(BOM)`的`UTF-8`。 ### 2.3. 副作用 -一个文件`应当`声明新符号 (类名,函数名,常量等)并且不产生副作用,或者`应当`执行有副作用的逻辑,但不能同时做这两件事。 +一个源文件`建议`只用来做声明(`类(class)`,`函数(function)`,`常量(constant)`等)或者只用来做一些引起副作用的操作(例如:输出信息,修改`.ini`配置等),但`不建议`同时做这两件事。 -短语"副作用"意思是不直接执行逻辑的类,函数,常量等 *仅包括文件* +短语`副作用(side effects)`的意思是 *在包含文件时* 所执行的逻辑与所声明的`类(class)`,`函数(function)`,`常量(constant)`等没有直接的关系。 -“副作用”包含但不局限于:生成输出,显式地使用`require`或`include`,连接外部服务,修改ini配置,触发错误或异常,修改全局或者静态变量,读取或修改文件等等 +`副作用(side effects)`包含但不局限于:产生输出,显式地使用`require`或`include`,连接外部服务,修改ini配置,触发错误或异常,修改全局或者静态变量,读取或修改文件等等 下面是一个既包含声明又有副作用的示例文件;即应避免的例子: ```php \n"; -// declaration +// 声明 function foo() { - // function body + // 函数体 } ``` -下面是一个仅包含声明的示例文件;即需要提倡的例子: +下面是一个仅包含声明的示例文件;即应提倡的例子: ```php Date: Mon, 9 Sep 2013 23:10:25 +0800 Subject: [PATCH 12/15] optimize PSR-2 --- accepted/zh_CN/PSR-2-coding-style-guide.md | 210 ++++++++++----------- 1 file changed, 105 insertions(+), 105 deletions(-) diff --git a/accepted/zh_CN/PSR-2-coding-style-guide.md b/accepted/zh_CN/PSR-2-coding-style-guide.md index 1ecaa5984..7a158a709 100644 --- a/accepted/zh_CN/PSR-2-coding-style-guide.md +++ b/accepted/zh_CN/PSR-2-coding-style-guide.md @@ -1,45 +1,45 @@ -代码样式规范 +代码风格指南 ================== -本手册是 [PSR-1][]基础代码规范的继承和扩展 +本手册是基础代码规范([PSR-1][])的继承和扩展。 -本指南的意图是为了减少不同开发者在浏览代码时减少认知的差异。 为此列举一组如何格式化PHP代码的共用规则。 +为了尽可能的提升阅读其他人代码时的效率,下面例举了一系列的通用规则,特别是有关于PHP代码风格的。 -各个成员项目的共性组成了本文的样式规则。当不同的开发者在不同的项目中合作时,将会在这些不同的项目中使用一个共同的标准。 因此,本指南的好处不在于规则本身,而在于共用这些规则。 +各个成员项目间的共性组成了这组代码规范。当开发者们在多个项目中合作时,本指南将会成为所有这些项目中共用的一组代码规范。 因此,本指南的益处不在于这些规则本身,而在于在所有项目中共用这些规则。 -在 [RFC 2119][]中的特性关键词"必须"(MUST),“不可”(MUST NOT),“必要”(REQUIRED),“将会”(SHALL),“不会”(SHALL NOT),“应当”(SHOULD),“不应”(SHOULD NOT),“推荐”(RECOMMENDED),“可以”(MAY)和“可选”(OPTIONAL)在这文档中将被用来描述。 +[RFC 2119][]中的`必须(MUST)`,`不可(MUST NOT)`,`建议(SHOULD)`,`不建议(SHOULD NOT)`,`可以/可能(MAY)`等关键词将在本节用来做一些解释性的描述。 [RFC 2119]: http://www.ietf.org/rfc/rfc2119.txt [PSR-0]: https://github.com/php-fig/fig-standards/blob/master/accepted/zh_CN/PSR-0.md [PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/zh_CN/PSR-1-basic-coding-standard.md -1. 大纲 +1. 概述 ----------- -- 代码必须遵守 [PSR-1][]。 +- 代码`必须`遵守 [PSR-1][]。 -- 代码`必须`使用4个空格的缩进,而不是制表符。 +- 代码`必须`使用4个空格来进行缩进,而不是用制表符。 -- 一行代码长度`不应`硬性限制;软限制`必须`为120个字符;也`应当`是80个字符或者更少。 +- 一行代码的长度`不建议`有硬限制;软限制`必须`为120个字符,`建议`每行代码80个字符或者更少。 -- 在`namespace`声明下面`必须`有一个空行,并且`use`声明代码块下面也`必须`有一个空行。 +- 在`命名空间(namespace)`的声明下面`必须`有一行空行,并且在`导入(use)`的声明下面也`必须`有一行空行。 -- 类的左花括号`必须`放到下一行,右花括号`必须`放在类主体的下一行。 +- `类(class)`的左花括号`必须`放到其声明下面自成一行,右花括号则`必须`放到类主体下面自成一行。 -- 方法的左花括号`必须`放在下一行,右花括号`必须`放在方法主体下面。 +- `方法(method)`的左花括号`必须`放到其声明下面自成一行,右花括号则`必须`放到方法主体的下一行。 -- 所有的属性和方法`必须`有可见性(译者注:Public, Protect, Private)声明;`abstract`和`final`声明`必须`在可见性之前;`static`声明`必须`在可见性之后。 +- 所有的`属性(property)`和`方法(method)` `必须`有可见性声明;`抽象(abstract)`和`终结(final)`声明`必须`在可见性声明之前;而`静态(static)`声明`必须`在可见性声明之后。 -- 控制结构的关键词`必须`在后面有一个空格; 方法和函数`不可`有。 +- 在控制结构关键字的后面`必须`有一个空格;而`方法(method)`和`函数(function)`的关键字的后面`不可`有空格。 -- 控制结构的左花括号`必须`放在同一行,右花括号`必须`放在控制主体的下一行。 +- 控制结构的左花括号`必须`跟其放在同一行,右花括号`必须`放在该控制结构代码主体的下一行。 -- 控制结构的左括号后面`不可`有空格,右括号之前`不可`有空格。 +- 控制结构的左括号之后`不可`有空格,右括号之前也`不可`有空格。 ### 1.1. 示例 -本示例包含上面的一些规则简单展示: +这个示例中简单展示了上文中提到的一些规则: ```php ``必须`省略 +纯PHP代码源文件的关闭标签`?>` `必须`省略。 ### 2.3. 行 行长度`不可`有硬限制。 -行长度的软限制`必须`是120个字符;对于软限制,自动样式检查器`必须`警告但`不可`报错。 +行长度的软限制`必须`是120个字符;对于软限制,代码风格检查器`必须`警告但`不可`报错。 -行实际长度`不应`超过80个字符;较长的行`应当`被拆分成多个不超过80个字符的后续行。 +一行代码的长度`不建议`超过80个字符;较长的行`建议`拆分成多个不超过80个字符的子行。 在非空行后面`不可`有空格。 -空行`可以`用来改善可读性和区分相关的代码块。 +空行`可以`用来增强可读性和区分相关代码块。 -一行`不应`多于一个语句。 +一行`不可`多于一个语句。 ### 2.4. 缩进 -代码`必须`使用4个空格的缩进,并且`不可`使用制表符作为缩进。 +代码`必须`使用4个空格,且`不可`使用制表符来作为缩进。 -> 注意:只用空格,不和制表符混合使用,将会对避免代码差异,补丁,历史和注解中的一些问题有帮助。使用空格还可以使调整细微的缩进来改进行间对齐变得非常简单。 +> 注意:代码中只使用空格,且不和制表符混合使用,将会对避免代码差异,补丁,历史和注解中的一些问题有帮助。空格的使用还可以使通过调整细微的缩进来改进行间对齐变得更加的简单。 -### 2.5. 关键词和 True/False/Null +### 2.5. 关键字和 True/False/Null -PHP [keywords][] `必须`使用小写。 +PHP关键字([keywords][])`必须`使用小写字母。 -PHP常量`true`, `false`和`null``必须`使用小写。 +PHP常量`true`, `false`和`null` `必须`使用小写字母。 [keywords]: http://php.net/manual/en/reserved.keywords.php -3. Namespace和Use声明 +3. `命名空间(Namespace)`和`导入(Use)`声明 --------------------------------- -如果存在,`namespace`声明之后`必须`有一个空行。 +`命名空间(namespace)`的声明后面`必须`有一行空行。 -如果存在,所有的`use`声明`必须`放在`namespace`声明的下面。 +所有的`导入(use)`声明`必须`放在`命名空间(namespace)`声明的下面。 -一个`use`关键字`必须`只用于一个声明。 +一句声明中,`必须`只有一个`导入(use)`关键字。 -在`use`声明代码块后面`必须`有一个空行。 +在`导入(use)`声明代码块后面`必须`有一行空行。 -示例: +示例: ```php bar($arg1); Foo::bar($arg2, $arg3); ``` -参数列表`可以`被拆分成多个有一个缩进的后续行。如果这么做,列表中的第一项必须放在下一行,并且每一行`必须`只有一个参数。 +参数列表`可以`被拆分成多个缩进了一次的子行。如果拆分成子行,列表中的第一项`必须`放在下一行,并且每一行`必须`只能有一个参数。 ```php bar( 5. 控制结构 --------------------- -对于控制结构的样式规则概括如下: +下面是对于控制结构代码风格的概括: -- 控制结构关键词之后`必须`有一个空格 -- 左括号之后`不可`有空格 -- 右括号之前`不可`有空格 -- 在右括号和左花括号之间`必须`有一个空格 -- 代码主体`必须`有一次缩进 -- 右花括号`必须`主体的下一行 +- 控制结构的关键词之后`必须`有一个空格。 +- 控制结构的左括号之后`不可`有空格。 +- 控制结构的右括号之前`不可`有空格。 +- 控制结构的右括号和左花括号之间`必须`有一个空格。 +- 控制结构的代码主体`必须`进行一次缩进。 +- 控制结构的右花括号`必须`主体的下一行。 -每个结构的主体`必须`被括在花括号里。这结构看上去更标准化,并且当加新行的时候可以减少引入错误的可能性。 +每个控制结构的代码主体`必须`被括在花括号里。这样可是使代码看上去更加标准化,并且加入新代码的时候还可以因此而减少引入错误的可能性。 ### 5.1. `if`,`elseif`,`else` -一个`if`结构看起来应该像下面这样。注意括号,空格,花括号的位置;并且`else`和`elseif`和前一个主体的右花括号在同一行。 +下面是一个`if`条件控制结构的示例,注意其中括号,空格和花括号的位置。同时注意`else`和`elseif`要和前一个条件控制结构的右花括号在同一行。 ```php $value) { ### 5.6. `try`, `catch` -一个`try catch`语句看起来应该像下面这样。注意括号,空格和花括号的位置。 +下面是一个`try catch`异常处理控制结构的示例,注意其中括号,空格和花括号的位置。 ```php bar( 7. 结论 -------------- -在该指南中有很多风格的元素和做法有意被忽略掉。这些包括但不局限于: +本指南有意的省略了许多元素的代码风格。主要包括: - 全局变量和全局常量的声明 -- 方法声明 +- 函数声明 - 操作符和赋值 @@ -535,16 +535,16 @@ $foo->bar( - 注释和文档块 -- 类名给你前缀和后缀 +- 类名的前缀和后缀 - 最佳实践 -以后的建议`可以`修改和扩展该指南以满足这些或其他风格的元素和实践。 +以后的代码规范中`可能`会修正或扩展本指南中规定的代码风格。 附录A 调查 ------------------ -为了写这个风格指南,我们采用了调查个项目以确定共同的做法。这个调查在这里供他人查看。 +为了写这个风格指南,我们调查了各个项目以最终确定通用的代码风格。并把这次调查在这里公布出来。 ### A.1. 调查数据 @@ -593,7 +593,7 @@ $foo->bar( 类常量如何命名?`upper` = 大写加下划线分隔符。 `true_false_null`: -全校写或者全大写? +全小写或者全大写? `method_names`: 方法名如何命名?`camel` = `驼峰式`, `lower_under` = 小写加下划线分隔符。 From e4f2f008bae1022033301cba154b58810e8ca86f Mon Sep 17 00:00:00 2001 From: thbourlove Date: Tue, 10 Sep 2013 09:58:34 +0800 Subject: [PATCH 13/15] optimize PSR-3 --- accepted/zh_CN/PSR-3-logger-interface.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/accepted/zh_CN/PSR-3-logger-interface.md b/accepted/zh_CN/PSR-3-logger-interface.md index 763d604e9..24f357b5f 100644 --- a/accepted/zh_CN/PSR-3-logger-interface.md +++ b/accepted/zh_CN/PSR-3-logger-interface.md @@ -1,15 +1,13 @@ 日志接口 ================ -本文档用来描述日志类库的通用接口。 +本文档描述了日志类库的通用接口。 -主要目标是让类库获得一个`Psr\Log\LoggerInterface`对象并能通过简单通用的方式来写日志。有自定义需求的框架和CMS`可以`根据情况扩展这个接口,但`应当`保持和该文档的兼容性,以确保应用中使用到的第三方库能将日志集中写到应用日志里。 +主要目标是让类库获得一个`Psr\Log\LoggerInterface`对象并能通过简单通用的方式来写日志。有自定义需求的框架和CMS`可以`根据情况扩展这个接口,但`推荐`保持和该文档的兼容性,以确保应用中使用到的第三方库能将日志集中写到应用日志里。 -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", -"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be -interpreted as described in [RFC 2119][]. +[RFC 2119][]中的`必须(MUST)`,`不可(MUST NOT)`,`建议(SHOULD)`,`不建议(SHOULD NOT)`,`可以/可能(MAY)`等关键词将在本节用来做一些解释性的描述。 -关键词`实现者`在这个文档被解释为:在日志相关的库或框架实现`LoggerInterface`接口的人。用这些实现的人都被称作`用户`。 +关键词`实现者`在这个文档被解释为:在日志相关的库或框架实现`LoggerInterface`接口的开发人员。用这些实现者开发出来的类库的人都被称作`用户`。 [RFC 2119]: http://tools.ietf.org/html/rfc2119 @@ -20,13 +18,13 @@ interpreted as described in [RFC 2119][]. - `LoggerInterface`暴露八个接口用来记录八个等级(debug, info, notice, warning, error, critical, alert, emergency)的日志。 -- 第九个方法是`log`,接受日志等级作为第一个参数。用一个日志等级常量来调用这个方法`必须`和直接调用指定等级方法的结果一致。用一个本规范中未定义且不为具体实现所知的日志等级来调用该方法`必须`抛出一个`Psr\Log\InvalidArgumentException`。用户确定某自定义日志等级被当前实现所支持前,`不应`使用它。 +- 第九个方法是`log`,接受日志等级作为第一个参数。用一个日志等级常量来调用这个方法`必须`和直接调用指定等级方法的结果一致。用一个本规范中未定义且不为具体实现所知的日志等级来调用该方法`必须`抛出一个`Psr\Log\InvalidArgumentException`。`不推荐`使用自定义的日志等级,除非你非常确定当前类库对其有所支持。 [RFC 5424]: http://tools.ietf.org/html/rfc5424 ### 1.2 消息 -- 每个方法都接受一个字符串,或者一个有`__toString`方法的对象作为`message`参数。`实现者``可以`对传入的对象有特殊的处理。如果没有,`实现者``必须`将它转换成字符串。 +- 每个方法都接受一个字符串,或者一个有`__toString`方法的对象作为`message`参数。`实现者` `可以`对传入的对象有特殊的处理。如果没有,`实现者` `必须`将它转换成字符串。 - `message`参数中`可能`包含一些`可以`被`context`参数的数值所替换的占位符。 @@ -36,7 +34,7 @@ interpreted as described in [RFC 2119][]. 占位符名字`应该`只能由`A-Z`,`a-z`,`0-9`,下划线`_`和句号`.`组成。其它的字符作为以后占位符规范的保留字。 - `实现者``可以`使用占位符来实现不同的转义和翻译日志成文。因为`用户`并不知道上下文数据会是什么,所以他们`不应`提前转义占位符。 + `实现者` `可以`使用占位符来实现不同的转义和翻译日志成文。因为`用户`并不知道上下文数据会是什么,所以`不推荐`提前转义占位符。 下面提供一个占位符替换的例子,仅作为参考: @@ -69,7 +67,7 @@ interpreted as described in [RFC 2119][]. ### 1.3 上下文 -- 每个方法接受一个数组作为`context`参数,用来存储不适合在字符串中填充的信息。数组可以包括任何东西。`实现者``必须`确保他们尽可能包容的对`context`参数进行处理。一个`context`参数的给定值`不可`导致抛出异常,也`不可`产生任何PHP错误,警告或者提醒。 +- 每个方法接受一个数组作为`context`参数,用来存储不适合在字符串中填充的信息。数组可以包括任何东西。`实现者` `必须`确保他们尽可能包容的对`context`参数进行处理。一个`context`参数的给定值`不可`导致抛出异常,也`不可`产生任何PHP错误,警告或者提醒。 - 如果在`context`参数中传入了一个`异常`对象,它必须以`exception`作为键名。记录异常轨迹是通用的模式,并且可以在日志系统支持的情况下从异常中提取出整个调用栈。`实现者`在将`exception`当做`异常`对象来使用之前`必须`去验证它是不是一个`异常`对象,因为它`可能`包含着任何东西。 From eff32ab0f55f0c5e34fc308d23cac9741b76eddc Mon Sep 17 00:00:00 2001 From: n3xtchen Date: Thu, 6 Mar 2014 23:23:03 +0800 Subject: [PATCH 14/15] add PSR-4 translate --- accepted/zh_CN/PSR-4-autoloader.md | 44 ++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 accepted/zh_CN/PSR-4-autoloader.md diff --git a/accepted/zh_CN/PSR-4-autoloader.md b/accepted/zh_CN/PSR-4-autoloader.md new file mode 100644 index 000000000..364582fa4 --- /dev/null +++ b/accepted/zh_CN/PSR-4-autoloader.md @@ -0,0 +1,44 @@ +### 1. 概况 + +这个 PSR 描述的是通过文件路径自动载入类的指南;它作为对 PSR-0 的补充;根据这个 +指导如何规范存放文件来自动载入; + +### 2. 说明(Specification) + +#### 1. 类是一个泛称;它包含类,结构,traits 以及其他类似的结构; + +#### 2. 完整的类名应该类似如下范例: + + \(\)*\ + ++ 每一个命名空间必须有一个顶级命名空间(Vendor Name); ++ 每一个命名空间都可以有多个子命名空间; ++ 每一个命名空间的分隔符都必须转化成 `DIRECTORY_SEPARATOR`,当它被文件系统载入时; ++ 每一个在类名中的 `_` 符号都会被转化成 `DIRECTORY_SEPARATOR`。而 `_` 符号在 +命名空间中没有任何意义; ++ 完整的的命名空间和类当从文件系统中被加载的时候,都会以 `.php` 为后缀; ++ Vendor 名,命名空间和类名中的英文字符可以是任意大小写的组合; + +#### 3. 当从完整的类名载入文件时: + +1. 一个连续的一个或多个主命名空间和子命名空间名称,不包括主命名空间分隔符, +在完全限定类名(一个“命名空间前缀”)必须对应于至少一个“基本目录”。 +2. 在“命名空间前缀”后的连续子命名空间名称对应的子目录中的“基本目录”,其中的命名 +空间分隔符表示目录分隔符;子目录名称必须匹配的子命名空间名称; +3. 最后的类名应该和 php 文件名匹配;文件名的大小写必须匹配; + +#### 4. 自动载入器的实现不能抛出任何异常,不能抛出任何等级的错误;也不能返回值; + +### 3. 范例 + +如下表格展示的是完整的类名与其中相关文件路径的关系: + +| 完整的类名 | 命名空间前缀 | 基础目录 | 实际的类文件路径 +| ----------------------------- |--------------------|--------------------------|------------------------------------------- +| \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php +| \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php +| \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php +| \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php + +例子中的自动载入器非常适应这个指南,请查阅 [examples file](http://www.php-fig.org/psr/psr-4/PSR-4-autoloader-examples.md) +;但是他不能作为指南的一部分;可能随时被改变; From 6757be83ba455eb43b1c778c27e32bf579f2bde2 Mon Sep 17 00:00:00 2001 From: hfcorriez Date: Wed, 16 Apr 2014 11:54:54 +0800 Subject: [PATCH 15/15] Fix and improve PSR-4 --- accepted/zh_CN/PSR-4-autoloader.md | 49 +++++++++++++++--------------- 1 file changed, 25 insertions(+), 24 deletions(-) diff --git a/accepted/zh_CN/PSR-4-autoloader.md b/accepted/zh_CN/PSR-4-autoloader.md index 364582fa4..20f560ca2 100644 --- a/accepted/zh_CN/PSR-4-autoloader.md +++ b/accepted/zh_CN/PSR-4-autoloader.md @@ -1,44 +1,45 @@ -### 1. 概况 +## 1. 概况 -这个 PSR 描述的是通过文件路径自动载入类的指南;它作为对 PSR-0 的补充;根据这个 +这个 PSR 描述的是通过文件路径[自动载入][]类的指南;它作为对 [PSR-0][] 的补充;根据这个 指导如何规范存放文件来自动载入; -### 2. 说明(Specification) +## 2. 说明(Specification) -#### 1. 类是一个泛称;它包含类,结构,traits 以及其他类似的结构; +1. 术语「类」是一个泛称;它包含类,接口,traits 以及其他类似的结构; -#### 2. 完整的类名应该类似如下范例: +2. 完全限定类名应该类似如下范例: \(\)*\ -+ 每一个命名空间必须有一个顶级命名空间(Vendor Name); -+ 每一个命名空间都可以有多个子命名空间; -+ 每一个命名空间的分隔符都必须转化成 `DIRECTORY_SEPARATOR`,当它被文件系统载入时; -+ 每一个在类名中的 `_` 符号都会被转化成 `DIRECTORY_SEPARATOR`。而 `_` 符号在 -命名空间中没有任何意义; -+ 完整的的命名空间和类当从文件系统中被加载的时候,都会以 `.php` 为后缀; -+ Vendor 名,命名空间和类名中的英文字符可以是任意大小写的组合; + 1. 完全限定类名必须有一个顶级命名空间(Vendor Name); + 2. 完全限定类名可以有多个子命名空间; + 3. 完全限定类名应该有一个终止类名; + 4. 下划线在完全限定类名中是没有特殊含义的; + 5. 字母在完全限定类名中可以是任何大小写的组合; + 6. 所有类名必须以大小写敏感的方式引用; -#### 3. 当从完整的类名载入文件时: +3. 当从完全限定类名载入文件时: -1. 一个连续的一个或多个主命名空间和子命名空间名称,不包括主命名空间分隔符, -在完全限定类名(一个“命名空间前缀”)必须对应于至少一个“基本目录”。 -2. 在“命名空间前缀”后的连续子命名空间名称对应的子目录中的“基本目录”,其中的命名 -空间分隔符表示目录分隔符;子目录名称必须匹配的子命名空间名称; -3. 最后的类名应该和 php 文件名匹配;文件名的大小写必须匹配; + 1. 在完全限定类名中,连续的一个或几个子命名空间构成的命名空间前缀(不包括顶级命名空间的分隔符),至少对应着至少一个基础目录。 + 2. 在「命名空间前缀」后的连续子命名空间名称对应一个「基础目录」下的子目录,其中的命名 +空间分隔符表示目录分隔符。子目录名称必须和子命名空间名大小写匹配; + 3. 终止类名对应一个以 `.php` 结尾的文件。文件名必须和终止类名大小写匹配; -#### 4. 自动载入器的实现不能抛出任何异常,不能抛出任何等级的错误;也不能返回值; +4. 自动载入器的实现不可抛出任何异常,不可引发任何等级的错误;也不应返回值; -### 3. 范例 +## 3. 范例 -如下表格展示的是完整的类名与其中相关文件路径的关系: +如下表格展示的是与完全限定类名、命名空间前缀和基础目录相对应的文件路径: -| 完整的类名 | 命名空间前缀 | 基础目录 | 实际的类文件路径 +| 完全限定类名 | 命名空间前缀 | 基础目录 | 实际的文件路径 | ----------------------------- |--------------------|--------------------------|------------------------------------------- | \Acme\Log\Writer\File_Writer | Acme\Log\Writer | ./acme-log-writer/lib/ | ./acme-log-writer/lib/File_Writer.php | \Aura\Web\Response\Status | Aura\Web | /path/to/aura-web/src/ | /path/to/aura-web/src/Response/Status.php | \Symfony\Core\Request | Symfony\Core | ./vendor/Symfony/Core/ | ./vendor/Symfony/Core/Request.php | \Zend\Acl | Zend | /usr/includes/Zend/ | /usr/includes/Zend/Acl.php -例子中的自动载入器非常适应这个指南,请查阅 [examples file](http://www.php-fig.org/psr/psr-4/PSR-4-autoloader-examples.md) -;但是他不能作为指南的一部分;可能随时被改变; +例子中的自动载入器非常适应这个指南,请参照 [示例文件][]。由于可能随时变更,实例不能作为指南的一部分。 + +[自动载入]: http://php.net/autoload +[PSR-0]: https://github.com/hfcorriez/fig-standards/tree/master/accepted/zh_CN/PSR-0.md +[示例文件]: http://www.php-fig.org/psr/psr-4/PSR-4-autoloader-examples.md