PHP-DI: зависимости PHP без фреймворка — мастерская и 8 задач
Как собрать PHP-приложение из сервисов: 8 задач, 19 вариантов, реальные ошибки, тестовая подмена и устаревший кеш. Мастерская и исходники.

PHP-DI: собрать приложение из понятных частей
В небольшом PHP-скрипте легко создать объект через new и сразу вызвать метод. Затем появляется отправка уведомления, расчёт цены, настройки API, журнал, тестовый транспорт и отдельная команда импорта. Код создания объектов начинает повторяться в контроллере, консольной команде и тестах. Изменение конструктора требует искать все места, где вручную собиралась одна и та же цепочка.
PHP-DI помогает описать эту сборку в одном месте. Бизнес-класс объявляет, какие объекты нужны ему для работы, а контейнер создаёт их по типам и определениям. Например, сервис заказа получает расчёт стоимости и интерфейс уведомлений. В тесте за интерфейсом стоит память, в другом приложении это может быть SMTP-адаптер или клиент очереди. Сервису заказа не приходится выбирать транспорт внутри метода.
Ниже — восемь практических задач и девятнадцать вариантов. Есть работающий PHP-проект без фреймворка, реальные ошибки, сравнение ручной и автоматической сборки, окружение, фабрики, тестовая подмена и наглядный опыт устаревшего кеша. Мастерская позволяет посмотреть результат каждого запуска и скачать исходники для своего приложения.
Где применять: API, импорт, кабинет и небольшие сервисы
В HTTP API один сервис может использоваться из нескольких маршрутов. В консольном импорте нужна та же проверка и обработка данных, но другой способ вывода результата. В кабинете отчётов один транспорт отправляет уведомление в production, а другой сохраняет намерение отправки при тестировании. Разделение логики и сборки помогает сохранить одинаковое поведение в разных точках входа.
Для старого проекта внедрение удобно начинать с одного участка. Выделите расчёт или обработку заявки в класс, передайте его зависимости через конструктор и соберите объект рядом с точкой входа. После этого добавьте контейнер, если ручная сборка стала заметно разрастаться. Переписывать все страницы, функции и глобальные переменные одним заходом не требуется.
PHP-DI особенно полезен там, где состав приложения меняется по окружению или тесту. При этом два простых объекта могут остаться обычными new. Библиотека не добавляет маршрутизацию, ORM, авторизацию или фоновые процессы. Она решает конкретную задачу: получить нужный объект вместе с корректно подготовленными зависимостями и сделать эту сборку управляемой.
Внедрение зависимости и контейнер — два разных шага
Dependency injection начинается с конструктора, а не с установки пакета. Наш QuoteService принимает PriceCalculator снаружи. Класс не ищет калькулятор в глобальной переменной, не создаёт контейнер и не читает конфигурацию. Его обязанность — попросить вычисление и вернуть результат. Такой сервис легко проверить простым вызовом метода.
Контейнер появляется в месте сборки приложения, которое часто называют composition root. В проекте это config/bootstrap.php и начальная часть CLI-примера. После получения основного сервиса работа идёт через его обычные методы. Передавать весь контейнер в каждый объект удобно только на первый взгляд: реальные зависимости становятся скрытыми, а тесту приходится воспроизводить неизвестный набор записей.
Посмотрите на конструктор ниже: он сразу сообщает, что необходимо для расчёта. Если позже добавится налоговая политика, её можно передать отдельным объектом и явно обсудить изменение контракта. Общий контейнер не должен превращаться в универсальную сумку для текущего пользователя, заказа, запроса и временных результатов.
<?php
declare(strict_types=1);
namespace Workshop;
final class QuoteService
{
public function __construct(private PriceCalculator $calculator) {}
public function quote(int $quantity): array
{
return ['quantity' => $quantity, 'totalKopecks' => $this->calculator->total($quantity, 12500)];
}
}
Версия, Composer и точное повторение проекта
Материал подготовлен для PHP-DI 7.1.1. В скачиваемом проекте требуется PHP не ниже 8.3; сама библиотека имеет более широкий минимум, но примеры и проверенное окружение здесь согласованы с PHP 8.3. Composer lock содержит точные версии PHP-DI и транзитивных зависимостей. Номер версии проверен по Packagist при подготовке 16 ноября 2026 года.
В composer.json используется ограничение ^7.1.1, а composer install устанавливает сохранённый набор из composer.lock. Команда update намеренно решает другую задачу: пересчитывает зависимости и может изменить lock. После обновления нужно заново выполнить тесты, особенно проверки компиляции и ошибок. Копировать только vendor без исходников и lock для воспроизводимого проекта неудобно.
Если Composer пока незнаком, начните с нашего руководства по Composer. Синтаксис классов, конструкторы и интерфейсы разобраны в большом PHP-мануале сайта. Установка библиотеки не требует Symfony, Laravel или отдельного сервера контейнера.
{
"name": "aen/php-di-workshop",
"description": "Executable PHP-DI examples and recorded workshop",
"type": "project",
"license": "MIT",
"require": {
"php": ">=8.3",
"php-di/php-di": "^7.1.1"
},
"autoload": {
"psr-4": {
"Workshop\\": "src/"
}
},
"scripts": {
"test": "php tools/record.php",
"warmup": "php tools/warmup.php"
},
"config": {
"sort-packages": true,
"allow-plugins": false
}
}
Мини-мастерская: опыт, результат и исходный файл
Сначала выберите задачу, затем вариант и среду выполнения. В карточке объясняется, что именно стоит сравнить. Например, у фабрики отличаются два get и сочетание get с make, а в опыте компиляции можно последовательно открыть первый релиз, прежний кеш с новыми данными и новый каталог релиза. Кнопки предыдущей и следующей задачи помогают пройти материал по порядку.
Каждая запись получена настоящим запуском PHP. Страница показывает готовые результаты и не исполняет введённый код на хостинге. Код завершения, PHP-версия, результат и исключение относятся к выбранному запуску. Отрицательные варианты выделены отдельно: ожидаемый отказ не подменяется успешным JSON соседнего опыта. Уведомления в проекте учебные и никуда не отправляются.
Ниже результата расположен просмотр исходных файлов. Выберите класс, определения, CLI или руководство Linux/VPS, скопируйте код либо скачайте весь проект. JSON выбранного опыта тоже можно сохранить. Для собственного значения количества или нового транспорта изменяйте проект локально: выбор варианта на странице не является удалённым PHP-терминалом.
Опыт 1. Собрать один сервис вручную
В ручном примере создаётся PriceCalculator, затем он передаётся QuoteService. Для трёх единиц по 12 500 копеек результат равен 37 500 копейкам. Деньги представлены целым числом, чтобы учебный расчёт не отвлекался на особенности двоичной арифметики float. Налогов, скидок и валютного преобразования в этом примере нет.
Этот вариант полезен как контрольный. Он показывает, что контейнер не обязан менять бизнес-результат: при одинаковых объектах и аргументах сумма должна остаться прежней. В тестах проекта результат ручной сборки сравнивается с autowiring. Если они отличаются, сначала ищите разные определения или состояние, а не объясняйте расхождение магией библиотеки.
Запустите examples/manual.php, затем поменяйте аргумент quote. Ноль и количество больше ста отклоняются самим калькулятором. Создание объектов и проверка допустимости заказа относятся к разным обязанностям. Контейнер не должен автоматически принимать неверное количество только потому, что все зависимости удалось найти.
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/vendor/autoload.php';
use Workshop\{PriceCalculator, QuoteService};
$service = new QuoteService(new PriceCalculator());
echo json_encode($service->quote(3), JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT);
Опыт 2. Autowiring: типы помогают построить цепочку
Второй запуск просит у контейнера QuoteService. PHP-DI видит параметр конструктора PriceCalculator, создаёт калькулятор и передаёт его сервису. В нашем небольшом графе не требуется отдельное определение для каждого простого класса. Результат остаётся тем же: три единицы и 37 500 копеек.
Попробуйте проследить цепочку от внешнего класса к внутреннему. Это помогает читать более крупные приложения: контроллер зависит от сервиса, сервис — от репозитория или политики. Конструкторы должны оставаться достаточно понятными. Если для простой операции приходится собирать десятки несвязанных объектов, полезно пересмотреть границы самого класса.
Autowiring работает с доступной информацией о типах, но не понимает предметную область. Он не выбирает нужный SMTP-провайдер и не определяет адрес вашего API. В следующем варианте именно эта граница становится видимой. Подробности механизма описаны в официальном разделе autowiring.
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/vendor/autoload.php';
$container = (new DI\ContainerBuilder())->build();
$service = $container->get(Workshop\QuoteService::class);
echo json_encode($service->quote(3), JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT);
Строковый параметр: почему контейнеру нужен явный выбор
Endpoint принимает строку baseUrl. Из типа string нельзя узнать, нужен ли адрес склада, оплаты или отчётов. Вариант scalar-missing намеренно запрашивает этот класс без настройки и получает ошибку сборки. Такой отказ полезнее случайного URL по умолчанию, который незаметно отправлял бы запросы не в ту систему.
В исправленном варианте constructorParameter задаёт значение по имени аргумента. Учебный адрес example.invalid зарезервирован для примеров и не используется для реального HTTP-вызова. Объект только хранит конфигурацию. Поэтому успешная сборка Endpoint не означает, что сеть доступна или внешний сервер принял запрос.
Имена параметров входят в эту конфигурацию: при переименовании baseUrl нужно изменить и определение. Для большого набора настроек удобнее отдельный проверяемый объект, как AppSettings ниже. Тогда сервис получает осмысленный тип, а не длинный список строк, которые легко перепутать местами.
$builder->addDefinitions([Endpoint::class => autowire()->constructorParameter('baseUrl', 'https://example.invalid/api')]);
$result = ['baseUrl' => $builder->build()->get(Endpoint::class)->baseUrl]; break;
Опыт 3. Интерфейс отделяет действие от транспорта
OrderService получает Notifier, а не конкретный SMTP-клиент. Это позволяет обсуждать поведение сервиса без выбора библиотеки почты. Но интерфейс нельзя создать как обычный класс: в нём нет законченной реализации. Вариант interface-missing показывает этот ожидаемый отказ при попытке собрать сервис заказа.
Определение Notifier → MemoryNotifier устраняет неопределённость. В результате preview возвращает расчёт и описание учебного уведомления. Поле deliveredExternally равно false: сообщение сохранено только в массиве объекта. Такая явная граница важна для демо и теста — наличие объекта сообщения не подтверждает доставку адресату.
В реальном приложении за тем же интерфейсом может появиться адаптер очереди или SMTP. Прежде чем заменить реализацию, согласуйте ошибки, повторную отправку и идемпотентность. Совпадающий метод send ещё не гарантирует одинаковую семантику транспорта. Контейнер помогает выбрать реализацию, но контракт поведения остаётся вашей ответственностью.
<?php
declare(strict_types=1);
namespace Workshop;
interface Notifier
{
public function send(string $reference): array;
}
Файл определений: одна точка выбора реализации
В config/definitions.php собраны интерфейс, параметры окружения и классы, которые нужны приложению. Алиас через get направляет Notifier на запись MemoryNotifier. Это позволяет получить один и тот же объект по основному имени и через интерфейс в пределах данного контейнера. В нашем опыте такое поведение удобно для проверки накопленных уведомлений.
Список определений также содержит QuoteService и OrderService. Для простого autowiring эти строки не обязательны, но при компиляции они делают известные классы явными. Не нужно добавлять в файл каждый вспомогательный DTO автоматически: сначала определите, какие записи контейнер действительно должен создавать и какие сервисы проверяются при прогреве.
Конфигурация должна читаться как карта сборки, а не как большой сценарий обработки заказа. Избегайте скрытых запросов к сети при простом подключении файла. Более сложное создание объекта лучше вынести в отдельную фабрику, которую можно открыть, протестировать и диагностировать независимо от остальных определений.
<?php
declare(strict_types=1);
use Workshop\{AppSettings, SettingsFactory, Notifier, MemoryNotifier, QuoteService, OrderService, PriceCalculator};
use function DI\{autowire, env, factory, get};
return [
'app.label' => env('DEMO_LABEL', 'Мастерская'),
'app.timeout' => env('DEMO_TIMEOUT', '5'),
AppSettings::class => factory(SettingsFactory::class)
->parameter('label', get('app.label'))
->parameter('timeout', get('app.timeout')),
Notifier::class => get(MemoryNotifier::class),
MemoryNotifier::class => autowire(),
PriceCalculator::class => autowire(),
QuoteService::class => autowire(),
OrderService::class => autowire(),
];
Опыт 4. Окружение: получить строку и проверить смысл
Сценарии config-default и config-custom создают AppSettings с разными значениями. В первом используются label «Мастерская» и timeout 5, во втором — «Сервис» и 12. Третий вариант передаёт строку forever и получает отказ фабрики. Все три результата получены отдельными PHP-процессами, поэтому окружение одного опыта не переносится в следующий.
SettingsFactory проверяет, что timeout — целое число от одного до тридцати. Простое приведение к int могло бы превратить ошибочный текст в ноль и скрыть проблему. После проверки остальной код получает уже готовый объект с int, а не пытается заново разобрать переменную в каждом методе.
Сначала решите, какие значения допустимы, затем где они хранятся. URL, лимит, имя очереди и пароль требуют разных проверок и правил вывода в журнал. В этой мастерской используются только вымышленные несекретные настройки; переносить такой подробный JSON-вывод на настоящие токены и пароли нельзя.
<?php
declare(strict_types=1);
namespace Workshop;
final class SettingsFactory
{
public function __invoke(string $label, string $timeout): AppSettings
{
$value = filter_var($timeout, FILTER_VALIDATE_INT);
if ($value === false || $value < 1 || $value > 30) {
throw new \InvalidArgumentException('DEMO_TIMEOUT must be an integer 1..30.');
}
return new AppSettings($label, $value);
}
}
Getenv, .env и окружение PHP-FPM
PHP-DI env обращается к доступному процессу окружению. Наличие файла .env рядом с composer.json само по себе не загружает его содержимое. Если проект использует dotenv, загрузка должна произойти до разрешения зависящих от него записей. Отдельный материал сайта о phpdotenv помогает разобраться с этим этапом.
Окружение SSH-консоли и FPM-worker может различаться. Команда в терминале успешно видит DEMO_TIMEOUT, а HTTP-запрос получает значение по умолчанию, потому что pool не передал переменную процессу. В руководстве проекта показано явное добавление несекретных env-параметров в собственный пул при clear_env=yes. После изменения конфигурации нужно перечитать пул.
Не используйте глобальный дамп окружения как обычный способ диагностики на публичном сайте. Проверяйте конкретную разрешённую настройку и выводите только безопасный признак. Официальный справочник getenv полезен для различий между отсутствующим значением, строкой и окружением конкретного способа запуска.
Опыт 5. Фабрика создаёт объект тогда, когда он понадобился
ReportFactory возвращает ReportClient и пишет событие в учебный Trace. Сразу после build журнал пуст: создание фабричного объекта ещё не потребовалось. Первый get добавляет вызов фабрики и конструктор клиента. Это наблюдаемое поведение конкретного проекта; оно не говорит, что всякая конфигурация приложения свободна от побочных действий.
Вынесенная фабрика полезна, когда создание требует преобразования параметров или вызова конструктора сторонней библиотеки. Сама фабрика остаётся небольшим классом. Не стоит помещать туда длительный импорт или бизнес-транзакцию: неожиданно тяжёлый первый get затруднит диагностику времени ответа.
В примере ReportClient не выполняет сетевых запросов. Его endpoint — учебная строка. Это помогает отдельно увидеть момент создания, не смешивая его с DNS, TLS и ответом внешнего сервиса. Если вашему клиенту нужен настоящий health-check, делайте его явным этапом и не называйте успешный constructor проверенной доступностью API.
<?php
declare(strict_types=1);
namespace Workshop;
final class ReportFactory
{
public function __invoke(): ReportClient
{
Trace::add('ReportFactory invoked');
return new ReportClient('https://example.invalid/reports');
}
}
Get и make: время жизни объекта имеет значение
Вариант factory-shared дважды вызывает get одной записи. В результате sameInstance=true и factoryCalls=1. Вариант factory-make сначала вызывает get, затем make; корневые объекты различаются, а фабрика вызвана дважды. В мастерской это видно одновременно в результате и последовательности событий.
Из опыта не следует, что make заново создаёт каждую вложенную зависимость. Другие записи контейнера могут оставаться общими. Если объект содержит изменяемое состояние, продумайте, должно ли оно жить на запрос, на задание или на весь процесс. Текущий пользователь и заказ обычно передаются аргументами операции, а не записываются в общий сервис навсегда.
Особенно внимательно проверяйте очередь или долгоживущий worker. В нём контейнер может пережить несколько заданий, и накопленный массив сообщений не исчезнет сам после первого вызова. Для таких процессов нужна явная политика сброса состояния. API get/make и ограничения описаны в руководстве по контейнеру.
case 'factory-make':
Trace::$events = [];
$builder->addDefinitions([ReportClient::class => factory(ReportFactory::class)]);
$container = $builder->build(); $trace[] = 'After build: ' . count(Trace::$events) . ' events';
$one = $container->get(ReportClient::class);
$two = $case === 'factory-shared' ? $container->get(ReportClient::class) : $container->make(ReportClient::class);
$result = ['sameInstance' => $one === $two, 'factoryCalls' => count(array_filter(Trace::$events, fn($e) => $e === 'ReportFactory invoked')), 'endpoint' => $two->endpoint];
$trace = array_merge($trace, Trace::$events); break;
Опыт 6. Проверить бизнес-код без настоящей почты
MemoryNotifier записывает reference в публичный учебный массив. Тест вручную собирает OrderService, вызывает preview и проверяет, что появился DEMO-1001. Для этой проверки контейнер вообще не требуется. Это важное свойство структуры: бизнес-логику можно проверить отдельно от конфигурации и инфраструктуры.
У такого теста есть точная граница. Он подтверждает намерение отправить уведомление и правильную передачу reference. Он не подтверждает SMTP-аутентификацию, формат письма, доставку и отображение в почтовом клиенте. Для транспорта понадобится отдельная интеграционная проверка, например с локальным почтовым приёмником.
Оставляйте тестовые реализации простыми и наблюдаемыми. Если подмена сама повторяет сложную бизнес-логику отправителя, тест может воспроизвести ту же ошибку и создать ложную уверенность. В нашем случае подмена только запоминает аргумент, а ожидаемый массив проверяется явно.
<?php
declare(strict_types=1);
namespace Workshop;
final class MemoryNotifier implements Notifier
{
public array $messages = [];
public function send(string $reference): array
{
$this->messages[] = $reference;
return ['channel' => 'memory', 'reference' => $reference, 'deliveredExternally' => false];
}
}
Переопределение до сборки и намеренный отказ транспорта
Вариант test-override сначала подключает общий файл определений, затем задаёт Notifier через FailingNotifier. Позднее определение выбирает другую реализацию до создания контейнера и первого запроса сервиса. Вызов preview заканчивается исключением Synthetic transport failure, которое ожидается тестом.
Так можно проверять реакцию приложения на недоступную интеграцию, не ломая настоящую почту. В более полном сервисе следующими проверками станут повтор, понятный ответ API и отсутствие двойной записи заказа. Наш пример останавливается на классифицированном отказе; он не изображает транзакционный workflow, которого в исходниках нет.
Не рассчитывайте, что позднее изменение определения автоматически перестроит уже созданный граф. Объект мог сохранить старый транспорт в конструкторе. Собирайте отдельный контейнер для отдельного теста или задавайте переопределение заранее. Порядок источников разобран в документации переопределений.
$builder->addDefinitions(dirname(__DIR__) . '/config/definitions.php');
$builder->addDefinitions([Notifier::class => autowire(FailingNotifier::class)]);
$result = $builder->build()->get(OrderService::class)->preview(2); break;
Опыт 7. Ошибка записи, цикл и неверный пользовательский ввод
Три отрицательных варианта показывают разные причины отказа. Неизвестный missing.service не имеет определения. CycleA требует CycleB, а CycleB — CycleA, поэтому цепочка не может завершиться. Количество ноль, напротив, передаётся уже успешно собранному QuoteService и отклоняется правилом калькулятора.
Различать эти случаи полезно и в журнале, и в ответе пользователю. Ошибка сборки обычно относится к конфигурации приложения и требует внимания разработчика. Неверное количество можно объяснить человеку и предложить исправить поле. Возвращать в обоих случаях одинаковое «что-то пошло не так» неудобно, а показывать полный стек всем посетителям небезопасно.
Цикл часто указывает на смешанные обязанности. Не всегда правильно разрывать его передачей контейнера внутрь одного класса: зависимость останется, только станет скрытой. Попробуйте выделить общий маленький сервис или изменить направление вызова. В архиве обе циклические модели оставлены специально как отрицательная фикстура.
<?php
declare(strict_types=1);
namespace Workshop;
final class PriceCalculator
{
public function total(int $quantity, int $unitPrice): int
{
if ($quantity < 1 || $quantity > 100 || $unitPrice < 0) {
throw new \InvalidArgumentException('Quantity must be 1..100; price must be non-negative.');
}
return $quantity * $unitPrice;
}
}
PSR-11 и понятные границы зависимости от библиотеки
Стандарт PSR-11 описывает общий интерфейс контейнера с get и has и категории исключений. Он не стандартизирует весь способ описания фабрик, autowiring или компиляции. Поэтому замена одного контейнера на другой не означает, что достаточно поменять имя пакета в Composer и оставить каждую настройку прежней.
В нашем проекте бизнес-классы не импортируют DI\Container. Специфичные функции DI находятся в config и CLI-опытах. Это ограничивает место, которое пришлось бы менять при другом способе сборки. Для класса расчёта ничего не меняется: он по-прежнему принимает обычные типизированные зависимости.
Проверка has не заменяет полноценного smoke-теста сервиса: наличие известной записи ещё не делает корректными все её зависимости и внешние настройки. Проверяйте необходимое разрешение и выбранное безопасное действие. Полный текст интерфейса и исключений находится в PSR-11; архитектурные рекомендации — в PHP-DI best practices.
Опыт 8. Компиляция: увидеть настоящий устаревший кеш
Этот опыт запускает три отдельных PHP-процесса. Первый создаёт скомпилированный контейнер в каталоге cache-a со значением release-one. Второй передаёт release-two, но использует тот же кеш и получает прежнее release-one. Третий создаёт контейнер в cache-b и возвращает release-two. Результаты видны как три самостоятельных записи.
Такой сценарий объясняет практическую ошибку развёртывания: код уже заменили, а сгенерированный контейнер оставили от предыдущего релиза. Проверка выполнена между процессами, поэтому её нельзя списать только на объект, который остался в памяти одного PHP-запуска. В тесте каждому повтору выделяется собственный временный каталог.
Компиляция полезна для известной стабильной конфигурации. При разработке в проекте она отключена, а в production включается отдельным условием. Не делайте вывод о конкретном ускорении по факту существования PHP-файла: статья не содержит нагрузочного сравнения. Измеряйте время и память на своём наборе сервисов.
<?php
declare(strict_types=1);
require dirname(__DIR__) . '/vendor/autoload.php';
$release = $argv[1] ?? 'a';
if (!in_array($release, ['a', 'b'], true)) { throw new InvalidArgumentException('Unknown release'); }
$label = $argv[2] ?? 'release-one';
$run = getenv('DEMO_RUN_ID') ?: 'manual';
if (!preg_match('/^[a-z0-9-]{1,50}$/D', $run)) { throw new InvalidArgumentException('Invalid run id'); }
$directory = dirname(__DIR__) . '/.runtime/' . $run . '/cache-' . $release;
$builder = new DI\ContainerBuilder();
$builder->addDefinitions(['release.label' => $label]);
$builder->enableCompilation($directory, 'AenCache' . strtoupper($release));
$container = $builder->build();
echo json_encode(['label' => $container->get('release.label'), 'compiledFile' => is_file($directory . '/AenCache' . strtoupper($release) . '.php')], JSON_THROW_ON_ERROR);
Прогрев: построить файл и разрешить важные сервисы
tools/warmup.php включает production-режим, получает контейнер и запрашивает AppSettings и OrderService. Одна успешная build не обязана проверить каждый ленивый factory. Поэтому прогрев дополнен разрешением записей, которые необходимы учебному HTTP-примеру и заказу. Неверный timeout в этом шаге становится ошибкой до переключения релиза.
Прогрев не должен неожиданно отправлять настоящие письма или менять данные. В наших конструкторах таких действий нет. Если существующая библиотека выполняет работу при создании клиента, учтите это отдельно и выберите безопасную проверку. Факт создания PDO или SMTP-объекта также не всегда равен полной проверке требуемой операции.
Рекомендация для этого проекта — отдельный каталог кеша внутри каждого релиза. Старый релиз сохраняет свой кеш для отката, новый собирается заранее. Не смешивайте сгенерированный файл с долгоживущим хранилищем пользовательских данных. Поведение компиляции и подготовка production описаны в официальном руководстве.
<?php
declare(strict_types=1);
putenv('APP_ENV=production');
$container = require dirname(__DIR__) . '/config/bootstrap.php';
// Resolve essential entries: build() alone does not validate every factory.
$container->get(Workshop\AppSettings::class);
$container->get(Workshop\OrderService::class);
echo "Container compiled; required services resolved.\n";
Windows: первый запуск и ожидаемый код ошибки
Распакуйте архив в отдельную папку и откройте PowerShell в корне проекта. Проверьте PHP и Composer, установите зависимости по lock и запустите запись опытов. Команда record запускает варианты в отдельных процессах, проверяет результаты и сохраняет windows.json для мастерской. Административные права для Composer install в собственной папке не нужны.
После этого вызовите один успешный и один отрицательный вариант вручную. Для interface-missing ожидается JSON ошибки и код завершения 2. В PowerShell код можно посмотреть через $LASTEXITCODE. Не игнорируйте его при написании CI: отрицательный пример должен быть ожидаемым условием теста, а не незаметно проглоченным отказом команды.
Если нужный PHP не найден, сначала проверьте PATH и php –ini. Версия в консоли может отличаться от PHP веб-сервера. Для просмотра статической мастерской достаточно PHP -S с каталогом public; для настоящего HTTP-расчёта используется другой каталог web. Эти две страницы имеют разные обязанности и не должны случайно меняться местами.
php --version
composer install --no-interaction --no-plugins --no-scripts
composer validate --strict
composer check-platform-reqs
php tools/record.php
php examples/manual.php
php examples/autowire.php
php tools/case.php config-custom
php tools/case.php interface-missing
Linux: тот же lock, отдельное окружение
На Linux последовательность остаётся знакомой: Composer install, проверка платформы, CLI-опыты. Не копируйте готовый кеш контейнера из Windows на VPS: он относится к исходному релизу и может содержать пути. Переносите исходники и lock, затем собирайте зависимости и кеш в целевом каталоге приложения.
В архиве есть Dockerfile для воспроизводимого Linux-запуска. Он не подключает Docker socket, не публикует сетевые порты и монтирует только каталог записей данного проекта. Команда с –rm удаляет свой завершившийся контейнер. Никакого глобального system prune или удаления чужих volumes для повторения не требуется.
Для обычного PHP-DI приложения Docker необязателен: библиотека работает внутри имеющегося PHP. Контейнер здесь нужен как отдельная проверяемая среда, а не как дополнительный production-сервис. На сервере используйте подходящий PHP CLI/FPM своего дистрибутива и проверьте расширения через Composer check-platform-reqs.
php --version
composer install --no-interaction --no-plugins --no-scripts
composer validate --strict
composer check-platform-reqs
php tools/record.php
php tools/case.php factory-shared
php tools/case.php factory-make
DEMO_LABEL='Учебный кабинет' DEMO_TIMEOUT=8 php tools/warmup.php
Настоящий HTTP-пример: расчёт и ответы 200/422
В каталоге web находится небольшой index.php. Он читает quantity, проверяет целое значение, получает QuoteService и возвращает JSON. Для трёх единиц ожидается 200 с totalKopecks=37500. Ноль и текст вместо числа дают 422. Этот endpoint можно запустить локально и подключить к собственной форме как следующий учебный шаг.
Внутренние ошибки сборки обрабатываются отдельно: клиент получает общее сообщение, а в серверный журнал попадает класс исключения. В пример не включены авторизация, rate limit, база и сохранение заказа. Здесь нет причины принимать платёж или считать preview завершённой покупкой. Такой узкий endpoint удобен для проверки границы HTTP → сервис → результат.
Обратите внимание, что контейнер запрашивается только у входа. QuoteService не получает $_GET или Request, а PriceCalculator не знает об HTTP-статусах. Те же классы можно вызвать из CLI и теста. Этот небольшой разрез показывает практическую пользу отделения инфраструктуры от расчёта.
<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
try {
$quantity = filter_var($_GET['quantity'] ?? '2', FILTER_VALIDATE_INT);
if ($quantity === false) { throw new InvalidArgumentException('quantity must be integer'); }
$container = require dirname(__DIR__) . '/config/bootstrap.php';
echo json_encode($container->get(Workshop\QuoteService::class)->quote($quantity), JSON_THROW_ON_ERROR);
} catch (InvalidArgumentException $error) {
http_response_code(422);
echo json_encode(['error' => $error->getMessage()], JSON_THROW_ON_ERROR);
} catch (Throwable $error) {
http_response_code(500);
error_log('Quote demo failed: ' . get_class($error));
echo '{"error":"Internal configuration error"}';
}
VPS: правильный document root и отдельный пул FPM
В production публикуется каталог web, а vendor, config и var остаются вне корня сайта. Статическая мастерская public размещается отдельно, если вы хотите сохранить учебную витрину. Не указывайте root на весь скачанный проект: конфигурация и служебные файлы не предназначены для прямой выдачи посетителям.
В docs/linux-vps.md приведён пример Nginx для одного front controller и отдельного FPM socket. Неизвестные PHP-пути отклоняются. Показанный HTTP-блок нужно дополнить вашим обычным HTTPS-развёртыванием; он не является готовым TLS-конфигом. После изменений сначала проверяются php-fpm -t и nginx -t, затем выполняется reload и контроль запросов.
Имена пакетов, пользователя, сокета и домена зависят от сервера. Пример рассчитан на новую отдельную конфигурацию, а не на замену рабочего пула. Наши материалы о Nginx и Caddy помогают связать приложение с привычным серверным окружением.
server {
listen 80;
server_name php-di.example.com;
root /var/www/php-di-demo/current/web;
location / {
try_files $uri /index.php$is_args$args;
}
location = /index.php {
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $realpath_root/index.php;
fastcgi_pass unix:/run/php/php8.3-fpm-phpdi.sock;
}
location ~ \.php$ { return 404; }
location ~ /\. { deny all; }
}
Релизы, права файлов и состояние между запросами
Новый релиз сначала получает зависимости и собственный var/cache. После прогрева FPM достаточно чтения готового скомпилированного файла; запись нужна только тому этапу, который создаёт кеш. Владельца и группу задавайте для конкретного каталога релиза. chmod 777 не решает проблему границ доступа, а просто скрывает неправильную схему прав.
Изменение переменной FPM требует перечитывания конфигурации процесса. Изменение определений требует согласованного кеша и кода нового релиза. При откате возвращайте соответствующий каталог целиком. Если используются долгоживущие workers или OPcache с особой политикой, дополнительно учитывайте обновление процесса и фактически исполняемого кода.
Общий изменяемый объект опасен, когда переживает несколько пользователей или заданий. Наш MemoryNotifier намеренно накапливает массив и подходит для ограниченного опыта. В реальном worker данные операции должны передаваться явно, а состояние очищаться по понятному правилу. Контейнер не определяет такую политику автоматически только по имени класса.
<?php
declare(strict_types=1);
require_once dirname(__DIR__) . '/vendor/autoload.php';
$builder = new DI\ContainerBuilder();
$builder->addDefinitions(__DIR__ . '/definitions.php');
if (getenv('APP_ENV') === 'production') {
// The application is installed in a separate directory for each release.
$builder->enableCompilation(dirname(__DIR__) . '/var/cache', 'AenReleaseContainer');
}
return $builder->build();
Что проверяют тесты и как расширять проект
Набор tools/record.php проверяет равенство ручной и автоматической сборки, явный скаляр, интерфейс, три конфигурации, момент вызова фабрики, get/make, тестовую подмену и разные ошибки. Отдельные процессы подтверждают устаревший скомпилированный файл и новый кеш релиза. Windows с PHP 8.3.33 и Linux с PHP 8.3.36 прошли по 81 проверке и создали по 19 записей. В двух сообщениях исключений различаются только системные переносы строк CRLF/LF; оригинальные записи сохранены, а сравнение учитывает это различие.
Записи содержат версии PHP/PHP-DI, команду, код завершения, фактический JSON и SHA-256 исходных файлов. Хеш помогает обнаружить изменение кода после записи. Он не является цифровой подписью, аудитом безопасности или доказательством производительности. Повторная запись после правки должна использовать новый код и затем заново попасть в статическую витрину.
Начните расширение с одного реального сервиса вашего проекта. Сохраните возможность собрать его вручную, добавьте проверку успешного действия и отказа, затем определите конфигурацию контейнера. Такой порядок показывает, что библиотека помогает управлять приложением, а не просто заменяет несколько new сложным файлом настроек.
Исходники и дальнейшее чтение
Архив содержит классы, определения, минимальные CLI-примеры, настоящий HTTP endpoint, composer.lock, Dockerfile, тесты, сохранённые результаты и мастерскую. README объясняет запуск в PowerShell и Linux, а docs/linux-vps.md — структуру релиза, FPM, Nginx и кеш. Сторонние лицензии собраны рядом с готовой статической страницей; авторские исходники доступны по MIT.
После знакомства полезно проделать три самостоятельные задачи. Добавьте второй безопасный транспорт, который пишет уведомление в собственный тестовый файл. Введите новую проверяемую настройку без чтения окружения внутри бизнес-метода. Затем намеренно удалите определение и убедитесь, что ваш smoke-тест останавливает релиз до переключения сайта. Для каждой задачи заранее определите ожидаемый результат.
Первичные материалы: документация PHP-DI, определения PHP, настройка контейнера, разные окружения. Сравнивайте примеры с закреплённой версией проекта и обновляйте зависимости вместе с проверками.


