thinkphp开发规范

一、编写目的

    为了更好的提升技术部的工做效率，保证开发的有效性和合理性，并可最大程度的提升程序代码的可读性和可重复利用性，指定此规范。开发团队根据本身的实际状况，能够对本规范进行补充或裁减。

---

一、程序员能够了解任何代码，弄清程序的情况； 
二、新人能够很快的适应环境； 
三、防止新接触PHP的人出于节省时间的须要，自创一套风格并养成终生的习惯； 
四、防止新接触PHP的人一次次的犯一样的错误； 
五、在一致的环境下，人们能够减小犯错的机会； 
六、程序员们有了一致的敌人；

 

二、总体要求

    技术部php开发规范将参照PEAR的规范，基本采用PEAR指定的规范，在其基础上增长、修改或删除部分适合具体开发环境的规范。本规范只针对PHP开发过程当中编码的规范，对于PHP开发项目中文件、目录、数据库等方面的规范，将不重点涉及。

    本规范包含了PHP开发时程序编码中命名规范、代码缩进规则、控制结构、函数调用、函数定义、注释、包含代码、PHP标记、文件头的注释块、CVS标记、URL样例、常量命名等方面的规则。

三、安全规范

    当咱们尝试编码时，不少时候不知道如何去让本身的代码变得安全一点，由于咱们缺少安全常识，安全常识的规范能够帮你杜绝一些平常的菜鸟黑客的攻击，却不能阻止骨灰级专家们的凌厉攻势，因此更高深的安全咱们还得从其余途径学习。

3.一、包含文件

    PHP文件的包含在经过PHP的函数引入文件时，因为传入的文件名没有通过合理的校验，从而操做了预想以外的文件，就可能致使意外的文件泄露甚至恶意的代码注入。

3.1.一、命名规则

    提取出来具备通用函数的包含文件，文件后缀以.inc来命名，代表这是一个包含文件。 
    若是有多个.inc文件须要包含多页面，请把全部.inc文件封装在一个文件里面，具体到页面只须要包换一个.inc文件就能够了。

    如：xxx_session.inc、xxx_comm.inc、xxx_setting.inf、myssql_db.inc。 
    把以上文件以如下方式，封装在xxx.basic.inc文件里面：

require_once('xxx_session.inc');
require_once('xxx_comm.inc');
require_once('xxx_setting.inc');
require_once('mysql_db.inc');

注意： 
是否须要封装到一个文件，视状况而定，若是每一个inc的功能是分散到不一样的页面使用的话，就不建议封装。

3.1.二、存放规则

    通常包含文件不须要直接暴露给用户，因此应该放在 Web Server 访问不到的目录，避免由于配置问题而泄露设置信息

 

3.二、安全规则

    请参考产品安全检查表。

输入和输出：

检查是否作了HTML代码的过滤 
可能出现的问题：若是有人输入恶意的HTML代码，会致使窃取cookie, 产生恶意登陆表单，和破坏网站。

检查变量作数据库操做以前是否作了escape 
可能出现的问题：若是一个要写入查询语句的字符串变量包含了某些特殊的字符，好比引号(',")或者分号(;) 可能形成执行了预期以外的操做。 

建议采用的方法：使用mysql_escape_string()或实现相似功能的函数。

检查输入数值的合法性 
可能出现的问题：异常的数值会形成问题。若是对输入的数值不作检查会形成不合法的或者错误的数据存入UDB、存入其它的数据库或者致使意料以外的程序操做发生。

举例：若是程序以用户输入的参数值作为文件名，进行文件操做，恶意输入系统文件名会形成系统损毁。

核实对cookie的使用以及对用户数据的处理 
可能出现的问题：不正确的cookie使用可能形成用户数据泄漏。

访问控制 
对内部使用的产品或者供合做方使用的产品，要考虑增长访问控制。

logs 
确保用户的保密信息没有记在log中(例如：用户的密码)； 
确保对关键的用户操做保存了完整的用户访问记录。

https 
对敏感数据的传输要采用https。

3.三、一些针对PHP的规则

    设置 register_globals = off; 
    设置 error_reporting = E_ALL，而且要修正全部的error和warning; 
    将实际的操做放在被引用的文件中。把引用文件放到不能够被直接浏览的目录下。

register_globals已自 PHP 5.3.0 起废弃并将自 PHP 5.4.0 起移除。

3.四、其它处理规则

    其它处理规则

3.4.一、输入参数处理

    页面接到参数须要SQL操做，这时候须要作转义，尤为须要注意“'”。

    如：

$a = ' Let’s go ' ;
$sql = "Insert into tmp(col) values('$a')";

这种状况出现错误的不肯定性。

3.4.二、操做大HTML文本

    不少时候须要存放一大段HTML文本供页面使用，象用户定制页头页脚等。 
    须要剔除脚本标记，避免执行恶意php代码。 
    转换“<”“>”号，保证代码完整HTML文本。

四、编码规范

    对代码文件及代码进行规范化。

4.一、命名规范

    制定统一的命名规范对于项目开发来讲很是重要，不但能够养成程序员一个良好的开发习惯，还能增长程序的可读性、可移植性和可重用性，还能很好的提升项目开发的效率。

1.普通变量

普通变量命名遵循如下规则： 
    a．全部字母都使用小写； 
    b．对于一个变量使用多个单词的，使用_做为每一个词的间隔。

例如：$base_dir、$red_rose_price等。

2.静态变量 
静态变量命名遵循如下规则： 
    a．静态变量使用小写的s_开头； 
    b．静态变量全部字母都使用小写； 
    c．多个单词组成的变量名使用_做为每一个词的间隔。

例子：$s_base_dir、$s_red_rose_prise等。

3.局部变量 
局部变量命名遵循如下规则： 
    a．全部字母使用小写； 
    b．变量使用_开头； 
    c．多个单词组成的局部变量名使用_做为每一个词间的间隔。

例子：$_base_dir、$_red_rose_price等。

4.全局变量 
全局变量应该带前缀G_且全部字母大写,知道一个变量的做用域是很是重要的。例如：

global $G_LOG_LEVEL;
global $G_LOG_PATH;

5.全局常量 
全局变量命名遵循如下规则： 
    a．全部字母使用大写； 
    b．全局变量多个单词间使用_做为间隔。 
例子：

define('BASE_DIR','/base/dir/');
define('RED_ROSE_PRICE',20.0);

6.session变量 
session变量命名遵循如下规则： 
    a．全部字母使用大写； 
    b．session变量名使用S_开头； 
    c．多个单词间使用_间隔。

例子：$S_BASE_DIR、$S_RED_ROSE_PRICE等。

4.1.二、类命名

PHP中类命名遵循如下规则： 
    a．以大写字母开头； 
    b．多个单词组成的变量名，单词之间不用间隔，各个单词首字母大写。

例子：class MyClass 或 class DbOracle等。

4.1.三、方法或函数

方法或函数命名遵循如下规则： 
    a．首字母小写； 
    b．多个单词间不使用间隔，除第一个单词外，其余单词首字母大写。

例子：function myFunction() 或 function myDbOracle()等。

4.1.四、缩写词

当变量名或者其余命名中遇到缩写词时，参照具体的命名规则，而不采用缩写词原来的所有大写的方式。

例子：function myPear（不是myPEAR） functio getHtmlSource（不是getHTMLSource）。

4.1.五、数据库表名

数据库表名命名遵循如下规范： 
    a．表名均使用小写字母； 
    b．对于普通数据表，使用_t结尾； 
    c．对于视图，使用_v结尾； 
    d．对于多个单词组成的表名，使用_间隔；

例子：user_info_t 和 book_store_v等。

4.1.六、数据库字段

数据库字段命名遵循如下规范： 
    a．所有使用小写； 
    b．多个单词间使用_间隔。

例子：user_name、rose_price等。

4.二、书写规则

书写规则是指在编写 PHP 程序时，代码书写的规则，包括缩进、结构控制等方面规范。

4.2.一、代码缩进

在书写代码的时候，必须注意代码的缩进规则，咱们规定代码缩进规则以下： 
    a．使用4个空格做为缩进，而不使用tab缩进（对于ultraedit，能够进行预先设置）。

例子：

for ( $i=0;$i<$count;$i++ ) {
    echo 'test';
}

4.2.二、大括号{}书写规则

在程序中进行结构控制代码编写，如if、for、while、switch等结构，大括号传统的有两种书写习惯，分别以下： 
    a．{ 直接跟在控制语句以后，不换行，如：

for ( $i=0;$i<$count;$i++ ) {
    echo 'test';
}

    b．{ 在控制语句下一行，如：

for ( $i=0;$<$count;$i++ )
{
    echo 'test';
}

    其中，a是PEAR建议的方式，可是从实际书写中来说，这并不影响程序的规范和影响用phpdoc实现文档，因此能够根据我的习惯来采用上面的两种方式，可是要求在同一个程序中，只使用其中一种，以避免形成阅读的不方便。

4.2.三、小括号()和函数、关键词等

小括号、关键词和函数遵循如下规则： 
    a．不要把小括号和关键词紧贴在一块儿，要用一个空格间隔；如if ( $a<$b )； 
    b．小括号和函数名间没有空格；如$test = date("ymdhis")； 
    c．除非必要，不要在Return返回语句中使用小括号。 如Return $a；

4.2.四、=符号书写

在程序中=符号的书写遵循如下规则： 
    a．在=符号的两侧，均需留出一个空格；如 $a = $b 、$a = 'test'等； 
    b．在=符号与!、=、<、>等符号相邻时，不需留一个空格；如 if ( $a == $b ) 、if ( $a != $b ) 等； 
    c．在一个申明块，或者实现一样功能的一个块中，要求=号尽可能上下对其，左边能够为了保持对齐使用多个空格，而右边要求空一个空格；以下例：

$testa   = $aaa;
$testaa  = $bbb;
$testaaa = $ccc;

4.2.五、if else swith for while等书写

对于控制结构的书写遵循如下规则： 
    a．在if条件判断中，若是用到常量判断条件，将常量放在等号或不等号的左边，例如：if ( 6 == $errorNum ) ,由于若是你在等式中漏了一个等号，语法检查器会为你报错，能够很快找到错误位置，这样的写法要注意； 
    b．switch结构中必需要有default块； 
    c．在 for 和 wiile 的循环使用中，要警戒 continue 、 break 的使用，避免产生相似 goto 的问题；

 

4.2.六、类的构造函数

若是要在类里面编写构造函数，必须遵循如下规则： 
    a．不能在构造函数中有太多实际操做，顶多用来初始化一些值和变量； 
    b．不能在构造函数中由于使用操做而返回false或者错误，由于在声明和实例化一个对象的时候，是不能返回错误的；

4.2.七、语句断行

在代码书写中，遵循如下原则： 
    a．尽可能保证程序语句一行就是一句，而不要让一行语句太长产生折行； 
    b．尽可能不要使一行的代码太长，通常控制在120个字符之内； 
    c．若是一行代码太长，请使用相似 .= 的方式断行书写； 
    d．对于执行数据库的sql语句操做，尽可能不要在函数内写sql语句，而先用变量定义sql语句，而后在执行操做的函数中调用定义的变量；

例子：

$sql = 'SELECT username,password,address,age,postcode FROM test_t ';
$sql .= ' WHERE username=\'aaa\'';
$res = mysql_query($sql);

4.2.八、数字

一个在源代码中使用了的赤裸裸的数字是难以想象的数字，由于包括做者，在三个月内，没人知道它的含义。例如：

if ( 22 == $foo ) {
    start_thermo_nuclear_war();
} elseif ( 19 == $foo){
    refund_lotso_money();
} else {
    cry_cause_in_lost();
}

你应该用define()来给你想表示某样东西的数值一个真正的名字，而不是采用赤裸裸的数字，例如：

define('PRESIDENT_WENT_CRAZY', '22');
define('WE_GOOFED', '19');
define('THEY_DIDNT_PAY', '16');

if ( PRESIDENT_WENT_CRAZY == $foo ) {
    start_thermo_nuclear_war();
} elseif ( WE_GOOFED == $foo){
    refund_lotso_money();
} elseif ( THEY_DIDNT_PAY == $foo ){
    infinite_loop();
} else {
    cry_cause_in_lost();
}

4.2.九、判断

遵循如下规则： 
    a．不能使用 1/0 代替 true/false，在 PHP 中，这是不相等的； 
    b．不要使用非零的表达式、变量或者方法直接进行 true/false 判断，而必须使用严格的完整 true/false 判断；

如：不使用 if ( $a ) 或者 if ( checka() ) 而使用 if ( FALSE != $a ) 或者 if ( FALSE != check() )。

4.2.十、避免嵌入赋值

在程序中避免下面例子中的嵌入式赋值： 
不使用这样的方式：

while ( $a != ( $c = getchar() ) ) {
    process the character
}

4.2.十一、错误返回检测规则

检查全部的系统调用的错误信息，除非你要忽略错误。

为每条系统错误消息定义好系统错误文本，并记录错误LOG。

4.三、程序注释

每一个程序均必须提供必要的注释，书写注释要求规范，参照PEAR提供的注释要求，为从此利用phpdoc生成 PHP 文档作准备。 
程序注释的原则以下： 
    a．注释中除了文件头的注释块外，其余地方都不使用//注释，而使用/* */的注释； 
    b．注释内容必须写在被注释对象的前面，不写在一行或者后面；

4.3.一、程序头注释块

每一个程序头部必须有统一的注释块，规则以下： 
    a．必须包含本程序的描述； 
    b．必须包含做者； 
    c．必须包含书写日期； 
    d．必须包含版本信息； 
    e．必须包含项目名称； 
    f．必须包含文件的名称； 
    g．重要的使用说明，如类的调用方法、注意事项等；

参考例子以下：

//
// +---------------------------------------------------------+
// | PHP version 4.0
// +---------------------------------------------------------+
// | Copyright (c) 1997-2001 The PHP Group
// +---------------------------------------------------------+
// | This source file is subject to of the PHP license,
// | that is bundled with this packafile LICENSE, and is
// | available at through the world-web at
// | http://www.php.net/license/2_02.txt.
// | If you did not receive a copy of the and are unable to
// | obtain it through the world-wide-web,end a note to
// | license@php.net so we can mail you a immediately.
// +---------------------------------------------------------+
// | Authors: Stig Bakken
// | Tomas V.V.Cox
//
// +———————————————————+
//
// $Id: Common.php,v 1.8.2.3 2001/11/13 01:26:48 ssb Exp $

4.3.二、类的注释

类的注释采用里面的参考例子方式：

/**
 * @ Purpose:
 * 访问数据库的类，以ODBC做为通用访问接口
 * @Package Name: Database
 * @Author: Forrest Gump gump@crtvu.edu.cn
 * @Modifications:
 * No20020523-100:
 * odbc_fetch_into()参数位置第二和第三个位置调换
 * John Johnson John@crtvu.edu.cn
 * @See: (参照)
 */

class Database {
    ...
}

4.3.三、函数和方法的注释

函数和方法的注释写在函数和方法的前面，采用相似下面例子的规则：

/**
 * @Purpose:
 * 执行一次查询
 * @Method Name: query()
 *
 * @Param: string $queryStr SQL查询字符串
 * @Param: string $username 用户名
 *
 * @Author: Michael Lee
 *
 * @Return: mixed 查询返回值（结果集对象）
 */
function query （ $queryStr, $username ） {
    ...
}

4.3.四、变量或者语句注释

程序中变量或者语句的注释遵循如下原则： 
    a．写在变量或者语句的前面一行，而不写在同行或者后面； 
    b．注释采用/* */的方式； 
    c．每一个函数前面要包含一个注释块。内容包括函数功能简述，输入/输出参数，预期的返回值，出错代码定义； 
    d．注释完整规范； 
    e．把已经注释掉的代码删除，或者注明这些已经注释掉的代码仍然保留在源码中的特殊缘由。

例子：

/**
 * @Purpose:
 * 数据库链接用户名
 * @Attribute/Variable Name: db_user_name
 * @Type: string
 */
var db_user_name;

4.四、其它规范

4.4.一、PHP代码标记

全部的PHP程序代码块标记均使用<?php ，不使用短标记<?。

4.4.二、程序文件名、目录名

程序文件名和目录名命名均采用有意义的英文方式命名，不使用拼音或无心义的字母，同时均必须使用小写字母，多个词间使用_间隔。

4.4.三、PHP项目一般的文件目录结构

建议在开发规范的独立的PHP项目时，使用规范的文件目录结构，这有助于提升项目的逻辑结构合理性，对应扩展和合做，以及团队开发均有好处。

一个完整独立的PHP项目一般的文件和目录结构以下： 
/ 项目根目录 
/manage 后台管理文件存放目录 
/css css文件存放目录 
/doc 存放项目文档 
/images 全部图片文件存放路径（在里面根据目录结构设立子目录） 
/scripts 客户端js脚本存放目录 
/tpl 网站全部html的模版文件存放目录 
/error.php 错误处理文件（能够定义到apache的错误处理中） 
以上目录结构是一般的目录结构，根据具体应用的具体状况，能够考虑不用彻底遵循，可是尽可能作到规范化。

4.4.四、PHP和HTML代码的分离问题

    对性能要求不是很高的项目和应用，咱们建议不采用 PHP 和 HTML 代码直接混排的方式书写代码，而采用 PHP 和 HTML 代码分离的方式，即采用模版的方式处理，这样一方面对程序逻辑结构更加清晰有利，也有助于开发过程当中人员的分工安排，同时还对往后项目的页面升级该版提供更多便利。

对于一些特殊状况，好比对性能要求很高的应用，能够不采用模版方式。

4.4.五、PHP项目开发中的程序逻辑结构

    对于 PHP 项目开发，尽可能采用 OOP 的思想开发，尤为在 PHP5 之后，对于面向对象的开发功能大大提升。

    在 PHP 项目中，咱们建议将独立的功能模块尽可能写成函数调用，对应一整块业务逻辑，咱们建议封装成类，既能够提升代码可读性，也能够提升代码重用性。好比，咱们一般将对数据库的接口封装成数据库类，有利于平台的移植。

    重复的代码要作成公共的库。（除了咱们在 plug-in 产品上遇到的状况，该产品系列有多个相相似的产品，为了尽量地减小安装包尺寸，不适合将这些产品共用的全部函数作成公共的库）

五、特定环境下PHP编码特殊规范

5.一、变量定义

    XXX环境下的 PHP 代码编写要求全部的变量均须要先申明后使用，不然会有错误信息，对于数组，在使用一个不肯定的 key 时，好比先进行 isset() 的判断，而后再使用；好比下面的代码：

$array ＝ array();
$var ＝ isset( $array[3] ) ? $array[3] : ''；

5.二、引用的使用

    引用在程序中使用比较多，为了公用同一个内存，而不须要另外进行复制，XXX环境下的引用使用时，须要注意下面的状况；

    在对函数的输入参数中使用引用时，不能在调用的时候在输入参数前加 & 来引用，而直接使用该变量便可，同时必须在函数定义的时候说明输入参数来自引用，好比下面的代码：

$a ＝ 1；
function ab( &$var ) {
    $var ++；
    return $var；
}
$b ＝ ab($a); // 注意，此处不能使用 $b ＝ ab(&$a)的方式；
echo $b."\n"；
echo $a."\n"；

此时 $a 和 $b 都是 2； 
XXX环境下对引用的特殊要求源自 php.ini 文件里面的 allow_call_time_pass_reference 项设置，对外公开的版本是 On，这样就能够支持&直接加到调用函数时变量前面进行引用，可是这一方法遭到抗议，并可能在未来版本的 PHP/Zend 里再也不支持。受到鼓励的指定哪些参数按引用传递的方法是在函数声明里。你被鼓励尝试关闭这一选项（使用off，XXX的全部运行环境下都是off）并确认你的脚本仍能正常工做，以保证在未来版本的语言里它们仍能工做。

5.三、变量的输入输出

    在XXX环境下，对 web 经过 GET 或者 POST 方法传递来的参数均要求进行严格的过滤和合法性验证，不推荐使用直接的$_GET 、 $_POST 或者 $_REQUEST 获取，而经过 XXX 的 XXX_yiv 模块提供的方法获取和过滤处理。