php代码规范

:-}

优势

规范有以下优点:

高效编码 - 避免了过多的选择造成的『决策时间』浪费;
风格统一 - 最大程度统一了开发团队成员代码书写风格和思路,代码阅读起来如出一辙;
减少错误 - 减小初级工程师的犯错几率。

开发哲学

因为篇幅原因本规范无法涉及到项目里每一块代码的编写标准,所以此处重点说明下此规范遵循的『开发哲学』,开发中请把其当做指明灯,来指引你做决策:

DRY –「Don't Repeat Yourself」不写重复的逻辑代码;
约定俗成 - 「Convention Over Configuration」,优先选择框架提倡的做法,不过度配置;
KISS - 「Keep it Simple, Stupid」提倡简单易读的代码,不写高深、晦涩难懂的代码,不过度设计;
主厨精选 - 让有经验的人来为你选择方案,不独创方案;
官方提倡 - 优先选择官方推崇的方案。

设计理念

以下是一些优秀的『程序设计理念』:

MVC - Model, View, Controller ,以 MVC 为核心,严格控制 Controller 的可读性和代码行数;
Restful - 利用『资源化概念』和标准的 HTTP 动词来组织你的程序;

在此规范中,我们会将使用这两套理念作为程序设计基础。这些设计理念为我们设计程序提供了依据,遵循这些理念,能让程序变得清晰易读。

不要过于灵活

在开发中如果完成一个动作的实现方式过多,建议框架统一方式,易于其他人或多年后的自己阅读代码。

创建指定版本laravel

通过安装指定版本的laravel,让项目更加稳定和获得更长时间维护。

composer create-project laravel/laravel project-name --prefer-dist "5.5.*"

密钥存放

硬代码,直接写死。- ❌ 可维护性低
写死在 config/app.php 文件中。 - ❌ 无法区分环境进行配置
存储于 .env 文件中,使用 env() 方法直接读取。 - ❌ 虽然解决了环境变量问题但是不推荐
存储在 .env 和 config/app.php 文件中,然后使用 config() 函数来读取。- ✅ 最佳实践

这样做主要有以下几个优势:

定义分明,config() 是配置信息,env() 只是用来区分不同环境;
统一放置于 config 中还可以利用框架的 配置信息缓存功能 来提高运行效率;
代码健壮性, config() 在 env() 之上多出来一个抽象层,会使代码更加健壮,更加灵活。

readme.md 文档

「项目概述」- 介绍说明项目的一些情况,类似于简单的产品说明,简单的功能描述,项目相关链接等,500 字以内;
「运行环境」- 运行环境说明,系统要求等信息;
「开发环境部署/安装」- 一步一步引导说明,保证项目新成员能最快速的,没有歧义的部署好开发环境;
「服务器架构说明」- 最好能有服务器架构图,从用户浏览器请求开始,包括后端缓存服务使用等都描述清楚(主要体现为软件的使用),配合「运行环境」区块内容,可作为线上环境部署的依据;
「代码上线」- 介绍代码上线流程,需要执行哪些步骤;
「扩展包说明」- 表格列出所有使用的扩展包,还有在哪些业务逻辑或者用例中使用了此扩展包;
「自定义 Artisan 命令列表」- 以表格形式罗列出所有自定义的命令,说明用途,指出调用场景;
「队列列表」- 以表格形式罗列出项目所有队列接口,说明用途,指出调用场景。

代码风格

开发中用到最多的是psr-1和psr-2的开发规范,对其他psr规范有好奇心的可以自行学习。

PSR-1

类名

必须 遵循 StudlyCaps 大写开头的驼峰命名规范;

常量

所有字母都 必须 大写,单词间用下划线分隔;

方法

必须 符合 camelCase 式的小写开头驼峰命名规范。

PHP代码 必须 且只可使用 不带 BOM 的 UTF-8 编码。

类的属性

大写开头的驼峰式 ($StudlyCaps)
小写开头的驼峰式 ($camelCase)
下划线分隔式 ($under_score)

本规范不做强制要求,但无论遵循哪种命名方式,都 应该 在一定的范围内保持一致。这个范围可以是整个团队、整个包、整个类或整个方法。

PSR-2

概览

代码 必须 使用 4 个空格符而不是「Tab 键」进行缩进。

每行的字符数 应该 软性保持在 80 个之内,理论上 一定不可 多于 120 个,但 一定不可 有硬性限制。

每个 namespace 命名空间声明语句和 use 声明语句块后面,必须 插入一个空白行。

类的开始花括号({) 必须 写在函数声明后自成一行,结束花括号(})也 必须 写在函数主体后自成一行。

方法的开始花括号({) 必须 写在函数声明后自成一行,结束花括号(})也 必须 写在函数主体后自成一行。

类的属性和方法 必须 添加访问修饰符(private、protected 以及 public),abstract 以及 final 必须 声明在访问修饰符之前,而 static 必须 声明在访问修饰符之后。

控制结构的关键字后 必须 要有一个空格符,而调用方法或函数时则 一定不可 有。

控制结构的开始花括号({) 必须 写在声明的同一行,而结束花括号(}) 必须 写在主体后自成一行。
控制结构的开始左括号后和结束右括号前,都 一定不可 有空格符。

实例

<?php
namespace Vendor\Package;

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

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

    final public static function bar()
    {
        // 方法体
    }
}