Качество кода Laravel

Настройка и проверка PHPStan

Что такое PHPStan?

PHPStan – это мощный статический анализатор, который помогает находить ошибки в коде без его выполнения. Он анализирует типы данных, возможные ошибки, нарушение контрактов и другие проблемы, которые могут привести к багам в продакшене. Если вы используете Laravel, то стандартного PHPStan может быть недостаточно. Специально для Laravel существует расширение Larastan, которое учитывает особенности фреймворка, такие как Eloquent-модели, фасады и контейнер зависимостей.

Установка и настройка Larastan (в т.ч. PHPStan)

1. Устанавливаем Larastan через Composer:

composer require --dev larastan/larastan

в данном случае, пакет phpstan/phpstan установится, как зависимость, вместе с Larastan

2. Создаем конфигурационный файл phpstan.neon в корне проекта:

includes:
    - ./vendor/larastan/larastan/extension.neon
parameters:
    paths:
        - app/
        - app-modules/
    # Level 9 is the highest level
    level: 8

    stubFiles:
    - vendor/nuwave/lighthouse/_ide_helper.php

    checkModelProperties: true
    checkGenericClassInNonGenericObjectType: false

    excludePaths:
  ...

Здесь мы подключаем Larastan – расширение PHPStan для Laravel, а также задаём 8 (из 9) уровень проверки. Paths – указываем какие папки необходимо проверять. Секция stubFiles указывает PHPStan на файлы заглушек. Эти файлы помогают анализатору понимать код, который иначе был бы для него недоступен. checkModelProperties - включает проверку свойств моделей Eloquent. checkGenericClassInNonGenericObjectType - отключает строгую проверку generic-классов, когда они используются как обычные объекты. В секции excludePaths можно указать пути, по которым не требуется проверка phpstan.

3. Запускаем анализ кода:

vendor/bin/phpstan analyse

Кроме проверок на этапе написания кода, мы используем автоматическую проверку кода перед развертыванием. Мы добавили в .gitlab-ci.yml строку запуска проверки

сode static analyze:
stage: analyze
image: registry.dev-mage3.com/developers/astrio-laravel:base
dependencies:
    - composer 
 before_script:
    - cd app  script:
    - ./vendor/bin/phpstan analyze app/ app-modules/ --memory-limit 2048M
  allow_failure: true
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event' && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == 'dev'  
tags: [ dind ]

После этого PHPStan запускается автоматически, когда создаётся merge request в ветку dev.

Настройка и проверка Laravel Pint

Что такое Laravel Pint?

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

Установка Laravel Pint

Устанавливаем через Composer:

composer require --dev laravel/pint

Запускать Pint можно командой с консоли

vendor/bin/pint

Настройки хранятся в корне проекта в файле pint.json. Вот пример, который у нас используется на одном из проектов:

используется на одном из проектов:
{
    "preset": "laravel",
    "rules": {
        "strict_param": false,
        "array_syntax": {
            "syntax": "short"
        },
        "declare_strict_types": true,
        "comment_to_phpdoc": true
    },
    "exclude": [
    ]
}

Preset - используется Laravel-стиль кодирования. strict_param - строгая проверка параметров отключена. "syntax": "short" - включён короткий синтаксис массивов []. declare_strict_types - добавляется declare(strict_types=1); в начало файлов. comment_to_phpdoc - обычные комментарии превращаются в PHPDoc.

Laravel Pint – это инструмент для автоматического форматирования кода, который можно легко интегрировать в PhpStorm. Для этого указываем в настройках File → Settings. Php – Quality Tools – Laravel Pint. Указываем путь к Pint, например app/vendor/bin/pint, указываем путь к настройкам.

После этого в редакторе будет появляться подсказка с предложением исправить код

Laravel Pint автоматически форматирует код, приводя его к единому стилю, что делает его чище и удобнее для чтения. Он исправляет отступы, удаляет лишние пробелы и пустые строки, приводит массивы к короткому синтаксису и унифицирует кавычки. Также Pint добавляет строгую типизацию, исправляет комментарии и DocBlock, упрощает конструкции функций и убирает дублирующиеся импорты. Это помогает поддерживать код в чистом состоянии и снижает вероятность ошибок.

Настройка и проверка Laravel IDE Helper

Что такое Laravel IDE Helper?

Laravel IDE Helper создаёт вспомогательные файлы для улучшения автодополнения в PhpStorm и других IDE. Это делает разработку удобнее, особенно при работе с фасадами, моделями и сервисами Laravel/

Установка и генерация файлов

Устанавливаем пакет:

composer require --dev barryvdh/laravel-ide-helper

Публикуем конфигурацию

php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config

После установки мы прописали в composer.json команду для автоматической генерации подсказок при обновлении зависимостей. В разделе scripts.post-update-cmd указали следующий код:

"post-update-cmd": [
 ....
    "@php artisan ide-helper:generate",
    "@php artisan ide-helper:meta",
    "@php artisan lighthouse:ide-helper"
]

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

php artisan ide-helper:generate
php artisan ide-helper:meta
php artisan lighthouse:ide-helper

Преимущества использования IDE Helper

1. Улучшенное автодополнение - IDE (например, PhpStorm, VS Code) смогут точно определять методы фасадов Laravel, например:

use Illuminate\Support\Facades\Cache;
Cache::put('key', 'value', 600); // Без IDE Helper – методы могут быть не распознаны

2.Подсказки по моделям - После генерации ide-helper:models в коде появятся аннотации с доступными свойствами моделей:

/**
 * App\Models\User
 *
 * @property int $id
 * @property string $name
 * @property string $email
 * @property \Illuminate\Support\Carbon $created_at
 * @property \Illuminate\Support\Carbon $updated_at
 */
class User extends Model {}

Теперь при обращении к $user->name IDE будет знать, что это строка.

3.GraphQL (Lighthouse) - Если используется Lighthouse, команда lighthouse:ide-helper генерирует корректные типы для GraphQL-запросов, улучшая автодополнение схем и резолверов.

Использование IDE Helper делает разработку в Laravel удобнее: снижает вероятность ошибок, ускоряет написание кода и улучшает читаемость. Настроив автоматическую генерацию в composer.json, можно избежать необходимости ручного обновления подсказок после изменения зависимостей.

Дополнительно, это позволяет:

1. Экономить время разработчиков за счёт корректного автодополнения.

2. Улучшить качество кода, снижая вероятность использования несуществующих методов и свойств.

3. Делать код более понятным и самодокументируемым за счёт аннотаций.

4. Упростить работу с GraphQL при использовании Lighthouse.

5. Все эти преимущества делают IDE Helper незаменимым инструментом при разработке сложных проектов на Laravel.

Выводы

Использование PHPStan, Laravel Pint и Laravel IDE Helper в связке даёт максимально эффективный контроль качества кода в Laravel-проектах.

PHPStan обеспечивает статический анализ кода, выявляя ошибки, потенциальные баги и нарушения строгой типизации до момента выполнения. Это делает код безопаснее и уменьшает количество неожиданных ошибок в продакшене.

Laravel Pint автоматически форматирует код в соответствии с современными стандартами. Он устраняет стилистические недочёты, унифицирует синтаксис и повышает читаемость, упрощая командную работу.

Laravel IDE Helper значительно улучшает автодополнение и навигацию в PhpStorm и других IDE. Он устраняет проблему "магических методов" Laravel, делая работу с кодом удобнее и эффективнее.

Почему именно этот стек инструментов?

Эти три инструмента идеально дополняют друг друга:

1. PHPStan помогает находить логические ошибки.

2. Pint автоматически поддерживает кодстайл.

3. IDE Helper делает работу с Laravel в IDE интуитивной и предсказуемой.

Для Laravel нет более мощного набора инструментов, обеспечивающего чистоту, качество и удобство работы с кодом

Качество кода Laravel ▼

Качество кода Laravel
▼