腾讯PHP开发规范v1.0

1引言
1.1定义及缩略语
缩略词 说明
海豹平台 运维中心提供的研发平台，提供框架、公共基础组件、公共业务组件加速业务的日常研发工作
1.2参考文档
海豹平台WIKI：http://wiki.seals.webdev.com/
1.3目的
本规范由编程原则组成，融合并提炼了开发人员长时间积累下来的成熟经验，意在帮助形成良好一致的编程风格。以达到事半功倍的效果，如果有需要本文档会不定期更新。
1.4适用范围
如无特殊说明，以下规则要求完全适用于基于海豹平台框架开发的应用，同时也可大部分适用于部门其他PHP项目。
1.5标准化作用
当一个软件项目尝试着遵守公共一致的标准时，可以使参与项目的开发人员更容易了解项目中的代码、弄清程序的状况。使新的参与者可以很快的适应环境，防止部分参与者出于节省时间的需要，自创一套风格并养成终生的习惯，导致其它人在阅读时浪费过多的时间和精力。而且在一致的环境下，也可以减少编码出错的机会。
缺陷是由于每个人的标准不同，所以需要一段时间来适应和改变自己的编码风格，暂时性的降底了工作效率。从使项目长远健康的发展以及后期更高的团队工作效率来考虑暂时的工作效率降低是值得的，也是必须要经过的一个过程。标准不是项目成功的关键，但可以帮助我们在团队协作中有更高的效率并且更加顺利的完成既定的任务。

1)程序员可以了解任何代码，弄清程序的状况
2)新人可以很快的适应环境
3)防止新接触PHP的开发出于节省时间的需要，自创一套风格并养成终生的习惯
4)防止新接触PHP的开发一次次的犯同样的错误
5)在一致的环境下，可以减少犯错的机会
2目录结构规范
2.1框架路径
框架引用路径必须采用绝对路径，托管的开发、测试和正式环境必须为：
/data/php/framework
2.2应用目录结构
应用需要严格参考以下目录安排代码位置：
webroot/
index.php Web 应用入口脚本文件
index-test.php 功能测试使用的入口脚本文件
assets/ 包含公开的资源文件
css/ 包含 CSS 文件
images/ 包含图片文件
themes/ 包含应用主题
protected/ 包含受保护的应用文件
modc 命令行脚本
modc.bat Windows 下的命令行脚本
modc.php 命令行 PHP 脚本
commands/ 包含自定义的 ‘modc’ 命令
components/ 包含可重用的用户组件
config/ 包含配置文件
controllers/ 包含控制器的类文件
SiteController.php 默认控制器的类文件
extensions/ 包含第三方扩展
messages/ 包含翻译过的消息(i8n相关)
models/ 包含模型的类文件
runtime/ 包含临时生成的文件
tests/ 包含测试脚本
views/ 包含控制器的视图和布局文件
layouts/ 包含布局视图文件
main.php 所有视图的默认布局
site/ 包含 ‘site’ 控制器的视图文件
system/ 包含系统视图文件

2.2.1配置config
存放应用配置目录，具体参考WIKI人口脚本
2.2.2控制器controllers
存放控制逻辑的类目录，具体参考WIKI控制器
2.2.3模型models
存放模型定义的类目录，具体参考WIKI模型
2.2.4视图views
存放视图文件的目录，具体目录参考WIKI视图
2.2.5国际化messages
存放国际化定义文件的目录
2.2.6组件components
存放组件的类目录，具体目录参考WIKI组件
2.2.7命令commands
存放Console命令的类目录，具体目录参考WIKI之Cli使用
2.2.8临时目录runtime
目录权限777，可用于存放临时生成的文件。
2.3路径别名
1)system: 表示平台框架目录，默认为/data/php/framework。
2)webroot: 表示入口脚本文件所在的目录，一般为应用的根目录。
3)application: 表示应用的基础目录，一般为webroot/protected。
4)ext: 表示包含了所有第三方扩展的目录，一般为webroot/protected/extensions。

通过使用 Mod::getPathOfAlias(), 别名可以被翻译为其相应的路径。例如：
system.core.web.CController 会被翻译为 /data/php/framework/core/web/CController。
2.3.1类型导入
使用别名可以很方便的导入类的定义，如导入webroot/protected/components/Controller

Mod::import(‘application.components.Controller’);

同样可以使用目录导入

Mod::import(‘application.components.*’);

3PHP编码规范
3.1标签
PHP程序可以使用<?php ?>或<?= ?>来界定 PHP 代码，在HTML页面中嵌入纯变量时，可以使用<?= ?>这样的形式，不可使用其他的标签变种。
纯PHP类文件，文件最后一个?>省略。
3.2编码
PHP代码必须只使用不带BOM的UTF-8。
3.3注释
1)单行注释：在语句结尾用双反斜杠”// “注释
2)多行注释：多行注视以”/”或“/**”符号开头，以”/ “符号作为注释结束符。

需要生成文档的注释必须是以“/”开头，以“*/”结尾。主流的IDE开发工具（如Eclipse，Zend）会用不同的颜色来区分下面的几种注释。
3.3.1文件注释
/
*（简述，用在索引列表中）
*

• 详细的功能描述（可略）
• @copyright Copyright© 2013, 公司名或作者名
• @author ${AUTHOR}
• @version $Id: ${FILE_NAME}, v ${VERSION} ${TIME} ${AUTHOR} Exp $

/
3.3.2类注释
/*
*（概要）
*

• 详细的功能描述
• @property 类型 $prop 属性描述
• @author ${AUTHOR}
• @package application.components（参见路径别名）

/
3.3.3方法注释
/*

• 功能描述
• @param 类型 $fields 描述
• @return 类型 描述
  */

3.3.4属性注释
/**

• @var 类型 KaTeX parse error: Unexpected character: '' at position 701: …)代替dataFile()。 ̲ 有时前缀名是有用的： …i = 0; $i < count; $i++) { … }

3.4.5常量名
量全部使用大写字母和下滑线组成,常量的名称中不允许出现小写字母，可使用分隔符作为下划线。
3.5书写规则
3.5.1文件
1)所有的PHP文件必须使用Unix LF(换行)作为行结束符。
2)所有PHP文件必须以一个空行结束。
3)纯PHP代码的文件关闭标签?>必须省略
3.5.2行
1)行长度不可有硬限制。
2)行实际长度不应超过80个字符；较长的行应当被拆分成多个不超过80个字符的后续行。
3)空行可以用来改善可读性和区分相关的代码块。
4)一行不应多于一个语句。
3.5.3缩进
每个缩进的单位约定是4个空格的缩进，并且不可使用制表符作为缩进，需每个参与项目的开发人员在编辑器(Eclipse、EditPlus、Zend Studio等)中进行强制设定将TAB转化为4个空格，以防在编写代码时遗忘而造成格式上的不规范。
3.5.4控制结构
对于控制结构的样式规则概括如下：
1)控制结构关键词之后必须有一个空格
2)左括号之后不可有空格
3)右括号之前不可有空格
4)在右括号和左花括号之间必须有一个空格
5)代码主体必须有一次缩进
6)右花括号必须主体的下一行
每个结构的主体必须被括在花括号里。这结构看上去更标准化，并且当加新行的时候可以减少引入错误的可能性。
3.5.4.1if,elseif, else
一个if结构看起来应该像下面这样。注意括号，空格，花括号的位置；并且else和elseif和前一个主体的右花括号在同一行。
//<?php
if ( $expr1) { // if body } elseif ($expr2) {
// elseif body
} else {
// else body;
}
关键词elseif应该替代else if使用以保持所有的控制关键词像一个单词。
3.5.4.2switch, case
一个switch结构看起来应该像下面这样。注意括号，空格和花括号。case语句必须从switch处缩进，并且break关键字（或其他中止关键字）必须和case主体缩进在同级。如果一个非空的case主体往下落空则必须有一个类似// 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;
}

3.5.4.3while, do while
一个while语句看起来应该像下面这样。注意括号，空格和花括号的位置。

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

同样的，一个do while语句看起来应该像下面这样。注意括号，空格和花括号的位置。

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

3.5.4.4for
一个for语句看起来应该像下面这样。注意括号，空格和花括号的位置。
//<?php
for ($i = 0; $i < 10; $i++) { // for body } 3.5.4.5foreach 一个foreach语句看起来应该像下面这样。注意括号，空格和花括号的位置。 //&lt;?php foreach ($iterable as $key => $value) {
// foreach body
}
3.5.4.6try, catch
一个try catch语句看起来应该像下面这样。注意括号，空格和花括号的位置。
//<?php
try {
// try body
} catch (FirstExceptionType $e) {
// catch body
} catch (OtherExceptionType $e) {
// catch body
}

3.5.5运算符
1)每个运算符与两边参与运算的值或表达式中间要有一个空格
3.5.6引号
在绝大多数可以使用单引号的场合，禁止使用双引号（性能考虑）。可以或必须使用单引号的情况包括但不限于下述：
1)字符串为固定值，不包含“\t”等特殊转义字符；
2)数组的固定下标，例如 $array[&#x27;key&#x27;]; 3)表达式中不需要带入变量，例如$string = ‘test’;，而非 $string = &quot;test$var";
3.5.7关键词
1)PHP keywords 必须使用小写。
2)PHP常量true, false和null必须使用小写。
3.5.8函数
3.5.9类
1)类必须单独一个源文件，并且类名和文件名相同。
2)类的左花括号必须放到下一行，右花括号必须放在类主体的下一行。
3)类文件“?>”结束标记去掉

//<?php
class Foo
{
[body]
}

4)一个类的extends和implements关键词必须和类名在同一行。

class ClassName extends ParentClass implements ArrayAccess, Countable
{
// constants, properties, methods
}

5)implements一个列表可以被拆分为多个有一次缩进的后续行。如果这么做，列表的第一项必须要放在下一行，并且每行必须只有一个接口。

class ClassName extends ParentClass implements
ArrayAccess,
Countable,
Serializable
{
// constants, properties, methods
}
3.5.10属性
1)所有的属性必须声明可见性。
2)var关键词不可用来声明属性。
3)一个语句不可声明多个属性。
4)属性名称可以使用单个下划线作为前缀来表明保护或私有的可见性。

class ClassName
{
public $foo = null;
private $_bar = 1;
}
3.5.11方法
1)所有的方法必须声明可见性。
2)方法名不应只使用单个下划线来表明是保护或私有的可见性。
3)方法名在声明之后不可跟随一个空格。左花括号必须放在下面自成一行，并且右花括号必须放在方法主体的下面自成一行。左括号后面不可有空格，右括号前面不可有空格。
4)一个方法定义看来应该像下面这样。 注意括号，逗号，空格和花括号：
5)在参数列表中，逗号之前不可有空格，逗号之后必须要有一个空格。
6)方法中有默认值的参数必须放在参数列表的最后面。

class ClassName
{
public function fooBarBaz(KaTeX parse error: Expected 'EOF', got '&' at position 7: arg1, &̲arg2, $arg3 = [])
{
// method body
}
}

7)参数列表可以被分为多个有一次缩进的多个后续行。如果这么做，列表的第一项必须放在下一行，并且每行必须只放一个参数。
8)当参数列表被分为多行，右括号和左花括号必须夹带一个空格放在一起自成一行。

class ClassName
{
public function aVeryLongMethodName(
ClassTypeHint KaTeX parse error: Expected 'EOF', got '&' at position 15: arg1, &̲arg2,
array $arg3 = []
) {
// method body
}
}

9)如果存在，abstract和final声明必须放在可见性声明前面。
10)如果存在，static声明必须跟着可见性声明。
4数据库命名规范
4.1命名规范
数据库的所有表(Table)、视图(View)、索引(Index)、触发器(Trigger)、函数(Function)和存储过程(Store Procedure)均应遵循以下命名规范。
1)命名统一用大写
2)命名只能由小写字母和数字构成，并且只能是以小写字母打头
3)命名应采用能够准确反映其中文含义的英文单词或英文单词缩写构成，避免出现英文单词和汉语拼音混用的局面
4)命名长度不可以超过25个字符（表名尽量保持在20个字符的长度，然后再其上建立索引、主键、触发器等等的时候，便于加扩展信息）
5)名称的各部分之间以"_"(下划线)连接
6)字段如有相同定义，应该用相同命名
7)命名应避免用关键字，参见附录一《关键字列表》
4.2实体命名
实体(包括库表、视图、函数和索引等)命名结构如下：
prefix[_module]_body[_suffix]
1)为前缀名，表示数据库对象的类型
2)为模块名，按应用模块进行分类，为可选项
3)为主体名，应该能够清楚地说明对象的含义
4)是后缀名，提供特效的含义，比如在该对象需分表存放时使用，如按月分开存放的表，为可选项。
4.2.1前缀命名
前缀 数据库对象
t 表(Table)
v 视图(View)
tri 触发器(Trigger)
p 存储过程(Procedure)
tt 临时表(Temporary Table)
idx 索引(Index)
uk 唯一索引（Unique Index）
pk 主键(Primary Key)
fk 外键(Foreign Key)
f 函数（Function）
4.2.2后缀命名
后缀 定义
_HIS 历史表
_LOG 流水表
_MAP 对照表
_REL 关系表
_YYYYMMDD 因数据量庞大，需按日分开存放的表
_YYYYMM 因数据量庞大，需按月分开存放的表
4.3字段命名
字段命名结构如下:
prefix_body[_suffix]
1)为前缀名，为必填项，必须为“f”。
2)为主体名，应该能够清楚地说明对象的含义
3)是后缀名，提供特效的含义，为可选项。

4.3.1后缀命名
以下是一些特别的后缀，代表了这个字段特效的含义。在其他的情况，应避免使用以下的后缀。
后缀 定义
_DESC 参数表内的描叙字段
一般来讲是VARCHAR(255)
_FLAG 只可能是True或False的字段
一般来讲是TINYINT(1)
_ID 标识字段，一般来讲是INT（11）
_TYPE 类型字段，一般来讲是CHAR(1)
4.4字段类型
一般来说， 在保证正确性的前提下，尽量使用最小的数据类型来存储和表示数据。 小的数据类型一般比大的更快，因为小的数据类型占用的磁盘空间， 内存和cup缓存都相对小，需要的cpu处理也要相对少; 这个原则很重要， 但是设计的时候也不要低估需要存储的数据的数据范围。
简单的数据类型需要的cup处理周期更少，比如：对整数的处理比字符串处理更容易， 因为字符集和排序规则使得字符串比较复杂化了， 两个典型例子是： 使用mysql的内嵌数据类型来存储日期和时间而不是字符串，使用整数存储Ip地址而不是字符串。
4.4.1数值类型
1)非万不得已不要使用DOUBLE，不仅仅只是存储长度的问题，同时还会存在精确性的问题。
2)固定精度的小数，也不建议使用DECIMAL，建议乘以固定倍数转换成整数存储，可以大大节省存储空间，且不会带来任何附加维护成本。
3)对于整数的存储，在数据量较大的情况下，建议区分开 TINYINT / INT / BIGINT 的选择，因为三者所占用的存储空间也有很大的差别，能确定不会使用负数的字段，建议添加unsigned定义。
4.4.2字符类型
1)非万不得已不要使用 TEXT 数据类型，其处理方式决定了他的性能要低于char或者是varchar类型的处理。
2)定长字段，建议使用 CHAR 类型，不定长字段尽量使用 VARCHAR，且仅仅设定适当的最大长度，而不是非常随意的给一个很大的最大长度限定，因为不同的长度范围，MySQL也会有不一样的存储处理。
4.4.3时间类型
1)尽量使用TIMESTAMP类型，因为其存储空间只需要 DATETIME 类型的一半。
2)对于只需要精确到某一天的数据类型，建议使用DATE类型，因为他的存储空间只需要3个字节，比TIMESTAMP还少。
3)不建议通过INT类型类存储一个unix timestamp 的值，因为这太不直观，会给维护带来不必要的麻烦，同时还不会带来任何好处。
4.4.4ENUM&SET
1)对于状态字段，可以尝试使用 ENUM 来存放，因为可以极大的降低存储空间。
2)如果是存放可预先定义的属性数据，可以尝试使用SET类型，即使存在多种属性，同样可以游刃有余，同时还可以节省不小的存储空间。
4.4.5LOB 类型
强烈反对在数据库中存放 LOB 类型数据
4.5表结构设计
4.5.1适度冗余
不需要一定遵守范式理论，适度的冗余，让Query尽量减少Join
4.5.2尽量使用NOT NULL
尽可能把字段定义成NOT NULL，许多表包含一些字段允许空的字段，即使应用需求不需要存储NULL的数据，因为允许字段为NULL是缺省的。
允许NULL的字段会占用掉更多的存储空间和花掉更多的cpu处理，当为一个可为空的字段建立索引时， 需要为每项分配一个额外的字节。即使遇到不需要存储值到某个字段，也应当考虑不使用NULL，而是考虑使用0，一个特殊值或者空串来代替。
4.5.3索引
1)唯一确定一条记录的一个字段或多个字段要建立主键或者唯一索引，不能唯一确定一条记录，为了提高查询效率建普通索引
2)对于取值不能重复，经常作为查询条件的字段，应该建唯一索引(主键默认唯一索引)，并且将查询条件中该字段的条件置于第一个位置。没有必要再建立与该字段有关的联合索引。
3)对于经常查询的字段，其值不唯一，也应该考虑建立普通索引，查询语句中该字段条件置于第一个位置，对联合索引处理的方法同样。
4)需要联合索引(或联合主键)的数据库要注意索引的顺序。SQL语句中的匹配条件也要跟索引的顺序保持一致。
5附件
5.1附录一：MYSQL保留字
ADD ALL ALTER ANALYZE AND AS ASC AUTO_INCREMENT BDB BEFORE BERKELEYDB BETWEEN BIGINT BINARY BLOB BOTH BTREE BY CASCADE CASE CHANGE CHAR CHARACTER CHECK COLLATE COLUMN COLUMNS CONSTRAINT CREATE CROSS CURRENT_DATE CURRENT_TIME CURRENT_TIMESTAMP DATABASE DATABASES DAY_HOUR DAY_MINUTE DAY_SECOND DEC DECIMAL DEFAULT DELAYED DELETE DESC DESCRIBE DISTINCT DISTINCTROW DIV DOUBLE DROP ELSE
ENCLOSED ERRORS ESCAPED EXISTS EXPLAIN FALSE FIELDS FLOAT FOR
FORCE FOREIGN FROM FULLTEXT FUNCTION GRANT GROUP HASH HAVING
HIGH_PRIORITY HOUR_MINUTE HOUR_SECOND IF IGNORE IN INDEX INFILE INNER
INNODB INSERT INT INTEGER INTERVAL INTO IS JOIN KEY KEYS KILL LEADING
LEFT LIKE LIMIT LINES LOAD LOCALTIME LOCALTIMESTAMP LOCK LONG
LONGBLOB LONGTEXT LOW_PRIORITY MASTER_SERVER_ID MATCH MEDIUMBLOB
MEDIUMINT MEDIUMTEXT MIDDLEINT MINUTE_SECOND MOD MRG_MYISAM
NATURAL NOT NULL NUMERIC ON OPTIMIZE
OPTION OPTIONALLY OR ORDER OUTER OUTFILE
PRECISION PRIMARY PRIVILEGES PROCEDURE PURGE READ
REAL REFERENCES REGEXP RENAME REPLACE REQUIRE
RESTRICT RETURNS REVOKE RIGHT RLIKE RTREE
SELECT SET SHOW SMALLINT SOME SONAME
SPATIAL SQL_BIG_RESULT SQL_CALC_FOUND_ROWS SQL_SMALL_RESULT SSL STARTING
STRAIGHT_JOIN STRIPED TABLE TABLES TERMINATED THEN
TINYBLOB TINYINT TINYTEXT TO TRAILING TRUE TYPES UNION UNIQUE
UNLOCK UNSIGNED UPDATE USAGE USE USER_RESOURCES
USING VALUES VARBINARY VARCHAR VARCHARACTER VARYING
WARNINGS WHEN WHERE WITH WRITE XOR YEAR_MONTH ZEROFILL