PSR-1 Basic Coding Standard(译)-- 基础编码规范

注:本文算是笔者对PSR规范翻译/学习笔记，之后会陆续翻译剩余的规范，可能翻译的有错误的地方，希望读者能够指正，非常感谢.

什么是PSR？

PSR是PHP Standards Recommendations(PHP标准建议) 的简写，是由PHP-FIG组织(PHP Framework Interop Group-PHP框架交互操作组织)提出。PHP-FIG的工作是寻找项目之间的共性，以及让开发者能更好协同工作的方式。读者可能在浏览一些PHP技术文章的时候，可能会看到PSR-1,PSR-2,PSR-4,PSR-7等，这些是PHP-FIG的标准建议，这些标准建议的命名构成是以'PSR-'+'序号'，每个PHP_FIG标准建议都是为了解决大部分框架频繁遇到的一个特定的问题，而与此同时框架不需要自己再去重复解决问题,而是遵循PSR标准建议，采纳共享的解决方案.

目前PSR规范有哪些?

PSR规范

PSR-1: Basic Coding Standard
PSR-2: Coding Style Guide
PSR-3: Logger Interface
PSR-4: Autoloader
PSR-6: Caching Interface
PSR-7: HTTP message interfaces
PSR-11: Container interface
PSR-13: Link definition interfaces
PSR-16: Common Interface for Caching Libraries

什么是 PSR-1?

原文链接:PSR-1 Basic Coding Standard

Aims to ensure a high level of technical interoperability between shared PHP code.

PSR-1 就是为了能够使共享的PHP代码之间有高度的互操作性.

OverView (概览)

PHP文件(MUST)必须只使用<?php 和 <?= 标签.
PHP文件(MUST)必须只能使用无BOM头的UTF-8编码格式.
PHP文件(SHOULD)应该要么声明 classe，functions。constants 等等,或者 general ouput(通用输出?),改变php.ini的配置等等，但是(SHOULD Not)不应该两个都有.
命名空间和类(MUST)必须要遵循自动加载的PSR规范[PSR-0,PSR-4];
类名明明(MUST)必须以大驼峰式.
类中的常量的命名(MUST)必须为以下划线分割的大写字母.
方法名(MUST)必须为小驼峰式.

PHP Tags

PHP代码(MUST)必须使用长标签<?php ?> 或者短标签 <?= ?>;(MUST NOT)不能有其他类型的写法.

Character Encoding

PHP代码(MUST)必须只使用无BOM头的UTF-8编码格式.

Side Effects

一个PHP文件(SHOULD)必须要声明一些class,function,constant等,并且没有side effects (执行逻辑),或者(SHOULD)应该有side effects(执行逻辑),但是(SHOULD NOT)不应该两个都同时存在.

'side effects'代表的就是和声明class,function,constant等不直接相关联的执行逻辑，仅仅来自这个包含的文件。

'Side effects' 包含以下操作,但不仅限于此：general output(通用输出), 'require'和'include'的使用,连接外部服务,修改php.ini的设置,触发错误或者抛出异常,修改全局或者静态变量,读取或者写入文件操作等等.

以下是一个我们要避免的例子,就是一个具有'declarations'和side effects的PHP文件。

<?php
// side effect: change ini settings
ini_set('error_reporting', E_ALL);

// side effect: loads a file
include "file.php";

// side effect: generates output
echo "<html>\n";

// declaration
function foo()
{
    // function body
}

以下是一个是正确的例子，只包含了'declaraion'没有'side effects'.

<?php
// declaration
function foo()
{
    // function body
}

// conditional declaration is *not* a side effect
if (! function_exists('bar')) {
    function bar()
    {
        // function body
    }
}

Namespace and Class Names

This means each class is in a file by itself, and is in a namespace of at least one level: a top-level vendor name

命名空间和类(MUST)必须要遵循自动加载规范【PSR-0，PSR-4】,这意味着每个类在一个文件中，并且至少在一个level的命名空间中:最高level的vendor名称.

类名命名必须以大驼峰式.

PHP5.3及以后版本中，写代码(MUST)必须使用正式的命名空间.

For example:

<?php
// PHP 5.3 and later:
namespace Vendor\Model;

class Foo
{
}

PHP5.2.x以及之前的版本(SHOULD)应该使用pseudo-namespacing(伪命名空间)的惯例：在类名前+'Vendor_'前缀.

<?php
// PHP 5.2.x and earlier:
class Vendor_Model_Foo
{
}

The term “class” refers to all classes, interfaces, and traits.

本文中的术语class,代表的是所有的class,interface,traits。

Constants

类中的常量(MUST)必须为以下划线分割的大写字母.
for example:

<?php
namespace Vendor\Model;

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

Properties

对于类的属性，本文档有意省略了对属性名的命名方式.(大驼峰/小驼峰/下划线等)

无论采用什么样的命名方式(SHOULD)应该和其所在scope相一致.scope 可能为vendor级别，package级别，class级别,或者method级别.

Methods

方法名(MUST)必须声明为小驼峰式.