Laravel Pint

Введение

Laravel Pint – это оптимизированный инструмент для форматирования кода на PHP для минималистов. Pint построен на основе PHP CS Fixer и обеспечивает простой способ поддержания чистого и последовательного стиля кода.

Pint автоматически устанавливается с каждым новым приложением Laravel, так что вы можете начать использовать его сразу. По умолчанию Pint не требует какой-либо настройки и автоматически исправляет проблемы со стилем кода в вашем коде, следуя оптимизированному стилю кодирования Laravel.

Установка

Pint включен в последние версии фреймворка Laravel, поэтому установка обычно не требуется. Однако для старых приложений вы можете установить Laravel Pint через Composer:

composer require laravel/pint --dev

Запуск Pint

Вы можете указать Pint исправить проблемы со стилем кода, вызвав двоичный файл pint, который доступен в каталоге vendor/bin вашего проекта:

./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 из определенного каталога, вы можете указать опцию --config при вызове Pint:

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

Предустановки (Presets)

Предустановки определяют набор правил, которые могут использоваться для исправления проблем со стилем кода в вашем коде. По умолчанию Pint использует предустановку laravel, которая исправляет проблемы, следуя оптимизированному стилю кодирования Laravel. Однако вы можете указать другую предустановку, предоставив опцию --preset Pint:

./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

Это правило удаляет все комментарии и описательный текст docblock из вашего кода, оставляя только строки, содержащие аннотации с @, такие как @param, @return, @var, @phpstan-type и т. д.:

/**
 * Get the posts for the user. [tl! remove]
 * [tl! remove]
 * @return HasMany<Post, $this>
 */
public function posts(): HasMany

Однострочные комментарии и блочные комментарии без аннотаций @ удаляются полностью. Если вы хотите сохранить конкретный комментарий, вы можете добавить к нему префикс @note, @warning или @todo:

// @note This comment will be preserved.

Чтобы включить это правило, добавьте его в файл pint.json:

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

Это правило автоматически пропускает файлы в каталоге config, поскольку файлы конфигурации обычно полагаются на комментарии как на документацию.

Исключение файлов / каталогов

По умолчанию Pint будет проверять все файлы .php в вашем проекте, за исключением тех, которые находятся в каталоге vendor. Если вы хотите исключить больше каталогов, вы можете сделать это, используя опцию конфигурации exclude:

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

Если вы хотите исключить все файлы, подходящие под определенный шаблон имени, вы можете сделать это, используя опцию конфигурации notName:

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

Если вы хотите исключить файл, указав точный путь к нему, вы можете сделать это, используя опцию конфигурации notPath:

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

Непрерывная интеграция

Действия GitHub

Чтобы автоматизировать проверку вашего проекта с помощью Laravel Pint, вы можете настроить GitHub Actions для запуска Pint всякий раз, когда новый код отправляется на GitHub. Во-первых, обязательно предоставьте «разрешения на чтение и запись» рабочим процессам в GitHub в разделе Настройки > Действия > Общие > Разрешения рабочего процесса. Затем создайте файл .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