Laravel Pint

簡介
安裝
執行 Pint
設定 Pint
持續整合
- GitHub Actions

簡介

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

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

安裝

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

composer require laravel/pint --dev

執行 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

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

./vendor/bin/pint --test

如果您希望 Pint 僅修改根據 Git 與提供的分支不同的檔案，可以使用 --diff=[branch] 選項。這可以在您的 CI 環境（如 GitHub Actions）中有效使用，透過僅檢查新增或修改的檔案來節省時間：

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

如果您希望 Pint 僅修改根據 Git 有未提交變更的檔案，可以使用 --dirty 選項：

./vendor/bin/pint --dirty

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

./vendor/bin/pint --repair

設定 Pint

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

{
    "preset": "laravel"
}

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

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

預設規則集

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

./vendor/bin/pint --preset psr12

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

{
    "preset": "psr12"
}

Pint 目前支援的預設規則集有：laravel、per、psr12、symfony 和 empty。

規則

規則是 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 設定器。

自訂規則

除了 PHP CS Fixer 規則外，Pint 還提供了以 Pint/ 為前綴的自訂規則。這些規則預設未啟用，但您可以在 pint.json 檔案中啟用它們。

`Pint/phpdoc_type_annotations_only`

此規則會從您的程式碼中移除所有註解和文件區塊文字，僅保留包含 @ 標註的行，例如 @param、@return、@var、@phpstan-type 等：

/**
 * Get the posts for the user. [tl! remove]
 * [tl! remove]
 * @return HasMany
 */
public function posts(): HasMany

不包含 @ 標註的單行註解和區塊註解會被完全移除。如果您希望保留特定註解，可以使用 @note、@warning 或 @todo 為其添加前綴：

// @note This comment will be preserved.

要啟用此規則，請將其加入您的 pint.json 檔案：

{
    "preset": "laravel",
    "rules": {
        "Pint/phpdoc_type_annotations_only": true
    }
}

[!NOTE] 此規則會自動跳過 config 目錄中的檔案，因為設定檔通常依賴註解來提供文件說明。

排除檔案 / 資料夾

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

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

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

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

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

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

持續整合

GitHub Actions

要使用 Laravel Pint 自動化檢查您的專案，您可以設定 GitHub Actions，在每次將新程式碼推送到 GitHub 時執行 Pint。首先，請確保在 GitHub 的 Settings > Actions > General > Workflow 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