README

这是 Bravo3 编码标准（PHP）的 1.0.0 版本。

通用

• 所有 Bravo3 项目必须使用 MIT 许可证授权
• composer.json 应反映 MIT 许可证
• 此库可以包含在一个项目中，以要求所有 Bravo3 必需的库，例如 phpunit, psr/log 和 eloquent/enumeration

平台支持

• Bravo3 应用的最低要求是 PHP 5.4
• 所有代码必须与平台无关
• 不要使用仅在单个平台上工作的函数（例如 money_format）
• 不要在文件系统中引用绝对路径
• 不要需要特定的 Web 服务器（例如不要依赖于 .htaccess）
• 不要需要虚拟机
• 不要需要无法通过 Composer 安装的第三方工具（例如 Cucumber）

前端控制器 / 应用程序环境

• 您的应用程序必须始终有一个单一入口点
• 不要期望预置的环境变量

对于 Web 应用程序

• 您的环境必须由入口点定义
• 您的 vhost 配置必须将所有流量重定向到前端控制器

对于控制台应用程序

• 您的环境必须由一个参数定义
• 您的入口点必须在 Linux 系统上可执行，并在非 Linux 系统上通过 php 安全运行

配置

• 应用程序配置或版本控制下不得包含密码
• 使用一个参数文件，该文件已从 Git 仓库排除，以引入特定环境的配置
• 使用 incenteev/composer-parameter-handler 包来定义默认参数

版本控制系统

• 所有代码必须维护在 Git 中
• 所有仓库必须位于 Github 上的 Bravo3 组织中

Composer

• 所有库和项目都必须通过 Composer 控制依赖项
• Composer 应定义一个 PSR-0 自动加载器，以包含 src/ 和 tests/

"autoload": {
    "psr-0": { "": ["src/", "tests/"] }
},

项目结构

• 所有项目必须在 src/ 目录下包含 PSR-0 结构的格式化代码
• 所有测试必须在 tests/ 目录中（见测试）
• 所有文档必须在 docs/ 目录中（见文档）
• 必须在根目录或适当的应用程序目录（例如 "app/"）中存在一个 phpunit.xml.dist 文件
• 必须在根目录中存在一个 README.md 文件
• 如果存在 Web 根目录，它必须是根目录下独立的一个文件夹，并且具有合适的名称（例如 "web/"）
• 如果需要二进制目录，则应该是 "bin/"

版本控制

• 应用程序应遵循版本标准 x.y.z[-稳定性]，其中
  • x 是主要版本号：在重建或主要不兼容性时增加
  • y 是次要版本号：在次要不兼容性时增加
  • z 是修订号：仅在没有任何向后不兼容性时增加
  • -稳定性 是可选的，可以是以下之一
    • -稳定
    • -rc
    • -beta
    • -alpha
    • -dev
• 示例
  • 1.0.4-beta
  • 1.3.34
• 在发布新版本时，在 VCS 中标记提交
• 不要使用 'v' 前缀标记或版本（例如 v1.0.3）

文档

• 所有文档应采用Markdown格式，存储在项目的docs/文件夹中
• 所有项目应包含一个包含概述、简要使用示例和进一步文档链接的README.md

编码规范

• 所有代码必须遵循PSR-1标准
• 本节中所有其他标准都超出这些规则

SPL使用

• 在可能的情况下，您应扩展或利用SPL数据结构和类

命名规范

• 所有命名空间和类名必须采用大驼峰式（例如：MyStuff\ClassName）
• 缩写必须像单词一样处理（例如：“CIA”应为大写“Cia”）
• 所有方法名必须采用小驼峰式（例如：getSomeProperty()）
• 所有变量和属性必须采用蛇形（例如：$some_variable）
• 所有库和项目都必须具有二级命名空间（例如：Bravo3\Standards）

类型提示

• 所有方法参数应在可能的情况下包含类型提示
• 如果传递数组，则应使用array类型提示

代码风格

• 所有代码必须遵循PSR-2标准
• 本节中所有其他标准都超出这些规则

扩展风格

• 所有非根命名空间都应通过“use”语句导入
• 构造函数应始终包含括号
• 数组声明应使用方括号，绝不能使用array()（例如：$my_array = ['hello' => 'world'];）

文档

• 方法返回变量绝不应是未知的
• 如果方法返回多个选项，则PHPDoc块应包含所有选项，并用竖线分隔（例如：@return SomeClass|null）
• PHPDoc块绝不应不准确
• @param、@return和@throws应始终包含类型提示
• PHPDoc块不是强制的，除非返回变量将是未知的

代码要求

错误处理

• PHP错误和警告应始终转换为异常。

枚举

• 枚举应扩展eloquent/enumeration包

use Eloquent\Enumeration\AbstractEnumeration;

/**
 * @method static HttpRequestMethod GET()
 * @method static HttpRequestMethod POST()
 * @method static HttpRequestMethod PUT()
 * @method static HttpRequestMethod DELETE()
 */
final class HttpRequestMethod extends AbstractEnumeration
{
    const GET = 'GET';
    const POST = 'POST';
    const PUT = 'PUT';
    const DELETE = 'DELETE';
}

日志记录

• 所有代码都应利用PSR-3日志接口

异常

• 所有二级命名空间应具有一个Exception/目录
• 所有二级命名空间应具有一个通用异常接口
• 所有异常应实现二级通用接口，并扩展SPL异常类
  • 例如：class SomeException extends \RuntimeException implements MyBundleException

集合

• 当返回对象集合时，您的应返回一个\Traversable对象而不是数组
• 这可以通过使用ArrayIterator类快速实现，请参阅SampleItemCollection.php

原则

• 所有代码都应通过所有SOLID原则
• 所有服务和库都应该是独立的、高度接口化，并使用抽象与其他服务进行通信

接口

• 在适用的情况下，对象应实现一个接口
• 在适用的情况下，接口应作为方法参数的类型提示（不是实现，参见LSP）
• 主要接口应在适当的情况下包含抽象实现
• 辅助接口应在适当的情况下包含特质实现

分支

• 功能分支必须直接从master分支出来
• 功能分支的名称应采用“feature-”格式
• 热修复分支的名称应采用“hotfix-”格式

测试

• 单元测试必须使用最新的PHPUnit，并应使用最新版本的PHPUnit
• 单元测试应在根目录下的tests/文件夹中
• 测试用例应遵循PSR-0命名空间标准
• 测试用例应在二级命名空间下，后面跟着'Tests/'
  • 例如，tests/Bravo3/Standards/Tests/UtilityTest.php 将会测试 src/Bravo3/Standards/Utility.php
• 所有PHP代码应该有90%-100%的PHPUnit测试覆盖率，以下内容除外
  • 异常
  • 测试相关内容
  • 无法测试的场景（使用@codeCoverageIgnoreStart和@codeCoverageIgnoreEnd来排除这些内容）
• 需要第三方API的实时集成测试应该添加到@integration组中，并默认排除