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

时间 2019-11-07

标签 fig php psr 规范系列基础编码栏目 PHP 繁體版

原文原文链接

1. FIG-PHP与PSR简介

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

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

PSR-0 自动加载（2014.10.21被废弃，替代规范为PSR-4）git
PSR-1 基础编码规范github
PSR-2 编码风格web
PSR-3 日志接口segmentfault
PSR-4 改进的自动加载框架
PSR-7 HTTP消息接口ide

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

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

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

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

2.1 概述

源文件必须（MUST）只使用 <?php 和 <?= 这两种标签。
源文件中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代码必须只使用长标签(<?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配置，触发错误或异常，修改全局或者静态变量，读取或修改文件等等。

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

<?php
// 辅助做用：修改了ini配置
ini_set('error_reporting', E_ALL);

// 辅助做用：载入了文件
include "file.php";

// 辅助做用：产生了输出
echo "<html>\n";

// 声明
function foo()
{
    // 函数体
}

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

<?php
// 声明
function foo()
{
    // 函数体
}

// 条件式声明不算作是辅助做用
if (! function_exists('bar')) {
    function bar()
    {
        // 函数体
    }
}

2.3 空间名(namespace)和类名(class name)

命名空间(namespace)和类(class)必须遵循一种自动加载规范PSR-0或PSR-4.

这意味着一个源文件中只能有一个类(class)，而且在命名空间中至少要有一级：即一个顶级的组织名(vendor name)。

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

PHP5.3以后的代码必须使用正式的命名空间(namespace)

例子：

<?php
// PHP 5.3 及以后:
namespace Vendor\Model;

class Foo
{
}

PHP5.2.x以前的代码建议用伪命名空间Vendor_做为类名(class name)的前缀

<?php
// PHP 5.2.x 及以前:
class Vendor_Model_Foo
{
}

2.4 类的常量、属性和方法

术语类(class)指全部的类(class)，接口(interface)和trait。

2.4.1 常量

类常量必须（MUST）只由大写字母和下划线(_)组成。例子：

<?php
namespace Vendor\Model;

class Foo
{
    const VERSION = '1.0';
    const DATE_APPROVED = '2012-06-01';
}

2.4.2 属性

类的属性命名能够遵循$StulyCaps，$camelCase或者$under_score中的某一种风格，本规范不作强制要求，但不管遵循哪一种命名方式，都应当（SHOULD）在必定的范围内保持一致。这个范围能够是整个团队、整个包、整个类或整个方法。

2.4.3 方法

方法名必须（MUST）使用camelCase风格来声明。

3. 参考资料

[BOM] 一个bom头引起的血案, http://blog.csdn.net/ohmygirl/article/details/6931716

[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-自动加载, http://my.oschina.net/1pei/blog/485099

[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