FIG-PHP PSR规范系列1-基础编码规范

原创: 2016-06-23 13:29:42 733浏览

1. FIG-PHP与PSR简介

FIG-PHP制定了一系列PHP开发规范，简称PSR，这里FIG是框架互操作工作组（Framework Interoperability Group）的简称，PSR是PHP标准推荐（PHP Standard Recommendation）的缩写。FIG-PHP工作组最初是源于项目代表讨论两个项目之间的共性时，找出可以共事的方式。主要的受众是双方项目组，但PHP界的其他人也在观望。如果其他人愿意采用这里的规范，那么欢迎，但这并非工作组的目标。工作组中没人会告诉你如何来建造应用。

截止到2015.07, PSR共有五个规范文档发布，分别是：

PSR-0 自动加载（2014.10.21被废弃，替代规范为PSR-4）

PSR-1 基础编码规范

PSR-2 编码风格

PSR-3 日志接口

PSR-4 改进的自动加载

PSR-7 HTTP消息接口

下面将分多个系列来学习这些规范, 本文档是系列1。

2. PSR-1: 基础编码规范

本规范讨论一些基础的代码规范，以便将来代码共享时不同代码之间能有更高程度的技术互操作。

本规范中的必须(MUST)，不可(MUST NOT)，应当(SHOULD)，不应当(SHOULD NOT)，可以/可能(MAY)等关键词的含义可参见RFC 2119。

2.1 概述

源文件必须（MUST）只使用

源文件中php代码的编码格式必须（MUST）只使用不带字节顺序标记(BOM)的UTF-8。备注：更多BOM资料可参见参考资料[BOM]。

一个源文件建议只用来做声明（类(class)，函数(function)，常量(constant)等）或者只用来做一些辅助作用的操作（例如：输出信息，修改.ini配置等）,但不应当（SHOULD NOT）同时做这两件事。

命名空间(namespace)和类(class) 必须遵循一种PSR自动加载规范: PSR-0或PSR-4。（译者注：由于PSR-0已经被废弃，因此这里事实上等同于必须遵循PSR-4规范。）

类名(class name) 必须使用StudlyCaps写法。

（译者注：参见参考资料[StudlyCaps]， StudlyCaps是一种大小写字母可任意变化，其中一些字母可被忽略的一种写法。例如消息可能隐藏在大写字母与小写字母中，例如"ShoEboX"大写字母可拼出"SEX", 小写祖母可拼出"hobo", webmail服务商Hotmail最初被写为HoTMaiL, 大写字母可拼出HTML。）

类(class)中的常量必须只由大写字母和下划线(_)组成。

方法名(method name) 必须使用camelCase（驼峰式)写法。

2.2 文件

2.2.1 PHP标签

PHP代码必须只使用长标签()或者短输出式标签(= ?>)；而不可使用其他标签。

2.2.2 字符编码

PHP代码的编码格式必须只使用不带字节顺序标记(BOM)的UTF-8。

2.2.3 辅助作用

一个源文件建议只用来做声明（类(class)，函数(function)，常量(constant)等）或者只用来做一些辅助作用的操作（例如：输出信息，修改.ini配置等）,但不建议同时做这两件事。

短语辅助作用(side effects)的意思是与声明（类(class)，函数(function)，常量(constant)等）没有直接关系的一些执行逻辑。

（译者注：[PSR-1-翻译1]中将side effects翻译为副作用，[PSR-1-翻译2]中翻译为从属效应 , 都感觉不知所云，这里翻译为辅助作用应当更好）。

（译者注：原文中的merely from including the file没有弄清楚是什么意思，留待以后确认）。

辅助作用包含但不局限于：产生输出，显式地使用require或include，连接外部服务，修改ini配置，触发错误或异常，修改全局或者静态变量，读取或修改文件等等。

下面是一个既包含声明又有辅助作用的示例文件；即应避免的例子：

\n";// 声明function foo(){    // 函数体}

下面是一个仅包含声明的示例文件；即应提倡的例子：

2.3 空间名(namespace)和类名(class name)
      命名空间(namespace)和类(class)必须遵循一种自动加载规范PSR-0或PSR-4.
      这意味着一个源文件中只能有一个类(class)，并且在命名空间中至少要有一级：即一个顶级的组织名(vendor name)。
     类名(class name) 必须使用StudlyCaps写法。
     PHP5.3之后的代码必须使用正式的命名空间(namespace) 
  例子：
  
  PHP5.2.x之前的代码建议用伪命名空间Vendor_作为类名(class name)的前缀
  
  2.4 类的常量、属性和方法
      术语类(class)指所有的类(class)，接口(interface)和trait。
  2.4.1 常量
      类常量必须（MUST）只由大写字母和下划线(_)组成。 例子：
  2.4.2 属性
      类的属性命名可以遵循$StulyCaps，$camelCase或者$under_score中的某一种风格，本规范不做强制要求，但无论遵循哪种命名方式，都应当（SHOULD）在一定的范围内保持一致。这个范围可以是整个团队、整个包、整个类或整个方法。
  2.4.3 方法
      方法名必须（MUST）使用camelCase风格来声明。
 3. 参考资料  
[BOM] 一个bom头引发的血案, 
  [PHP-FIG] php-fig, http://www.php-fig.org/
  [PSR-1-翻译1] PSR-1基本代码规范, https://github.com/hfcorriez/fig-standards/blob/zh_CN/%E6%8E%A5%E5%8F%97/PSR-1-basic-coding-standard.md
  [PSR-1-翻译2] PHP PSR-1 基本代码规范(中文版), http://segmentfault.com/a/1190000002521577
  [PSR-4] FIG-PHP PSR规范系列4-自动加载, 
  [RFC2119] Key words for use in RFCs to Indicate Requirement Levels, March 1997, http://www.ietf.org/rfc/rfc2119.txt
  [RFC2119-阮一峰] RFC2119：表示要求的动词, http://www.ruanyifeng.com/blog/2007/03/rfc2119.html 
  [StudlyCaps] Studly caps, https://en.wikipedia.org/wiki/Studly_caps