Composer и стандарты PSR: как настроить современный PHP-проект

Из чего состоит современный PHP-проект

Минимальный набор, с которого стоит начинать любой проект:

• Composer — менеджер зависимостей и автозагрузчик классов.
• PSR-4 — правило, по которому имя класса соответствует пути к файлу.
• PSR-12 — общий стиль кода, чтобы любой разработчик читал проект без привыкания.
• PHP-CS-Fixer — автоматически приводит код к стилю.
• PHPStan — статический анализ: находит ошибки типов и опечатки без запуска кода.

PSR — это рекомендации группы PHP-FIG, которые поддерживают большинство фреймворков и библиотек.

Шаг 1. composer.json

Создайте проект командой composer init или напишите файл вручную:

{
    "name": "acme/shop",
    "type": "project",
    "require": {
        "php": ">=8.2"
    },
    "require-dev": {
        "phpstan/phpstan": "^2.0",
        "friendsofphp/php-cs-fixer": "^3.0"
    },
    "autoload": {
        "psr-4": { "Acme\\Shop\\": "src/" }
    },
    "autoload-dev": {
        "psr-4": { "Acme\\Shop\\Tests\\": "tests/" }
    },
    "config": {
        "sort-packages": true
    }
}

Ключевые моменты:

• require — то, что нужно в продакшене; require-dev — инструменты разработки.
• Указывайте версию PHP в require: Composer не даст поставить несовместимые пакеты.
• composer.lock коммитьте в репозиторий для приложений. Он фиксирует точные версии, и у всех собирается одно и то же.
• На сервере ставьте зависимости командой composer install --no-dev --optimize-autoloader.

Шаг 2. Автозагрузка по PSR-4

PSR-4 связывает пространство имён с папкой. При настройке выше класс Acme\Shop\Order\Invoice должен лежать в src/Order/Invoice.php:

<?php

declare(strict_types=1);

namespace Acme\Shop\Order;

final class Invoice
{
    public function __construct(
        private readonly int $amount,
    ) {
    }
}

Подключите автозагрузчик один раз в точке входа:

require __DIR__ . '/../vendor/autoload.php';

После изменения секции autoload выполните composer dump-autoload. Регистр в именах файлов и папок должен точно совпадать с именем класса: на Linux-сервере invoice.php и Invoice.php — разные файлы.

Шаг 3. Стиль кода: PSR-12 и PHP-CS-Fixer

PSR-12 описывает отступы, расположение скобок, порядок use, объявление типов. Запоминать не нужно — это делает PHP-CS-Fixer. Конфигурация .php-cs-fixer.dist.php:

<?php

$finder = PhpCsFixer\Finder::create()
    ->in([__DIR__ . '/src', __DIR__ . '/tests']);

return (new PhpCsFixer\Config())
    ->setRules(['@PSR12' => true])
    ->setFinder($finder);

Команды:

• vendor/bin/php-cs-fixer fix — исправить код;
• vendor/bin/php-cs-fixer fix --dry-run --diff — только показать нарушения (для CI).

Набор правил @PSR12 можно заменить на более новый @PER-CS, который развивает PSR-12.

Шаг 4. Статический анализ: PHPStan

PHPStan проверяет типы, несуществующие методы, неправильные аргументы. Файл phpstan.neon:

parameters:
    level: 6
    paths:
        - src
        - tests

Запуск: vendor/bin/phpstan analyse.

Как внедрять без боли:

• В новом проекте начинайте с высокого уровня строгости.
• В старом — начните с низкого и повышайте постепенно, либо сохраните текущие ошибки в baseline (--generate-baseline) и запрещайте только новые.

Шаг 5. Скрипты и CI

Соберите команды в секцию scripts composer.json:

"scripts": {
    "cs": "php-cs-fixer fix --dry-run --diff",
    "stan": "phpstan analyse",
    "check": ["@cs", "@stan"]
}

Теперь composer check одинаково запускается у разработчика и в CI. Пайплайн, который падает на нарушениях стиля и ошибках анализа, работает надёжнее любых договорённостей.

Частые ошибки

• Не коммитят composer.lock — на сервере ставятся другие версии пакетов.
• Правят код в vendor/ — изменения пропадут при следующей установке.
• Несовпадение namespace и пути — класс не находится только на продакшене.
• Включают анализ на максимум в старом коде — тысячи ошибок, и инструмент отключают.