在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 <rpnanhai@gamil.com>
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，來得到相對應的徽章。