在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

详见

PSR-1 基本代码规范:

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

PSR-3 日志接口规范:

PSR-4 自动加载相关

PSR-7 HTTP消息相关

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 定义版本信息

详见composer中文网

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

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

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

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

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

This source file is subject to the MIT license that is bundled
with this source code in the file LICENSE.
EOF;
$finder = PhpCsFixerFinder::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 PhpCsFixerConfig::create()
    ->setRules($fixers)
    ->setFinder($finder)
    ->setUsingCache(false);

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

PhpStorm

Sublime Text

Vim

在规定了自己的代码规范之后，如何保证别人提交的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有这个徽章。，可以自己的项目添加上了。

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

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

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

登录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可以获取这个徽章。

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

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

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

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