Конфигурация и CLI
Настройте ядро, выберите флаги возможностей, передайте классам поведений зависимости из контейнера приложения и работайте с консолью.
Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал
Всё, что фреймворку нужно знать о вашем приложении, передаётся одним вызовом — init() на вашем ядре. На этой странице перечислены все параметры, которые принимает ядро, флаги возможностей, способ, которым behavior classes (классы поведений) получают зависимости из контейнера вашего приложения, и консоль vendor/bin/aspect, которой вы собираете и исследуете кеш.
Ваше ядро (kernel) наследует Go\Core\AspectKernel и регистрирует behavior classes в configureAop(). В API они называются aspects (аспекты), см. таблицу терминов:
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect());
// Eager alternative: $container->add(MonitorAspect::class, new MonitorAspect()); }}Инициализируется оно один раз, обычно во фронт-контроллере, сразу после автозагрузчика Composer:
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'],]);Параметры ядра
Заголовок раздела «Параметры ядра»Принимаются только перечисленные ниже параметры. Неизвестный ключ, неизвестный containerClass или неизвестный бит в features выбрасывает Go\Aop\Exception\InvalidConfigurationException, так что опечатка приводит к ошибке при загрузке, а не игнорируется молча.
| Параметр | Тип | По умолчанию | Назначение |
|---|---|---|---|
cacheDir |
string |
нет, обязательный | Каталог для скомпилированных исходников, прокси, кешей advisors и карты классов. |
appDir |
string |
каталог, в котором лежит vendor/ |
Корень приложения. Пути в кеше повторяют пути исходников относительно него, и компилируются только файлы внутри него. |
debug |
bool |
false |
Режим разработки: изменения файла ядра и файлов behavior classes инвалидируют кеш, а каждый класс и include загружается через компилирующий stream filter фреймворка. С false скомпилированные классы загружаются из кеша через карту классов Composer. В продакшене используйте false. |
includePaths |
string[] |
[] (всё внутри appDir) |
Каталоги, которые компилируются. Держите список узким: компиляция кода из vendor медленная и редко бывает нужна. |
excludePaths |
string[] |
[] |
Каталоги, которые никогда не компилируются. Каталог кеша, сам фреймворк и его зависимости времени выполнения (goaop/dissect, goaop/parser-reflection, nikic/php-parser, psr/container, symfony/finder) исключаются всегда. |
features |
int |
0 |
Битовая маска флагов Go\Aop\Features, см. следующий раздел. |
cacheFileMode |
int |
0770 минус umask |
Права доступа к файлам кеша. Значение должно быть в диапазоне от 0600 до 0777 и давать владельцу права на чтение и запись; каталоги получают соответствующие биты поиска. |
containerClass |
class-string |
Go\Core\Container |
Реализация контейнера ядра. Должна реализовывать Go\Core\AspectContainer (PSR-11 ContainerInterface). |
parsedFilesLimit |
int |
100 |
Сколько разобранных исходных файлов (синтаксических деревьев, примерно по 0,2 МБ каждое) goaop/parser-reflection держит в памяти во время компиляции. Должно быть положительным целым: чем больше, тем реже повторный разбор, чем меньше, тем меньше расход памяти. Заменяет лимит, заданный через ReflectionEngine::setMaximumCachedFiles() до init(), и служит значением по умолчанию для cache:warmup:aop --cached-files. |
Флаги возможностей
Заголовок раздела «Флаги возможностей»Флаги возможностей — это константы final-класса Go\Aop\Features. Комбинируйте их через |:
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::INTERCEPT_INCLUDES | Features::PREBUILT_CACHE,]);Features::ALL объединяет все флаги. AspectKernel::hasFeature() сообщает, установлен ли флаг, и выбрасывает исключение для неизвестного флага.
| Флаг | Когда использовать |
|---|---|
INTERCEPT_INCLUDES |
Ваше приложение загружает код через include/require, а не через Composer. |
PREBUILT_CACHE |
Вы собираете кеш во время деплоя и хотите, чтобы запросы полностью ему доверяли. Настройка для продакшена. |
PARTIAL_REFLECTION |
Класс, который вы хотите скомпилировать, наследует или реализует что-то, чего фреймворк не может найти. |
INTERCEPT_INCLUDES
Заголовок раздела «INTERCEPT_INCLUDES»Направляет include и require в скомпилированных файлах через компилятор. Используйте его для легаси-кода, который не загружается через Composer.
PREBUILT_CACHE
Заголовок раздела «PREBUILT_CACHE»Полностью доверяет кешу, собранному во время деплоя. Ядро пропускает проверки каталога кеша и его доступности для записи, сравнение filemtime исходников, проверки отслеживаемых ресурсов и проверки актуальности кешей advisors. Запрос никогда не компилирует код и никогда не пишет в каталог кеша, поэтому работает на файловых системах только для чтения.
Обратная сторона: кеш должен быть полным. Файлы, которые компилятор никогда не берёт (вне include paths, исключённые, не .php, например подключаемый шаблон), загружаются как есть. У всего остального внутри include paths должна быть запись в кеше.
Сама команда cache:warmup:aop не доверяет собираемому ею кешу. Запущенная поверх существующего каталога, она заново компилирует каждый файл, исходник которого изменился (размер или время изменения). Её загрузочный файл может ещё до начала сборки загрузить классы, о которых кеш пока не знает: там они загружаются нескомпилированными, а компилирует их сама сборка.
PARTIAL_REFLECTION
Заголовок раздела «PARTIAL_REFLECTION»Компилирует класс, родительский класс, интерфейс или трейт которого найти невозможно: объявленный кодом, сгенерированным во время выполнения, через class_alias() или в файле вне автозагрузчика Composer. Класс сопоставляется с правилами и компилируется со своими методами и свойствами и с методами и свойствами доступных предков. Члены, унаследованные от отсутствующего предка, не перехватываются.
Без этого флага такой класс не компилируется. Включайте флаг, когда столкнётесь с этой ошибкой.
Правилам для функций и инициализации флаг не нужен
Заголовок раздела «Правилам для функций и инициализации флаг не нужен»Механизм для этих matching rules (правил выбора) фреймворк включает сам на основе зарегистрированных behavior classes, в том числе ленивых. В features ничего задавать не нужно:
- Правило
execution(Namespace\function(*))добавляет прокси функций в подходящие пространства имён. - Правило
initialization(...)включает переписывание выраженийnew Foo(...)в скомпилированных файлах. Пока такое правило зарегистрировано, каждый переписанныйnewпроходит через перехватчик, поэтому применяйте такие правила только к коду, которому они нужны.
Синтаксис matching rules описан на странице Поведения и правила выбора.
Behavior classes из контейнера приложения
Заголовок раздела «Behavior classes из контейнера приложения»Контейнер ядра — это PSR-11-контейнер (Go\Core\AspectContainer расширяет Psr\Container\ContainerInterface). Он может делегировать контейнеру вашего приложения: Symfony, Laravel, PHP-DI или любому другому PSR-11-контейнеру. Для идентификаторов, не зарегистрированных в контейнере ядра, get(), getService() и has() обращаются к делегату.
Ядро инициализируется раньше, чем приложение собирает свой контейнер. Поэтому вы регистрируете behavior classes как обычно, а свои зависимости они получают лениво:
protected function configureAop(AspectContainer $container): void{ // Runs when one of its behaviors first runs, after the application container is attached $container->addLazyService( MonitorAspect::class, static fn(AspectContainer $container) => new MonitorAspect($container->getService(LoggerInterface::class)), ); // or take the whole behavior class from the application container, by the id it has there // $container->addLazyService(MonitorAspect::class, static fn(AspectContainer $c) => $c->get('app.monitor_aspect'));}Когда контейнер приложения появится, например сразу после загрузки ядра вашего фреймворка, подключите его:
ApplicationAspectKernel::getInstance()->getContainer()->setDelegate($psrContainer);Compile step (этап компиляции) и прогрев кеша требуют только сам behavior class. Они выполняются до setDelegate(), даже в vendor/bin/aspect, и никогда не создают его экземпляр. Фабрика запускается, когда впервые выполняется один из его behaviors (поведений); если зависимости к этому моменту всё ещё нет, выбрасывается ServiceNotFoundException.
Мосты (bridges) для Symfony, Laravel и Yii3 описаны на странице Интеграции.
Правила для фабрик behavior classes
Заголовок раздела «Правила для фабрик behavior classes»- Фабрика никогда не запрашивает у контейнера ядра собственный идентификатор. Этот идентификатор указывает на тот самый behavior class, который сейчас создаётся. Берите экземпляр из контейнера приложения по идентификатору, который у него там, или собирайте его из зависимостей.
- Behavior classes никогда не обнаруживаются в делегате. PSR-11-контейнер невозможно исследовать: стандартного способа искать сервисы по интерфейсу или тегу нет. Каждый behavior class регистрируется в
configureAop(). Мост для конкретного фреймворка может собирать сервисы по тегу или интерфейсу из своего контейнера и регистрировать их черезaddLazyService(). - Compile step никогда не создаёт экземпляр behavior class. Он читает behavior class, а сгенерированный код ссылается на каждый behavior по имени класса и метода. Каждый behavior class, в том числе без свойств экземпляра (такой PHP не может сделать ленивым), создаётся своей фабрикой, когда впервые выполняется один из его behaviors, — уже после подключения контейнера приложения.
- Создание behavior class не должно запускать его собственные behaviors. Если behavior class зависит от сервиса, создание которого перехватывает один из его behaviors (конструктор сервиса или метод, который вызывает конструктор), этот behavior выполнился бы на экземпляре, которого ещё нет. Перехватчик сообщает об этом исключением
AspectCircularReferenceException, в котором названы behavior class, перехваченный вызов и цепочка вызовов от создания до behavior. Внедряйте такую зависимость лениво (ленивый сервис, замыкание или service locator) или сузьте matching rule, чтобы behavior class не перехватывал создание собственных зависимостей.
Собственный класс контейнера
Заголовок раздела «Собственный класс контейнера»Чтобы заменить контейнер ядра, передайте свой класс в containerClass. Он должен реализовывать Go\Core\AspectContainer, то есть PSR-11-методы get() и has(), а также setDelegate(). Неизвестный идентификатор выбрасывает ServiceNotFoundException, реализующий Psr\Container\NotFoundExceptionInterface.
Режимы разработки и продакшена
Заголовок раздела «Режимы разработки и продакшена»Параметр debug переключает два режима. Ваши behavior classes и matching rules в обоих одинаковы.
'debug' => true |
'debug' => false |
|
|---|---|---|
| Загрузка классов | Каждый класс и include проходят через компилирующий stream filter. |
Скомпилированные классы берутся из кеша через карту классов Composer. |
| Изменённый исходник, behavior class или файл ядра | Компилируется заново при следующем запросе. | Кеш отдаётся как есть. |
| Пересборка кеша | Не нужна. | При каждом деплое, командой cache:warmup:aop. |
| Для чего | Локальная разработка. | Продакшен. Добавьте Features::PREBUILT_CACHE. |
В разработке шага сборки нет: отредактируйте класс или behavior, перезагрузите страницу, и фреймворк перекомпилирует то, что изменилось. Точки останова работают в вашем исходном коде.
В продакшене фреймворк передаёт Composer карту классов из кеша, а парсер и трансформеры на тёплых запросах не загружаются. С PREBUILT_CACHE поверх этого запрос пропускает ещё и все проверки исходных файлов и актуальности кеша. Как настроить всё это дальше (OPcache, предзагрузка, контейнеры), описано на странице Продакшен и производительность.
Каталог кеша
Заголовок раздела «Каталог кеша»cacheDir — единственный обязательный параметр. В каталоге лежат:
- скомпилированные исходники: тело каждого исходного класса в виде трейта
<Class>OriginalTraitпо относительному пути его исходного файла; - прокси — рядом со скомпилированными исходниками, под исходным именем класса;
- кеши advisors ваших behavior classes — обычные PHP-файлы рядом со скомпилированными исходниками;
- метаданные, включая
_include.cache— карту классов, которая передаётся Composer; _preload.php, если вы собираете кеш командойcache:warmup:aop --preload.
Что нужно знать:
- Он повторяет
appDir. Пути в кеше относительны корню приложения, а пути внутри метаданных хранятся относительно__DIR__, поэтому кеш остаётся рабочим, когда каталог приложения перемещается. - Он никогда не компилируется. Каталог кеша исключается всегда, что бы вы ни указали в
excludePaths. - Права доступа задаёт
cacheFileMode. По умолчанию —0770минус umask. Собирайте кеш от имени пользователя, который обслуживает запросы, или для него. - Удалите его при обновлении с 3.x. Ни один файл кеша 3.x повторно не используется, а с
PREBUILT_CACHEкеш, собранный другой версией фреймворка, отклоняется.
Консоль
Заголовок раздела «Консоль»vendor/bin/aspect cache:warmup:aop public/index.phpДля vendor/bin/aspect нужен symfony/console (^7.4 || ^8.0). Установите его через Composer, если в вашем приложении его ещё нет.
Каждая команда принимает путь к файлу, который инициализирует ваше ядро, — обычно это фронт-контроллер или bootstrap-файл. Этот файл выполняется, поэтому команда видит ядро с теми же параметрами, что и ваше приложение. Внутри приложения, которое уже инициализировало ядро (в консоли интеграции с фреймворком, где команды зарегистрированы как сервисы), аргумент опускается: команды используют ядро текущего процесса.
Каждая команда возвращает Command::SUCCESS или Command::FAILURE. В скриптах проверяйте код выхода.
| Команда | Назначение |
|---|---|
cache:warmup:aop |
Компилирует в кеш все файлы внутри include paths. |
cache:warmup:opcache |
Заполняет opcache.file_cache кешем фреймворка и тем, что загружает запрос. |
debug:aspect |
Выводит зарегистрированные behavior classes и их behaviors. |
debug:advisor |
Выводит advisors (каждый behavior с его matching rule) или перехваченные вызовы, которые выбирает один advisor. |
debug:weaving |
Дважды прогревает кеш и сообщает о прокси, сгенерированных по-разному. |
cache:warmup:aop
Заголовок раздела «cache:warmup:aop»rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8Команда компилирует все файлы внутри includePaths (за вычетом excludePaths) и записывает скомпилированные файлы, прокси, кеши advisors и метаданные. Она показывает индикатор прогресса. О каждом файле, который не удалось скомпилировать, она сообщает в stderr и завершается с ненулевым кодом, поэтому скрипт деплоя или docker build останавливается на этом месте, а не выкатывает неполный кеш.
| Опция | По умолчанию | Назначение |
|---|---|---|
--workers=N |
1 (компиляция в процессе команды) |
Компилирует в N параллельных рабочих процессах. Укажите число CPU. |
--cached-files=N |
параметр ядра parsedFilesLimit, 100 |
Сколько разобранных файлов каждый процесс держит в памяти. |
--fail-fast |
выключено | Останавливается на первом файле, который не удалось скомпилировать. |
--cache-dir=DIR |
cacheDir ядра |
Собирает кеш в другом каталоге, с нуля, пока ядро и рабочие процессы продолжают использовать свой. |
--preload[=FILE] |
выключено | Дополнительно записывает скрипт opcache.preload для кеша: _preload.php в каталоге кеша или FILE. |
-v |
выключено | Выводит каждый файл вместо одного индикатора прогресса. |
Замечания об опциях:
--cache-dirпозволяет при деплое подготовить кеш следующего релиза рядом с работающим, а затем атомарно переключиться на него, например заменой символической ссылки. Собранный так кеш полон и не зависит от расположения, даже если его собирает продакшен-ядро с прогретым собственным кешем: компилятор всегда читает исходные файлы, а не скомпилированные, которые отдаёт Composer.--preloadбез значения должна стоять после аргумента loader, иначе она примет loader за своё значение. Скрипт при старте PHP линкует каждый скомпилированный класс и каждый нетрансформированный класс, известный кешу; классы с behavior на статической инициализации остаются автозагрузчику. В скрипте нет абсолютных путей, и он перечисляет классы именно этого кеша, поэтому пересобирайте его вместе с кешем. Настройка предзагрузки описана на странице Продакшен и производительность.- Поверх существующего каталога команда заново компилирует каждый файл, исходник которого изменился (размер или время изменения), и оставляет остальные, в том числе с
PREBUILT_CACHE. Начинайте с пустого каталога, если кеш должен содержать ровно текущий релиз.
cache:warmup:opcache
Заголовок раздела «cache:warmup:opcache»vendor/bin/aspect cache:warmup:opcache public/index.php --file-cache=/var/cache/opcache --entry=public/index.phpКомпилирует в opcache.file_cache то, что загружает продакшен-запрос: кеш фреймворка, карту классов Composer и автозагружаемые файлы, нетрансформированные исходники, загрузочный файл и точки входа. Новый мастер-процесс PHP-FPM или CLI-процесс затем читает скомпилированные скрипты с диска, а не компилирует их.
| Опция | Назначение |
|---|---|
--file-cache=DIR |
Каталог opcache.file_cache. Должен совпадать с настроенным. |
--entry=FILE |
Точка входа для компиляции. Повторите опцию для нескольких файлов. |
Скомпилированные скрипты записываются на диск только процессом, запущенным с -d opcache.enable_cli=1 -d opcache.file_cache_only=1 -d opcache.file_cache=DIR. Если команда запущена без них, она выводит точную команду для запуска.
Файловый кеш привязан к сборке PHP и к абсолютным путям файлов. Запускайте команду в итоговом образе, после cache:warmup:aop, тем же бинарником PHP, который обслуживает запросы. Кеш фреймворка, загрузочный файл и точки входа должны компилироваться, иначе команда завершается с ошибкой; файлы из карты классов Composer, которые не компилируются, выводятся списком и пропускаются.
debug:aspect
Заголовок раздела «debug:aspect»vendor/bin/aspect debug:aspect public/index.phpВыводит зарегистрированные behavior classes и их behaviors. Принимает также опцию --aspect=....
debug:advisor
Заголовок раздела «debug:advisor»vendor/bin/aspect debug:advisor public/index.phpВыводит advisors. С --advisor=... показывает перехваченные вызовы, которые выбирает этот advisor, — так видно, выбирает ли ваше matching rule те методы, которые вы ожидаете.
debug:weaving
Заголовок раздела «debug:weaving»vendor/bin/aspect debug:weaving public/index.phpДважды прогревает кеш и сообщает о прокси, которые в двух прогонах сгенерированы по-разному. Различие указывает на недетерминированный behavior class.
Основы деплоя
Заголовок раздела «Основы деплоя»rm -rf var/cache/aopvendor/bin/aspect cache:warmup:aop public/index.php --workers=8- Очистите каталог кеша.
- Прогрейте кеш командой
cache:warmup:aop. Команда завершается с ошибкой, если какой-то файл не компилируется, поэтому деплой останавливается, а не выкатывает неполный кеш. Большие проекты быстрее компилировать параллельно с--workers. - Запускайте приложение с
'debug' => falseиFeatures::PREBUILT_CACHE.
use Go\Aop\Features;
ApplicationAspectKernel::getInstance()->init([ 'debug' => false, 'appDir' => __DIR__ . '/..', 'cacheDir' => __DIR__ . '/../var/cache/aop', 'includePaths' => [__DIR__ . '/../src'], 'features' => Features::PREBUILT_CACHE,]);Пересобирайте кеш при каждом изменении кода, behavior classes, параметров ядра или composer.lock. На практике это значит — при каждом деплое. В режиме разработки пересборка не нужна.
Настройка OPcache, предзагрузка, флаги автозагрузчика Composer и сборка кеша в Docker-образ описаны на странице Продакшен и производительность. Обновление с 3.x, включая изменение формата кеша, — на странице Ограничения и переход на 4.0.
© 2026 Alexander Lisachenko
