檢查與修正團隊的 Code Style,簡單介紹 PHP CS Fixer

每位碼農的人生成長歷程不盡相同,因此在 Coding 上可能都會有各自的習慣或是風格。

在團隊協作開發的時候,不同的 Coding 風格可能會給團隊造成一些困擾,例如:

  • 有人喜歡用 4 個空格排版,但有人覺得 2 個空格才剛好。
  • 宣告陣列用 [] 簡單明暸,但用老派的 array() 也可以吧?
  • 陣列(array)中用來區隔元素(element)的逗號,後面要不要加上空格?

雖然上述這些問題並不影響程式碼執行,卻會加重團隊進行 Code Review 或是 Debug 的負擔。因為在看懂 Code 之前,還需要花點時間熟悉他人的寫作風格。但真正讓人害怕的,是團隊中可能存在完全不在意排版, Code Style 屬於放飛自我的成員。

為了解決程式碼風格各異的問題。多數程式語言通常都會對 Code Style 提出一套自己的標準,例如 Python 有 PEP 8,PHP 也有 PHP-FIG 所提出的 PSR-12

為了統一團隊的 Code Style,可以使用 PHP CS Fixer 這個工具,對團隊的 Code Style 進行檢查與修正。

首先使用 composer 安裝 PHP CS Fixer。

composer require friendsofphp/php-cs-fixer --dev

安裝好之後,就可以使用 PHP CS Fixer 來對指定資料夾的所有檔案進行檢查並修正,使用起來相當簡單。

vendor/bin/php-cs-fixer fix src

如果想要調整的 PHP CS Fixer 的設定,可以在專案的根目錄中新建一個 .php-cs-fixer.dist.php 檔案。

<?php

// 設定要檢查的目錄
$finder = PhpCsFixer\Finder::create()
    ->in([
        __DIR__ . '/src',
        __DIR__ . '/tests',
    ])
    ->name('*.php')
    ->ignoreDotFiles(true)
    ->ignoreVCS(true);

$config = new PhpCsFixer\Config();

return $config->setRules([
        '@PSR12' => true, // 使用 PSR-12 的程式碼風格標準
        'strict_param' => true, // 開啟嚴格模式,禁止 PHP 自行轉換類型
        'array_syntax' => ['syntax' => 'short'], // 陣列宣告使用
    ])
    ->setFinder($finder);

PHP CS Fixer 可以搭配 GitHub Action 一起使用,如果程式碼檢查過後有地方需要調整,就會自動 commit 一個調整過後的版本並推上 Repo,以下方的 GitHub Action yaml 設定檔為例(來自 Spatiepackage-skeleton)。

name: Check & fix styling # workflow 的名稱,會在 Github Action 頁面上顯示的名稱(選擇性)

on: [push] # 只有在執行 git push 的時候,才會觸發並執行此 workflow

jobs: # 建立一個 job
  php-cs-fixer: # 定義此 job 的名稱
    runs-on: ubuntu-latest # 執行在最新版本的 ubuntu runner 上

    steps: # 定義 php-cs-fixer 的執行步驟
      - name: Checkout code # 定義步驟名稱
        # 使用 actions/checkout@v2 這個官方的 action
        # 可以查看 workflow 的執行狀況,並對 workflow 的虛擬環境進行指令操作(例如搭建測試環境)
        uses: actions/checkout@v2
        with:
          ref: ${{ github.head_ref }}

      - name: Run PHP CS Fixer
        uses: docker://oskarstark/php-cs-fixer-ga
        with:
          args: --config=.php-cs-fixer.dist.php --allow-risky=yes

      - name: Commit changes
        uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: Fix styling

可以注意到 yaml 設定檔在執行 PHP CS Fixer 的部分,帶了一個參數 --allow-risky=yes,代表允許有可能會改變程式碼行為的修正,預設不會開啟,使用時需要特別注意。

參考資料


sharkHead
written by
sharkHead

後端工程師, PHP 基金會每月 5 鎂小額贊助人 稍微擅長 PHP、Python 與 Google Search,偶爾寫寫 TypeScript 對於逗號後面必須加空格有著絕對的堅持