BeikeShop官方开发文档 | 安装教程 使用开发教程

# 编码风格

BeikeShop 遵循 PSR1(PSR-12) 编码规范 和PSR-4自动加载规范

# PSR1 基本编码规范

本篇规范制定了代码基本元素的相关标准，以确保共享的 PHP 代码间具有较高程度的技术互通性。

本文件中的 必须，不得，需要，应，不应，应该，不应该，推荐，可能 和 可选 等能愿动词按照 RFC 2119 (opens new window) 中的描述进行解释。

# 1. 概览

  • PHP代码文件 必须 以 <?php 或 <?= 标签开始；

  • PHP代码文件 必须 以 不带 BOM 的 UTF-8 编码；

  • PHP代码中 应该 声明任一标志（类、函数、常量等），或引起副作用（如果一个函数修改了自己范围之外的资源，那就叫做有副作用，如：生成输出以及修改 .ini 配置文件等），但是不应该二者都有；

  • 命名空间以及类 必须 符合 PSR 的自动加载规范： [PSR-0 (opens new window)（已废弃）或 PSR-4 (opens new window)] 中的一个。

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

  • 类中的常量所有字母都 必须 大写，单词间用下划线分隔；

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

# 2. 文件

# 2.1. PHP 标签

PHP 代码 必须 使用 <?php ?> 长标签 或 <?= ?> 短输出标签； 一定不可 使用其它自定义标签。

# 2.2. 字符集编码

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

# 2.3. 副作用

一份 PHP 文件中 应该 要不就只定义新的声明，如类、函数或常量等不产生 副作用 的操作，要不就只执行会产生 副作用 的逻辑操作，但 不该 同时具有两者。

「副作用」(side effects) 一词的意思是，仅仅通过包含文件，不直接声明类、函数和常量等，而执行的逻辑操作。

「副作用」包含却不仅限于：生成输出，明确使用require或include，连接到外部服务，修改ini设置，发出错误或异常，修改全局或静态变量，读取或写入一个文件，等等。

以下是一个 反例，一份包含「函数声明」以及产生「副作用」的代码：

<?php
// 「副作用」：修改 ini 配置
ini_set('error_reporting', E_ALL);

// 「副作用」：引入文件
include "file.php";

// 「副作用」：生成输出
echo "<html>\n";

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

下面是一个范例，一份只包含声明不产生「副作用」的代码：

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

// 条件声明 **不** 属于「副作用」
if (! function_exists('bar')) {
    function bar()
    {
        // 函数主体部分
    }
}

# 3. 命名空间和类名

命名空间和类名 必须 遵循『自动加载』规范： [PSR-0 (opens new window)， PSR-4 (opens new window)]。

这意味着每个类都独立为一个文件，并且至少在一个层次的命名空间内，那就是：顶级组织名（vendor name）。

类名 必须 以类似 StudlyCaps 形式的大写开头的驼峰命名方式声明。

PHP 5.3 及更高版本的代码 必须 使用正式的命名空间。

举个例子：

<?php
// PHP 5.3 及更高版本：
namespace Vendor\Model;

class Foo
{
}

PHP 5.2 及更低版本 应该 使用伪命名空间，约定俗成，以顶级组织名称 Vendor_ 为类名前缀：

<?php
// PHP 5.2.x 及更低版本：
class Vendor_Model_Foo
{
}

# 4. 类的常量、属性和方法

此处的「类」指代所有的类、接口以及可复用代码块（traits）。

# 4.1 常量

类的常量中所有字母都 必须 大写，词间以下划线分隔。例如：

<?php
namespace Vendor\Model;

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

# 4.2 属性

类的属性命名 可以 遵循：

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

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

# 4.3 方法

方法名称 必须 符合 camelCase() 式的小写开头驼峰命名规范。

# PSR-4 自动加载规范

为了避免歧义，文档大量使用了「能愿动词」，对应的解释如下：

  • 必须 (MUST)：绝对，严格遵循，请照做，无条件遵守；
  • 一定不可 (MUST NOT)：禁令，严令禁止；
  • 应该 (SHOULD) ：强烈建议这样做，但是不强求；
  • 不该 (SHOULD NOT)：强烈不建议这样做，但是不强求；
  • 可以 (MAY) 和 可选 (OPTIONAL) ：选择性高一点，在这个文档内，此词语使用较少；

参见：RFC 2119 (opens new window)

# 1. 总览

PSR-4 描述了从文件路径中 自动加载 (opens new window) 类的规范。 它拥有非常好的兼容性，并且可以在任何自动加载规范中使用，包括 PSR-0 (opens new window)。 PSR-4 规范也描述了放置 autoload 文件（就是我们经常引入的 vendor/autoload.php）的位置。

# 2. 规范

  1. 术语「class」指的是类（classes）、接口（interfaces）、特征（traits）和其他类似的结构。

  2. 全限定类名具有以下形式：

 \<NamespaceName>(\<SubNamespaceNames>)*\<ClassName>

  1. 全限定类名必须拥有一个顶级命名空间名称，也称为供应商命名空间（vendor namespace）。

  2. 全限定类名可以有一个或者多个子命名空间名称。

  3. 全限定类名必须有一个最终的类名（我想意思应该是你不能这样\<NamespaceName>(\<SubNamespaceNames>)*\来表示一个完整的类）。

  4. 下划线在全限定类名中没有任何特殊含义（在 PSR-0 (opens new window) 中下划是有含义的）。

  5. 全限定类名可以是任意大小写字母的组合。

  6. 所有类名的引用必须区分大小写。

  7. 全限定类名的加载过程

    1. 在全限定的类名（一个「命名空间前缀」）中，一个或多个前导命名空间和子命名空间组成的连续命名空间，不包括前导命名空间的分隔符，至少对应一个「根目录」。

    2. 「命名空间前缀」后面的相邻子命名空间与根目录下的目录名称相对应（且必须区分大小写），其中命名空间的分隔符表示目录分隔符。

    3. 最终的类名与以.php结尾的文件名保持一致，这个文件的名字必须和最终的类名相匹配（意思就是如果类名是FooController，那么这个类所在的文件名必须是FooController.php）。

  8. 自动加载文件禁止抛出异常，禁止出现任何级别的错误，也不建议有返回值。

# 3. 范例

下表显示了与给定的全限定类名、命名空间前缀和根目录相对应的文件的路径。

Fully Qualified Class Name Namespace Prefix Base Directory Resulting File Path
\Acme\Log\Writer\File_Writer Acme\Log\Writer ./acme-log-writer/lib/ ./acme-log-writer/lib/File_Writer.php
\Aura\Web\Response\Status Aura\Web /path/to/aura-web/src/ /path/to/aura-web/src/Response/Status.php
\Symfony\Core\Request Symfony\Core ./vendor/Symfony/Core/ ./vendor/Symfony/Core/Request.php
\Zend\Acl Zend /usr/includes/Zend/ /usr/includes/Zend/Acl.php

想要了解一个符合规范的自动加载器的实现可以查看示例文件 (opens new window)。示例中的自动加载器禁止被视为规范的一部分，它随时都可能发生改变。

← Laravel 目录结构 →