基础编码规范 (Basic Coding Standard)

翻译：薛粲
授权许可：CC BY-NC 4.0

这份文档是《PSR-1: Basic Coding Standard》的非官方译文。

这份标准文档阐述了那些需要考虑的标准的编写代码的原则，用于确保在共享 PHP 代码时技术上具备较高层次的互操作性。

英文原文使用的关键词 "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 以及 "OPTIONAL" 遵循 RFC 2119 的描述。译文中根据上下文可能会使用不同的词汇来对应这些关键词，并加粗显示。

  1. 概述
  2. 文件
  3. 命名空间和类名
  4. 类常量、属性和方法

1. 概述

  • 文件必须只用 <?php 或 <?= 标记。

  • PHP 源代码文件必须只用不带 BOM 的 UTF-8 编码。

  • 一个文件应该或者用于声明各种符号（类、函数、常量等），或者发生作用（例如产生输出、修改 .ini 设置等）但不应该同时做上述两件事情。

  • 命名空间和类必须遵循一条关于自动加载的 PSR，即 PSR-0 或 PSR-4。

  • 类名必须声明为 StudlyCaps 样式。

  • 类常量必须全部使用大写字母和下划线进行声明。

  • 方法名必须声明为 camelCase 样式。.

2. 文件

2.1 PHP 标记

PHP 代码必须使用长的 <?php ?> 标记或者短的用于输出的 <?= ?> 标记；不得使用其它种类的标记。

2.2 字符编码

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

2.3 副作用

一个文件应该是：或者用于声明新的符号（类、函数、常量等）的，同时并不导致其它副作用；或者用于执行一些会产生副作用的逻辑。但是，一个文件不应该既声明新的符号，又执行产生副作用的逻辑。

短语“副作用”在这里指的是执行那些不直接与声明类、函数、常量等相关的逻辑，merely from including the file.

“副作用”包括但不限于：产生输出、明确的使用 require 或 include，连接外部服务、修改 ini 设置、抛出错误或异常、修改全局或静态变量以及读写文件等。

下面的示例既包含了声明又执行了产生副作用的逻辑，换句话说，这里例子是应该避免的：


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

// 副作用：加载文件
include "file.php";

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

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

下面的示例只包含声明而没有产生副作用，也就是说是可以借鉴的例子：


<?php
// 声明
function foo()
{
    // function body
}

// 条件声明*不是*副作用
if (! function_exists('bar')) {
    function bar()
    {
        // function body
    }
}

3. 命名空间和类名

命名空间和类必须遵循一份自动加载 PSR 规范：PSR-0 或 PSR-4。

这意味着每个类在一个只属于它自己的文件中，并且至少在一层命名空间——即最顶层的提供商名——之中。

类名必须声明为 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. 类常量、属性和方法

术语“类”在这里涵盖了类、接口和 trait。

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() 风格的命名。

收藏 0 点赞 0
0 条评论