php-cs-fixer 是個程式碼格式化工具,格式化的標準是PSR-1、PSR-2 以及一些symfony 的標準。這個工具也和 symfony、twig 等優秀的 PHP 函式庫出自同門。
安裝與更新
需要使用 PHP 5.3.6 以上的版本。
你可以直接下載封裝好的phar 套件:php-cs-fixer.phar;
或透過wget 下載(下面的都是OSX 和Linux 上的用法):
wget http://get.sensiolabs.org/php-cs-fixer.phar -O php-cs-fixer
或透過curl 下載:
curl http://get.sensiolabs.org/php-cs-fixer.phar -o php-cs-fixer
下載完成後給可執行的權限,然後移動到bin 目錄下面即可:
sudo chmod a+x php-cs-fixer sudo mv php-cs-fixer /usr/local/bin/php-cs-fixer
這樣就可以在任何地方直接使用php-cs-fixer
指令來呼叫了。
也可以用過Composer 來安裝:
composer global require fabpot/php-cs-fixer
如果你是Mac 用戶、homebrew 用戶並且已經tap 過homebrew/php 的話,也可以直接:
brew install php-cs-fixer
或者:
brew install homebrew/php/php-cs-fixer
如果後續需要更新的話:
php-cs-fixer self-update
如果是透過homebrew 安裝的:
brew upgrade php-cs-fixer
如果沒有將執行檔放到bin 目錄下或在Windows需要使用php php-cs-fixer.phar
代替php-cs-fixer
。
用法
用法也很簡單,最基本的指令參數就是fix
#,直接執行時會盡可能多的依照預設標準格式化程式碼:
# 格式化目录 如果是当前目录的话可以省略目录 php-cs-fixer fix /path/to/dir # 格式化文件 php-cs-fixer.phar fix /path/to/file
--verbose
選項用來展示應用了的規則,預設是文字(txt
)格式。
--level
選項用於控制需要使用的規則層級:
php-cs-fixer fix /path/to/project --level=psr0 php-cs-fixer fix /path/to/project --level=psr1 php-cs-fixer fix /path/to/project --level=psr2 php-cs-fixer fix /path/to/project --level=symfony
預設情況下執行的是PSR-2 的所有選項以及一些附加選項(主要是symfony 相關的)。還有一些屬於『貢獻等級』的選項,你可以透過--fixers
選擇性的添加,--fixers
的多個條件要用逗號分開:
php-cs-fixer fix /path/to/dir --fixers=linefeed,short_tag,indentation
如果有需要的話也可以使用-name_of_fixer
採取黑名單的方式設定停用哪些選項。如果同時設定了 --fixers
和 -name_of_fixer
,前者的優先權更高。
同時使用 --dry-run
和 --diff
指令可以顯示出需要修改的總和,但並非實際修改。
透過以下方式也可以查看有哪些內容是會修改的,但並非實際改變檔案:
cat foo.php | php-cs-fixer fix --diff -
自訂設定
--config
選項可以用來設定選取目錄以及檔案進行分析並格式化,但這個選項只能設定一些常見的已知的項目,例如symfony:
# For the Symfony 2.3+ branch php-cs-fixer fix /path/to/sf23 --config=sf23
已有選項:
default 預設設定
magento magento 專案
sf23 symfony 的專案
#更多時候,我們可以透過設定檔來自訂格式化選項以及搜尋的目錄和檔案。自訂配置透過在專案根目錄中新增一個 .php_cs
檔案的方式實現。
設定本身就是 PHP 程式碼,最後回傳一個 Symfony\CS\ConfigInterface 的實例即可。你可以設定格式化的選項、等級、檔案以及目錄。
下面是一個簡單的例子:
<?php $finder = Symfony\CS\Finder\DefaultFinder::create() ->exclude('somedir') // 忽略 somedir ->in(__DIR__) // 当前目录 ; return Symfony\CS\Config\Config::create() ->fixers(['strict_param', 'short_array_syntax']) // 添加两个选项 ->finder($finder) ;
如果你想完全自訂格式化選項,就需要將格式化等級清空,並指定好所有需要的選項:
<?php $finder = Symfony\CS\Finder\DefaultFinder::create() ->in(__DIR__) ; return Symfony\CS\Config\Config::create() ->level(Symfony\CS\FixerInterface::NONE_LEVEL) ->fixers(['trailing_spaces', 'encoding']) ->finder($finder) ;
你也可以透過在選項前面加上-
的方式來停用某些選項,例如下面這個範例不採用PSR-0:
<?php $finder = Symfony\CS\Finder\DefaultFinder::create() ->exclude('somedir') ->in(__DIR__) ; return Symfony\CS\Config\Config::create() ->fixers(['-psr0']) ->finder($finder) ;
預設條件下的格式化級別是symfony (最嚴格),你可以修改這個等級:
<?php return Symfony\CS\Config\Config::create() ->level(Symfony\CS\FixerInterface::PSR2_LEVEL) ;
透過這些設定選項的組合,可以很輕易的客製化出自己想要的效果。
你也可以透過 --config-file
選項來指定 .php_cs
檔案的位置。
啟用快取可以在後續的執行中加快速度,透過以下方法設定:
<?php return Symfony\CS\Config\Config::create() ->setUsingCache(true) ;
編輯器外掛程式
下面這些編輯器/IDE 的外掛程式可以幫你簡化格式化的工作:
Atom
#NetBeans
PhpStorm
#Sublime Text
Vim
#格式化選項
# #psr0 [PSR-0] PSR-0 的路徑與命名空間標準
encoding [PSR-1] 檔案必須是不含BOM 的UTF-8 編碼;
#short_tag [PSR-1]只能使用
和
= ?>兩種PHP 程式碼標籤;
braces [PSR-2] 所有語句區塊都必須包含在花括號內,且位置以及縮排是符合標準的;
class_definition [PSR-2] class、trait、interfaces 關鍵字和名稱之間只能有一個空格;
#elseif [PSR-2] 使用
elseif取代
else if;
#eof_ending [PSR-2] 檔案必須以空白行結尾;
function_call_space [PSR-2]
# 當呼叫函數與方法時,函數名稱和方法名稱與參數擴充之間不能有空格;function_declaration [PSR-2]
函數宣告時空格的使用需要符合PSR-2;
#indentation [PSR-2]
程式碼必須使用四個空格縮排而不是製表符;line_after_namespace [PSR-2]
命名空間的宣告後必須有一個空白行;linefeed [PSR-2]
所有PHP 檔案只能用LF(Unix) 結尾;
- ##lowercase_constants [PSR-2 ]
PHP 常數true、false 和null 必須使用小寫;
- lowercase_keywords [PSR-2]
# PHP 關鍵字必須都是小寫;
- #method_argument_space [PSR-2]
方法宣告及呼叫時,參數之間的逗號前不能有空格,逗號後必須有一個空格;
#multiple_use [PSR-2]
# 每個use 只能宣告一個元素;
parenthesis [PSR-2] 圓括號內兩側不能有空格;
php_closing_tag [PSR-2] 純PHP 檔案必須省略- ?>
標籤;
single_line_after_imports [PSR-2] 每個use 宣告獨立一行,且use 語句區塊之後要有一個空白行;
trailing_spaces [PSR-2]刪除非空白行之後多餘的空格;
#visibility [PSR-2]-
每個屬性和方法都必須指定作用域是public、
和
protected#還是
private
,
abstract final - 必須位於作用域關鍵字之前,
static 必須位於作用域之後;
- #array_element_no_space_before_comma [symfony]
陣列宣告中,逗號之前不能有空格;
- #array_element_white_space_after_comma [symfony]
數組宣告中,逗號之後必須有一個人空格;
- #blankline_after_open
## [symfony] PHP 開始標籤的相同行不能有程式碼,且下方必須有一個空白行; concat_without_spaces [ symfony]
點連接符號左右兩邊不能有多餘的空格;
double_arrow_multiline_whitespaces [symfony]##=>
運算子兩端不能有多個空白行;#duplicate_semicolon [symfony]
刪除重複的分號;- empty_return [symfony]
# return 語句如果沒有任何回傳的話直接寫return 即可(不用return null);
empty_return [symfony] -
# 刪除多餘的空白行;
extra_empty_lines [symfony] -
修正函數參數與型別提示之間的缺少的空格問題;
#function_typehint_space [symfony]
#include [symfony] include- 和檔案路徑之間需要有一個空格,檔案路徑不需要用括號括起來;
- 使用
join 取代implode
函數; -
#list_commas [symfony]
######### ##########method_argument_default_value [symfony]###### 函數參數中有預設值的參數不能位於無預設值的參數之前;############## ########multiline_array_trailing_comma [symfony]###### 多行數組最後一個元素應該也有一個逗號;######################################################################################################### namespace_no_leading_whitespace [symfony]###### 命名空間前面不應該有空格;#####################new_with_braces [symfony]##oo###########new_with_braces [symfony]#######o 使用 使用 使用 使用。 new 新建實例時後面都應該帶上括號;#####################no_blank_lines_after_class_class_opening [symfony]###### 類別開始標籤後不應該有空白行;#####################no_empty_lines_after_phpdocs [symfony]###### PHP 文件區塊開始開始元素下面不應該有空白行;#### #################object_operator [symfony]#########T_OBJECT_OPERATOR### (###->###) 兩端不應有空格;###########list_commas [symfony]
刪除
list
語句中多餘的逗號; operators_spaces [symfony]
二進位運算子兩端至少有一個空格;phpdoc_indent [symfony]## phpdoc 應該保持縮排;
- ##phpdoc_inline_tag [symfony]
#phpdoc_inline_tag [symfony]
修正phpdoc 內嵌標籤格式,讓標籤與後續內容一律位於一行;
phpdoc_no_access [symfony]- 不應該出現在phpdoc 中;
和#phpdoc_no_empty_return [symfony]
#@return void @return null - 不應該出現在phpdoc 中;
#phpdoc_no_package [symfony]
和
@subpackage不應該出現在phpdoc 中;
- ##phpdoc_params [symfony]
@param
phpdoc 標量類型宣告時應該使用
,@throws
,@return
,@var
, 和@type
等phpdoc 標籤都要垂直對齊;
phpdoc_scalar [symfony] int - 而不是
integer,bool
float
而不是
boolean
, 而不是 - real
或 double;
phpdoc_separation [symfony]
phpdoc 中註解相同的屬性應該放在一起,不同的屬性之間應該有一個空白行分割; -
.
phpdoc_short_description [symfony]
phpdoc 的簡要描述應該以 、 - !
或? 結尾;
-
phpdoc_to_comment [symfony] 文件區塊應該都是結構化的元素;
除了文件區塊最開始的部分和最後的部分,phpdoc 開始和結束都應該是有內容的;
##phpdoc_trim [symfony]
phpdoc_type_to_var [symfony] # @type- 需要使用
@var 代替;
phpdoc 中應該正確使用大小寫;
phpdoc_types [symfony] -
註解中不應該包含變數名稱;phpdoc_var_without_name [symfony]
@var
和
@ type -
的用法;pre_increment [symfony]
不應該使用
i
或
--i -
代替#print_to_echo [symfony]
如果可能的話,使用
echo print - 語句;
#刪除
remove_leading_slash_use [symfony] use - 前的空白行;
刪除
remove_lines_between_uses [symfony] use - 語句區塊中的空白行;
#return [symfony] return - 之前應該有一個空白行;
在目前類別中使用
self_accessor [symfony] self - 取代類別名;
short_bool_cast [symfony] bool 類型資料前不應該試用兩個感嘆號;
- single_array_no_trailing_comma [symfony]
single_array_no_trailing_comma [symfony]
PHP 單行陣列最後一個元素後面不應該有空格;
single_blank_line_before_namespace [symfony]
命名空間聲明前應該有一個空白行;
single_quote [symfony]
簡單字串應該使用單引號代替雙引號;
spaces_after_semicolon [symfony]
修復分號後面的空格;
spaces_before_semicolon [symfony]禁止只有單行空格和分數號的寫法;
- spaces_cast [symfony]
變數和修飾符之間應該有一個空格;
- standardize_not_equal [symfony]
使用<>
取代
!=
#;
ternary_spaces [symfony]三元運算子之間的空格標準化;
-
#trim_array_spaces [symfony]
#################################################################### #######unalign_double_arrow [symfony]###### 不對其###=>###;################################################################################ unalign_equals [symfony]###### 不對其等號;#########
陣列需要格式化成和函數/方法參數類似,上下沒有空白行; unary_operators_spaces [symfony]
一元運算子和運算數需要相鄰;##unneeded_control_parentheses [symfony]
刪除控制結構語句中多餘的括號;