在github规范开发以及持续构建php项目

本文目的是通过自己写的一个php的简单的库（花密密码生成工具），

来学习我认为的php库开发的一些规范，以及github上持续构建你的项目的一些方法。其实是为了显示下边一系列的的徽章

本文涉及的内容有：

• 项目目录

• php的psr规范

• php备注的规范

• php的包管理器composer

• php保证代码质量（php-cs-fix，styleci，phpunit，coveralls）

• php的持续集成Travis CI

• php包发布Packagist 以及 LICENSE

• 更多的徽章获得

项目目录

    /
    |── bin/                            //命令行目录
    |── build/                          //构建目录
    |── src/                            //用于存放项目源代码
    |── tests/                          //单元测试目录
    |   ├── ClassNameTest/              //测试目录
    |   |── phpunit.xml                 //phpunit 配置文件
    |   └── bootstrap.php               //phpunit 引导文件
    |── vendor/                         //第三方依赖库
    |── .gitignore                      //git忽略文件
    |── .gitmessage                     //git提交规范文件
    |── .php_cs                         //php-cs-fix配置文件
    |── .styleci.yml                    //https://styleci.io配置文件
    |── .travis.yml                     //Travis CI 配置文件
    |── LICENSE                         //LICENSE
    |── composer.json                   //composer配置
    └── README.md                       //README

php的psr规范

详见

PSR-1 基本代码规范:

PSR-2 代码风格规范:(本篇规范是 PSR-1 基本代码规范的继承与扩展)

PSR-3 日志接口规范:

PSR-4 自动加载相关

PSR-7 HTTP消息相关

php备注的规范

PHPDoc WIKI

• @name 名字

• @abstract 申明变量/类/方法

• @access 指明这个变量、类、函数/方法的存取权限

• @author 函数作者的名字和邮箱地址

• @category 组织packages

• @copyright 指明版权信息

• @const 指明常量

• @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置

• @example 示例

• @exclude 指明当前的注释将不进行分析，不出现在文挡中

• @final 指明这是一个最终的类、方法、属性，禁止派生、修改。

• @global 指明在此函数中引用的全局变量

• @include 指明包含的文件的信息

• @link 定义在线连接

• @module 定义归属的模块信息

• @modulegroup 定义归属的模块组

• @package 定义归属的包的信息

• @param 定义函数或者方法的参数信息

• @return 定义函数或者方法的返回信息

• @see 定义需要参考的函数、变量，并加入相应的超级连接。

• @since 指明该api函数或者方法是从哪个版本开始引入的

• @static 指明变量、类、函数是静态的。

• @throws 指明此函数可能抛出的错误异常,极其发生的情况

• @todo 指明应该改进或没有实现的地方

• @var 定义说明变量/属性。

• @version 定义版本信息

php的包管理器composer

详见composer中文网

注意：如果访问不了国外镜像，可以全局修改使用中国镜像

  $  composer config -g repo.packagist composer https://packagist.phpcomposer.com

php保证代码质量

这一部分现在有很多解决方案。在github搜索phpQA也很多集成工具包

在我这个项目主要用到的就是php-cs-fix,phpunit.为了保证在github的代码风格
，用了https://styleci.io。

php-cs-fix

有关php-cs-fix可以参考这篇文章文章学习 php-cs-fixer - PHP 编码格式化工具
但是上边文章是php-cs-fix 配置文件是1.*版本的。现在官网升级到2.*版本。
很多配置文件名变化了。具体变化可以参考官方说明UPGRADE.md
下边给出在这个项目里的配置.cs_php

<?php
$year = date('Y');
$header = <<<EOF
The file is part of the rpnanhai/huami
(c) $year rpnanhai <[e-mail]>
This source file is subject to the MIT license that is bundled
with this source code in the file LICENSE.
EOF;
$finder = PhpCsFixer\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('vendor')
    ->in(__DIR__)
    ->ignoreDotFiles(true)
    ->ignoreVCS(true);
;
$fixers = array(
    '@PSR2' => true,
    'header_comment' => array('header' => $header),
    'no_empty_statement' => true, //多余的分号
    'no_extra_consecutive_blank_lines' => true, //多余空白行
    'include' => true, //include 和文件路径之间需要有一个空格，文件路径不需要用括号括起来；
    'no_trailing_comma_in_list_call'  => true, //删除 list 语句中多余的逗号；
    'no_leading_namespace_whitespace' => true, //命名空间前面不应该有空格；
    'array_syntax'  => array('syntax' => 'short'), //数组 【】 php版本大于5.4
    'no_blank_lines_after_class_opening' => true, //类开始标签后不应该有空白行；
    'no_blank_lines_after_phpdoc' => true, //PHP 文档块开始开始元素下面不应该有空白行；
    'object_operator_without_whitespace' => true, //(->) 两端不应有空格；
    'binary_operator_spaces'    => true, //二进制操作符两端至少有一个空格；
    'phpdoc_indent'             => true, //phpdoc 应该保持缩进；
    'phpdoc_no_access'          => true, //@access 不应该出现在 phpdoc 中；
    'phpdoc_no_package'         => true,
    'phpdoc_scalar'             => true, //phpdoc 标量类型声明时应该使用 int 而不是 integer，bool 而不是 boolean，float 而不是 real 或者 double；
    'phpdoc_to_comment'         => true, //文档块应该都是结构化的元素；
    'phpdoc_trim'               => true,
    'phpdoc_no_alias_tag'       => array('type' => 'var'),// @type 需要使用 @var 代替；
    'phpdoc_var_without_name'   => true, //@var 和 @type 注释中不应该包含变量名；
    'no_leading_import_slash'   => true, //删除 use 前的空行；
    //'no_extra_consecutive_blank_lines'  => array('use'), //删除 use 语句块中的空行；
    'self_accessor'             => true, //在当前类中使用 self 代替类名；
    'no_trailing_comma_in_singleline_array' => true, //PHP 单行数组最后一个元素后面不应该有空格；
    'single_blank_line_before_namespace' => true,//命名空间声明前应该有一个空白行；
    'single_quote'      => true,    //简单字符串应该使用单引号代替双引号；
    'binary_operator_spaces'    => array('align_equals' => true,'align_double_arrow' => true), //等号 => 对齐   symfony是不对齐的
    'no_singleline_whitespace_before_semicolons' => true, //禁止只有单行空格和分号的写法；
    'cast_spaces'   =>   true, //变量和修饰符之间应该有一个空格；
    'standardize_not_equals' => true, //使用 <> 代替 !=；
    'concat_space' => array('spacing' => 'one'), //点连接符左右两边有一个的空格；symfony是没空格
    'ternary_operator_spaces'   => true, //三元运算符之间的空格标准化
    'trim_array_spaces' => true, //数组需要格式化成和函数/方法参数类似，上下没有空白行；
    'unary_operator_spaces' => true, //一元运算符和运算数需要相邻;
    'no_whitespace_in_blank_line' => true, //删除空白行中多余的空格；
    'no_multiline_whitespace_before_semicolons' => true, //分号前的空格
    'no_unused_imports' => true, //删除没用到的use
);
return PhpCsFixer\Config::create()
    ->setRules($fixers)
    ->setFinder($finder)
    ->setUsingCache(false);

另外php-cs-fix都有对应的编辑器插件比如：

• PhpStorm

• Sublime Text

• Vim

styleci

在规定了自己的代码规范之后，如何保证别人提交的pr是否符合你的规范呢。

这时候就需要用https://styleci.io。通过github帐号注册后。就可以关联你的项目。

在你的项目目录添加配置文件 .styleci.yml

下边是和上面.php_cs对应的我的styleci配置文件，具体可以看https://styleci.io文档

preset: PSR2

risky: false

enabled:
  - no_empty_statement
  - no_extra_consecutive_blank_lines
  - include
  - no_trailing_comma_in_list_call
  - no_leading_namespace_whitespace
  - no_blank_lines_after_class_opening
  - no_blank_lines_after_phpdoc
  - object_operator_without_whitespace
  - binary_operator_spaces
  - phpdoc_indent
  - phpdoc_no_access
  - phpdoc_no_package
  - phpdoc_scalar
  - phpdoc_to_comment
  - phpdoc_trim
  - phpdoc_type_to_var
  - phpdoc_var_without_name
  - no_leading_import_slash
  - remove_lines_between_uses
  - self_accessor
  - no_trailing_comma_in_singleline_array
  - single_blank_line_before_namespace
  - single_quote
  - align_equals
  - no_singleline_whitespace_before_semicolons
  - cast_spaces
  - standardize_not_equals
  - concat_with_spaces
  - ternary_operator_spaces
  - trim_array_spaces
  - unary_operator_spaces
  - no_whitespace_in_blank_line
  - no_multiline_whitespace_before_semicolons
  - no_unused_imports
  - align_double_arrow
  - short_array_syntax


finder:
  exclude:
    - "vendor"
  name:
    - "*.php"

另外在https://styleci.io有这个徽章。，可以自己的项目添加上了。

phpunit

php单元测试，具体使用可以参考中文手册

这里配置好之后主要通过Travis CI进行调用，下边会讲到。

coveralls

coveralls是利用phpunit生成测试代码覆盖率的xml，来展示你的代码覆盖率。
网址是https://coveralls.io/。 依然是github注册。然后在Travis CI进行调用。需要 satooshi/php-coveralls 这个库调用。
在这个coveralls配置好之后就可以添加这个徽章了。

php的持续集成Travis CI

登录https://travis-ci.org/，依然使用github注册之后。给自己的项目开启持续构建。添加配置文件， ``

language: php

php:
  # - 5.4
  # - 5.5
  - 5.6
  - 7.0
  # - 7.1

before_script:
  - composer self-update
  - composer install -n --dev --prefer-source

script:
  - mkdir -p build/logs
  - ./vendor/bin/phpunit -c tests/phpunit.xml --coverage-clover build/logs/clover.xml

after_script:
  #coveralls调用 默认文件是build/logs/clover.xml，如果不是可以添加配置
  - travis_retry ./vendor/bin/coveralls -v

matrix:
  fast_finish: true

这时候push你的代码就可以开始持续构建了。另外在Travis CI可以获取这个徽章。

php包发布Packagist 以及 LICENSE

当你的代码完成后，测试完成后。就可以发布到Packagist包管理平台了。
如果composer.json配置好，按照官网一步一步来还是比较容易的，记得设置hook自动更新。
另外如果你的composer设置的国内的镜像，大概会有一到两个小时的延迟。

关于LICENSE的选取，可以参考这篇文章如何选择开源许可证？

在发布完之后就可以去https://poser.pugx.org/ 获取这几个徽章了。

更多的徽章获得

大家可以通过http://shields.io/这个网站来获得，获得去github添加更多的integrations，来获得相对应的徽章。