PHP代码规范-PHP编码规范

通则

基本编码准则

代码必须符合 PSR-1 中的所有规范。

文件格式

源文件

  • 顶部使用标签<?php,必须省略最后的?> 结束标签。(为了防止多余空格或者其他字符影响到代码。)
  • 编码格式必须UTF-8格式。
  • 注释说明文件类型,文件名称。
  • 目录不强制规范,驼峰和小写+下划线模式均支持。
  • 程序文件名和目录名均采用有意义的英文命名,不使用拼音或无意义的字母,只允许出现字母、数字、下划线和中划线字符,同时必须以“.php”结尾(模板文件除外)
  • 所有PHP文件必须以一个空白行作为结束。
  • 不建议使用短标签。(使用短标签容易和XML混淆,并且不是所有PHP版本和服务器都默认支持或打开短标签选项。)

例子:

//类统一采用
DemoTest.class.php
//接口统一采用
DemoTest.interface.php
//其他格式
demoTest.{style}.php

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static functionbar()
    {
        // method body
    }
}     

缩进

  • 代码必须使用4个空格符的缩进,一定不能用 tab键 。

备注: 使用空格而不是tab键缩进的好处在于, 避免在比较代码差异、打补丁、重阅代码以及注释时产生混淆。 并且,使用空格缩进,让对齐变得更方便。

  • 行的长度一定不能有硬性的约束。
  • 软性的长度约束一定要限制在120个字符以内,若超过此长度,带代码规范检查的编辑器一定要发出警告,不过一定不可发出错误提示。
  • 每行不应该多于80个字符,大于80字符的行应该折成多行。
  • 非空行后一定不能有多余的空格符。
  • 空行可以使得阅读代码更加方便以及有助于代码的分块。
  • 每行一定不能存在多于一条语句。

文件目录结构

根据具体情况考虑目录结构,不用完全遵循,但是要尽量做到规范化

├─ app //独立的应用
├─ class //单个类文件,共用的类文件(比如工具类)
├─ conf/inc //配置文件目录
├─ data //数据文件目录
├─ doc //程序相关文档
├─ htdocs/document_root
├─ images //所有图片文件存放路径(在里面根据目录结构设立子目录)
├─ css //CSS文件
├─ js //javascript 脚本文件
├─ lib //共用类库
├─ template //模板文件
├─ temp //临时文件 目录
    ├─ cache  
    ├─ session
    ├─ template_c
    ├─ other
├─ upload //上传文件(按照特定的规则分目录存放)
├─ manager //后台管理文件存放目录

编码格式

遵循PSR-2命名规范和PSR-4自动加载规范,并且注意如下规范: 目录、类库、函数文件应该统一以 “.php”为后缀

变量

变量命名规范

PHP中的变量用一个美元符号后面跟变量名表示。变量名区分大小写。 一个有效的变量名由字母或者下划线开关,后面跟任意数量的字母、数字、下划线。

  • 普通变量整体采用驼峰法,建议再变量前加表示类型的前缀。
  • 不确定类型以答谢字母开头,函数参数不确定的类型以大写字母开头,其他地方的变量以小写字母开头。

例如:

//普通便利
$name;
$shoesTime;

$sMyName //字符串
$arrMyArray //数组
$oMyObject //对象
$resource //资源

函数名

采用动词或者动词加形容词命名方式

例如:

$showMsg

类、属性、方法和命名空间

此处的“类”泛指所有的class类、接口以及traits可复用代码块。

类、接口和继承命名

  • 以大写字母开头。
  • 多个单词组成的变量名,单词之间不用间隔,各个单词首字母大写。
  • 类名与类文件保持一致。
  • 程序中所有类名唯一。
  • 抽象类应以Abstract开头。
  • 关键词 extends 和 implements必须写在类名称的同一行。
  • 类的开始花括号必须独占一行,结束花括号也必须在类主体后独占一行。

例如:

ClassName.class.php //类名

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // constants, properties, methods
}
接口命名规则
  • 采取和类相同的命名规则,但在其命名前加i字符,表示接口。 例如:IDataBase.
  • 尽量保持和实现它的类命名一致。 例如:iDatabase.interface.php
继承
  • implements 的继承列表也可以分成多行,这样的话,每个继承接口名称都必须分开独立成行,包括第一个。

例如:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

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

属性

  1. 每个属性都必须添加访问修饰符。
  2. 一定不可使用关键字 var 声明一个属性。
  3. 每条语句一定不可定义超过一个属性。
  4. 属性的命名使用驼峰法,并且首字母小写。

例如:

<?php
//主键名
protected $pk = 'dashboard_id';

// 设置当前模型对应的完整数据表名称
protected $table = 'map_dashboard';

// 设置字段信息
protected $schema = [
];
  1. 不要使用下划线作为前缀,来区分属性是 protected 或 private

以下是属性声明的一个范例:

<?php
namespace Vendor\Package;

classClassName
{
    public $foo = null;
}

方法

  1. 所有方法都必须添加访问修饰符。
  2. 不要使用下划线作为前缀,来区分方法是 protected 或 private
  3. 方法名称后一定不能有空格符,其开始花括号必须独占一行,结束花括号也必须在方法主体后单独成一行。参数左括号后和右括号前一定不能有空格。
  4. 一个标准的方法声明可参照以下范例,留意其括号、逗号、空格以及花括号的位置。

例如:

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}
  1. 方法命名方式:
  • 类的命名: (首字母大写)模块+Controller
  • 模型命名: (首字母大写)模块+Model
  • Serivce命名: (首字母大写)模块+Serivce
  • Logic命名: (首字母大写)相关功能+Logic
  • 方法命名: 关键字+操作对象
  1. 关键字:
  • 显示创建资源:create
  • 保存新建的资源:save
  • 显示指定的资源:read
  • 显示编辑资源:edit
  • 保存更新的资源:update
  • 删除指定资源:delete

例如:

创建用户:createUser
更新用户资料:updateUserinfo

方法的参数

  1. 参数列表中,每个参数后面必须要有一个空格,而前面一定不能有空格。
  2. 有默认值的参数,必须放到参数列表的末尾。

例如:

<?php
namespace Vendor\Package;

class ClassName
{
    public functionfoo($arg1, &$arg2, $arg3 = [])
    {
        // method body
    }
}
  1. 参数列表可以分列成多行,这样,包括第一个参数在内的每个参数都必须单独成行。
  2. 拆分成多行的参数列表后,结束括号以及方法开始花括号 必须 写在同一行,中间用一个空格分隔。

例如:

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName( ClassTypeHint $arg1, &$arg2, array $arg3 = [] )
    {
        // method body
    }
}

方法及函数调用

  1. 方法及函数调用时,方法名或函数名与参数左括号之间一定不能有空格,参数右括号前也 一定不能有空格。 每个参数前一定不能有空格,但其后必须有一个空格。

例如:

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);
  1. 参数可以分列成多行,此时包括第一个参数在内的每个参数都必须单独成行。

例如:

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

abstract 、final 、以及static

需要添加 abstract 或 final 声明时, 必须写在访问修饰符前,而 static 则必须写在其后。

例如:

<?php
namespace Vendor\Package;

abstract class ClassName
{
protected static $foo;

    abstract protected functionzim();

    final public static functionbar()
    {
        // method body
    }
}

关键字以及True/False/Null

  1. PHP所有关键字必须全部小写。
  2. 常量 true 、false 和 null 也必须全部小写。

namespace 以及 use 声明

  1. namespace 声明后 必须 插入一个空白行。
  2. 所有 use 必须 在 namespace 后声明。
  3. 每条 use 声明语句 必须 只有一个 use 关键词。
  4. use 声明语句块后 必须 要有一个空白行。

例如:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// ... additional PHP code ...

控制结构

控制结构的基本规范如下:

  • 控制结构关键词后必须有一个空格。
  • 左括号 ( 后一定不能有空格。
  • 右括号 ) 前也一定不能有空格。
  • 右括号 ) 与开始花括号 { 间一定有一个空格。
  • 结构体主体一定要有一次缩进。
  • 结束花括号 } 一定在结构体主体后单独成行。

每个结构体的主体都必须被包含在成对的花括号之中, 这能让结构体更加结构话,以及减少加入新行时,出错的可能性。

1、if 、 elseif 和 else

  1. 标准的 if 结构如下代码所示,留意 括号、空格以及花括号的位置, 注意 else 和 elseif 都与前面的结束花括号在同一行。

例如:

<?php
if ($expr1) {
    // if body
} elseif ($expr2) {
    // elseif body
} else {
    // else body;
}
  1. 应该使用关键词 elseif 代替所有 else if ,以使得所有的控制关键字都像是单独的一个词。

2、switch 和 case

标准的 switch 结构如下代码所示,留意括号、空格以及花括号的位置。 case 语句必须相对 switch 进行一次缩进,而 break 语句以及 case 内的其它语句都必须相对 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、whiledo while

  1. 一个规范的 while 语句应该如下所示,注意其 括号、空格以及花括号的位置。

例如:

<?php
while ($expr) {
    // structure body
}
  1. 标准的 do while 语句如下所示,同样的,注意其 括号、空格以及花括号的位置。

例如:

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

4、for

  1. 标准的 for 语句如下所示,注意其 括号、空格以及花括号的位置。

例如:

<?php
for ($i = 0; $i < 10; $i++) {
    // for body
}

5、foreach

  1. 标准的 foreach 语句如下所示,注意其 括号、空格以及花括号的位置。

例如:

<?php
foreach ($iterable as $key => $value) {
    // foreach body
}

6、trycatch

  1. 标准的 try catch 语句如下所示,注意其 括号、空格以及花括号的位置。

例如:

<?php
try {
    // try body
} catch (FirstExceptionType $e) {
    // catch body
} catch (OtherExceptionType $e) {
    // catch body
}

闭包

  1. 闭包声明时,关键词 function 后以及关键词 use 的前后都必须要有一个空格。
  2. 开始花括号必须写在声明的同一行,结束花括号必须紧跟主体结束的下一行。
  3. 参数列表和变量列表的左括号后以及右括号前,必须不能有空格。
  4. 参数和变量列表中,逗号前必须不能有空格,而逗号后必须要有空格。
  5. 闭包中有默认值的参数必须放到列表的后面。
  6. 标准的闭包声明语句如下所示,注意其 括号、逗号、空格以及花括号的位置。

例如:

<?php
$closureWithArgs = function($arg1, $arg2){
    // body
};

$closureWithArgsAndVars = function($arg1, $arg2)use($var1, $var2){
    // body
};
  1. 参数列表以及变量列表可以分成多行,这样,包括第一个在内的每个参数或变量都必须单独成行, 而列表的右括号与闭包的开始花括号必须放在同一行。

以下几个例子,包含了参数和变量列表被分成多行的多情况。

<?php
$longArgs_noVars = function( $longArgument, $longerArgument, $muchLongerArgument ){
   // body
};

$noArgs_longVars = function()use( $longVar1, $longerVar2, $muchLongerVar3 ){
   // body
};

$longArgs_longVars = function( $longArgument, $longerArgument, $muchLongerArgument )use( $longVar1, $longerVar2, $muchLongerVar3 ){
   // body
};

$longArgs_shortVars = function( $longArgument, $longerArgument, $muchLongerArgument )use($var1){
   // body
};

$shortArgs_longVars = function($arg)use( $longVar1, $longerVar2, $muchLongerVar3 ){
   // body
};

注意,闭包被直接用作函数或方法调用的参数时,以上规则仍然适用。

例如:

<?php
$foo->bar(
    $arg1,
    function($arg2)use($var1){
        // body
    },
    $arg3
);

总结

以上规范难免有疏忽,其中包括但不仅限于:

  • 全局变量和常量的定义
  • 函数的定义
  • 操作符和赋值
  • 行内对齐
  • 注释和文档描述块
  • 类名的前缀及后缀
  • 最佳实践

常量和配置.

  1. 常量以大写字母和下划线命名,例如 APP_PATH和 THINK_PATH;
  2. 配置参数以小写字母和下划线命名,例如 url_route_on 和url_convert;

数据表和字段.

  1. 数据表和字段采用小写加下划线方式命名,并注意字段名不要以下划线开头,例如 think_user 表和 user_name字段,不建议使用驼峰和中文作为数据表字段命名。

习惯于约定

缩写

例如:

    Image-> img
    string->str
    database->db
    array->arr
    count->cnt
    temporary->temp或者tmp
    password->passwd或者pwd
    message->msg

上一篇
下一篇