Pint

簡介 (Introduction)

Laravel Pint 是一個專為極簡主義者設計的 PHP 程式碼風格修復工具。Pint 建立在 PHP CS Fixer 之上，讓您可以輕鬆地確保程式碼風格保持整潔和一致。

Pint 會自動安裝在所有新的 Laravel 應用程式中，因此您可以立即開始使用。預設情況下，Pint 不需要任何設定，並且會依照 Laravel 的程式碼風格規範來修復您的程式碼風格問題。

安裝 (Installation)

Pint 已包含在最新版本的 Laravel 框架中，因此通常不需要安裝。但是，對於較舊的應用程式，您可以透過 Composer 安裝 Laravel Pint：

composer require laravel/pint --dev

執行 Pint (Running Pint)

您可以透過呼叫專案 vendor/bin 目錄下的 pint 二進位檔來指示 Pint 修復程式碼風格問題：

./vendor/bin/pint

如果您希望 Pint 以平行模式（實驗性）執行以提高效能，可以使用 --parallel 選項：

./vendor/bin/pint --parallel

平行模式也允許您透過 --max-processes 選項指定最大執行程序數量。如果未提供此選項，Pint 將使用機器上所有可用的核心：

./vendor/bin/pint --parallel --max-processes=4

您也可以針對特定檔案或目錄執行 Pint：

./vendor/bin/pint app/Models

./vendor/bin/pint app/Models/User.php

Pint 會顯示所有已更新檔案的詳細清單。您可以在呼叫 Pint 時提供 -v 選項來查看更多關於 Pint 變更的詳細資訊：

./vendor/bin/pint -v

如果您只想檢查程式碼是否有風格錯誤而不實際更改檔案，可以使用 --test 選項。如果發現任何程式碼風格錯誤，Pint 將回傳非零的結束代碼：

./vendor/bin/pint --test

如果您只想修改與 Git 提供的分支有差異的檔案，可以使用 --diff=[branch] 選項。這在 CI 環境（如 GitHub Actions）中非常有效，可以透過只檢查新增或修改的檔案來節省時間：

./vendor/bin/pint --diff=main

如果您只想修改 Git 中尚未提交變更的檔案，可以使用 --dirty 選項：

./vendor/bin/pint --dirty

如果您希望 Pint 修復任何有程式碼風格錯誤的檔案，但如果有任何錯誤被修復時也以非零結束代碼退出，可以使用 --repair 選項：

./vendor/bin/pint --repair

設定 Pint (Configuring Pint)

如前所述，Pint 不需要任何設定。但是，如果您希望自訂預設配置、規則或檢查的資料夾，可以在專案的根目錄中建立一個 pint.json 檔案：

{
  "preset": "laravel"
}

此外，如果您希望使用特定目錄中的 pint.json，可以在呼叫 Pint 時提供 --config 選項：

./vendor/bin/pint --config vendor/my-company/coding-style/pint.json

預設配置 (Presets)

預設配置定義了一組可用於修復程式碼風格問題的規則。預設情況下，Pint 使用 laravel 預設配置，該配置遵循 Laravel 的程式碼風格規範來修復問題。但是，您可以透過向 Pint 提供 --preset 選項來指定不同的預設配置：

./vendor/bin/pint --preset psr12

如果您願意，也可以在專案的 pint.json 檔案中設定預設配置：

{
  "preset": "psr12"
}

Pint 目前支援的預設配置有：laravel、per、psr12、symfony 和 empty。

規則 (Rules)

規則是 Pint 用來修復程式碼風格問題的風格指南。如上所述，預設配置是預先定義的規則群組，對於大多數 PHP 專案來說應該是完美的，因此您通常不需要擔心它們包含的個別規則。

但是，如果您願意，可以在 pint.json 檔案中啟用或停用特定規則，或是使用 empty 預設配置並從頭開始定義規則：

{
  "preset": "laravel",
  "rules": {
    "simplified_null_return": true,
    "array_indentation": false,
    "new_with_parentheses": {
      "anonymous_class": true,
      "named_class": true
    }
  }
}

Pint 建立在 PHP CS Fixer 之上。因此，您可以使用它的任何規則來修復專案中的程式碼風格問題：PHP CS Fixer Configurator。

排除檔案 / 資料夾 (Excluding Files / Folders)

預設情況下，Pint 會檢查專案中除了 vendor 目錄以外的所有 .php 檔案。如果您希望排除更多資料夾，可以使用 exclude 設定選項：

{
  "exclude": ["my-specific/folder"]
}

如果您希望排除所有包含特定名稱模式的檔案，可以使用 notName 設定選項：

{
  "notName": ["*-my-file.php"]
}

如果您希望透過提供檔案的確切路徑來排除檔案，可以使用 notPath 設定選項：

{
  "notPath": ["path/to/excluded-file.php"]
}

要使用 Laravel Pint 自動化專案的 Linting，您可以設定 GitHub Actions 以便在將新程式碼推送到 GitHub 時執行 Pint。首先，請務必在 GitHub 的 Settings > Actions > General > Workflow permissions 中授予工作流程「Read and write permissions」。然後，建立一個包含以下內容的 .github/workflows/lint.yml 檔案：

name: Fix Code Style

on: [push]

jobs:
  lint:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: true
      matrix:
        php: [8.4]

    steps:
      - name: Checkout code
        uses: actions/checkout@v5

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php }}
          tools: pint

      - name: Run Pint
        run: pint

      - name: Commit linted files
        uses: stefanzweifel/git-auto-commit-action@v6