PSR-1: 基础编码规范

 阅读约 5 分钟

翻译:薛粲
授权许可: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. 概述

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

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

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

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

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

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

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

2. 文件

2.1 PHP 标记

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

2.2 字符编码

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

2.3 副作用

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

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

“副作用”包括但不限于:产生输出、明确的使用 requireinclude,连接外部服务、修改 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() 风格的命名。

阅读 1.4k发布于 2016-03-20
推荐阅读
粲言堂
用户专栏

6 人关注
6 篇文章
专栏主页
目录