Начало работы
Установите фреймворк через Composer, создайте ядро, напишите первое поведение и посмотрите, как оно выполняется вокруг вашего кода.
Перевод с английского. Эталоном считается английская версия страницы. Читать оригинал
Вы один раз пишете behavior (поведение) — логирование, кеширование, проверку прав или транзакцию, — и фреймворк подключает его как динамический middleware (промежуточный слой) к каждому выбранному вами методу. В коде behaviors живут в behavior class (класс поведений), который в API называется aspect (аспект): каждый behavior — это метод, атрибут которого говорит, когда он выполняется, и содержит matching rule (правило выбора), которое говорит, где. В ваших классах остаётся только бизнес-логика. Таблица терминов сопоставляет названия из API со словами, которые используются в этой документации.
Требования
Заголовок раздела «Требования»- PHP 8.4 или новее. Работает на всех современных версиях PHP.
- Никаких расширений PECL или PIE. Это чистый PHP: без
php-aop,runkitилиuopzи безeval(). Используется расширениеtokenizer. - Composer. Фреймворк и его зависимости устанавливаются как обычные пакеты Composer.
Начало работы укладывается в пять шагов:
- Установить фреймворк через Composer.
- Создать ядро (kernel) приложения.
- Инициализировать ядро во фронт-контроллере.
- Написать behavior class.
- Зарегистрировать behavior class в ядре.
Установка через Composer
Заголовок раздела «Установка через Composer»composer require goaop/frameworkComposer установит фреймворк в vendor/goaop/framework.
Примеры на этой странице используют такую структуру каталогов. Предполагается, что Composer автозагружает классы из app/ и src/, например через секцию autoload вашего composer.json.
app/ApplicationAspectKernel.php the kernelpublic/index.php the front controllersrc/ your application code, compiled by the frameworksrc/Aspect/MonitorAspect.php your first behavior classvar/cache/aop/ the cache of generated codeСоздание ядра
Заголовок раздела «Создание ядра»<?php
use Go\Core\AspectContainer;use Go\Core\AspectKernel;
/** * The application kernel */class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { }}Ядро управляет всеми behavior classes приложения в одном месте. Унаследуйте абстрактный класс Go\Core\AspectKernel и реализуйте configureAop(). Пока метод остаётся пустым; ниже вы зарегистрируете в нём первый behavior class.
Инициализация ядра во фронт-контроллере
Заголовок раздела «Инициализация ядра во фронт-контроллере»<?php
include __DIR__ . '/../vendor/autoload.php'; // use composer
// Initialize the kernel$applicationAspectKernel = ApplicationAspectKernel::getInstance();$applicationAspectKernel->init([ 'debug' => true, // use 'false' for production mode 'appDir' => __DIR__ . '/..', // Application root directory 'cacheDir' => __DIR__ . '/../var/cache/aop', // Cache directory // Directories whose classes get behaviors; empty means all source files 'includePaths' => [ __DIR__ . '/../src/' ]]);
// Your application starts hereВызовите init() один раз — сразу после автозагрузчика Composer и до того, как приложение загрузит собственные классы. Для начала хватит четырёх параметров:
| Параметр | Назначение |
|---|---|
debug |
true включает режим разработки. В продакшене используйте false. |
appDir |
Корень приложения. Компилируются только файлы внутри него. По умолчанию — каталог, в котором лежит vendor/. |
cacheDir |
Куда записывается сгенерированный код. Обязательный параметр. |
includePaths |
Каталоги для компиляции. Пустой массив означает всё внутри appDir. |
Держите includePaths узким: компиляция кода из vendor медленная и редко бывает нужна. Неизвестный ключ параметра выбрасывает Go\Aop\Exception\InvalidConfigurationException, так что опечатка сразу приводит к ошибке, а не игнорируется молча. Полный список параметров — на странице Конфигурация и CLI.
Первый behavior
Заголовок раздела «Первый behavior»<?php
namespace Aspect;
use Go\Aop\Aspect;use Go\Aop\Intercept\MethodInvocation;use Go\Lang\Attribute\Before;
/** * A monitoring behavior class */class MonitorAspect implements Aspect{ /** * Method that will be called before real method */ #[Before("execution(public Example->*(*))")] public function beforeMethodExecution(MethodInvocation $invocation): void { echo 'Calling Before Interceptor for: ', $invocation, ' with arguments: ', json_encode($invocation->getArguments()), "<br>\n"; }}Behavior class — это обычный PHP-класс, реализующий Go\Aop\Aspect. Каждый behavior — публичный метод с одним атрибутом из Go\Lang\Attribute, который говорит, когда этот behavior выполняется.
- Behavior с
#[Before]выполняется перед перехваченным вызовом. Остальные атрибуты —#[After],#[AfterThrowing]и#[Around]. - Строка в атрибуте — это matching rule.
execution(public Example->*(*))выбирает выполнение каждого публичного нестатического метода классаExample. - Behavior получает
MethodInvocation— перехваченный вызов:getArguments()возвращает его аргументы, а при приведении к строке объект даёт имя метода.
Методы behaviors должны быть public. Фреймворк вызывает их напрямую на экземпляре behavior class, поэтому метод behavior с модификатором protected или private отклоняется при загрузке класса. На методе может быть не больше одного атрибута behavior.
Регистрация behavior class
Заголовок раздела «Регистрация behavior class»<?php
use Aspect\MonitorAspect;use Go\Core\AspectContainer;use Go\Core\AspectKernel;
class ApplicationAspectKernel extends AspectKernel{ /** * Register the behavior classes in the container */ protected function configureAop(AspectContainer $container): void { // Deferred (recommended): constructed on first use $container->addLazyService(MonitorAspect::class, static fn() => new MonitorAspect()); }}Behavior class — это сервис контейнера ядра. addLazyService() регистрирует фабрику. Compile step (этап компиляции) только читает behavior class, поэтому фабрика запускается, когда впервые выполняется один из его behaviors, и не раньше.
Если вы предпочитаете создать behavior class заранее, зарегистрируйте готовый экземпляр:
$container->add(MonitorAspect::class, new MonitorAspect());Behavior classes могут также получать зависимости из PSR-11-контейнера вашего приложения: его подключают к контейнеру ядра через setDelegate(). Как это сделать, показано на странице Конфигурация и CLI.
Проверяем в работе
Заголовок раздела «Проверяем в работе»Добавьте класс, который выберет matching rule:
<?php
class Example{ public function greet(string $name): string { return "Hello, {$name}"; }}Затем используйте его во фронт-контроллере после init():
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();echo $example->greet('World');Откройте страницу в браузере или выполните php public/index.php. Перед Hello, World появится строка от behavior с именем метода и его аргументами ["World"]. В Example нет ни одной ссылки на behavior class: behavior подключился к классу, когда автозагрузчик загрузил и скомпилировал его.
Вы никогда не вызываете behavior сами. Чтобы изменить набор методов, для которых он выполняется, вы меняете matching rule, а не классы. На странице Поведения и правила выбора описано, когда выполняется каждый вид behavior, и приведён полный синтаксис matching rules.
Что зарегистрировано
Заголовок раздела «Что зарегистрировано»Консоли bin/aspect нужен symfony/console:
composer require symfony/consolevendor/bin/aspect debug:aspect public/index.phpdebug:aspect выводит зарегистрированные behavior classes и их behaviors. Каждая команда bin/aspect принимает путь к файлу, который инициализирует ваше ядро (здесь это фронт-контроллер), и выполняет этот файл. debug:advisor --advisor=... показывает перехваченные вызовы, которые выбирает один advisor (behavior вместе с его matching rule). Обращайтесь к этим командам, когда behavior не выполняется.
Как работает compile step
Заголовок раздела «Как работает compile step»Ваши классы компилируются, когда PHP их загружает. Во время выполнения ничто не оборачивает ваши объекты, и никакой код не генерируется через eval(). Каждый скомпилированный класс — это обычный PHP-файл в каталоге кеша, и именно этот файл выполняет PHP.
Сгенерированный код
Заголовок раздела «Сгенерированный код»При компиляции класса его исходное тело переносится в трейт. Сгенерированный класс с исходным именем использует этот трейт, поэтому имя класса, его родители и self:: остаются прежними. Каждый перехваченный метод получает call context (контекст вызова) со своими behaviors:
static $__joinPoint = InterceptorInjector::forMethod( self::class, 'doSomething', [ Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)), ], $this->doSomethingOriginalAlias(...),);The::aspect() получает экземпляр behavior class из контейнера ядра. ->beforeMethodExecution(...) — написанный вами метод behavior, на который ссылаются через синтаксис first-class callable. По нему можно перейти Ctrl-кликом в IDE, поставить внутри точку останова и пройти сгенерированный код по шагам. Последний аргумент указывает на исходное тело метода.
Номера строк сохраняются, поэтому точки останова Xdebug в исходном коде продолжают работать. Атрибуты класса, его методов, параметров, констант и свойств копируются в сгенерированный код, так что чтение их через рефлексию работает как прежде. Методы, которые не выбирает ни одно matching rule, выполняются без всякого кода перехвата.
Каталог кеша
Заголовок раздела «Каталог кеша»В cacheDir лежат скомпилированные исходники, прокси, кеши advisors и карта классов. Пути в кеше повторяют пути исходников относительно appDir. Это обычные PHP-файлы: их можно открыть, сравнить и проверить своими инструментами безопасности.
Не коммитьте каталог кеша. В разработке фреймворк заполняет его по мере загрузки классов, в продакшене кеш собирается во время деплоя.
Режим разработки
Заголовок раздела «Режим разработки»С 'debug' => true каждый класс и каждый include загружается через stream filter фреймворка, который и компилирует код. Изменения файла ядра и файлов behavior classes инвалидируют кеш, а изменённые файлы компилируются заново при следующем запросе. Шага сборки нет: отредактируйте класс или behavior и перезагрузите страницу.
На горячих запросах режим разработки заметно медленнее продакшен-режима. Не используйте его в продакшене.
Продакшен-режим
Заголовок раздела «Продакшен-режим»С 'debug' => false скомпилированные классы загружаются из кеша через карту классов Composer. Парсер и трансформеры на тёплых запросах не загружаются.
Для деплоя соберите кеш один раз и скажите ядру полностью ему доверять:
-
Очистите каталог кеша.
-
Прогрейте кеш:
Окно терминала vendor/bin/aspect cache:warmup:aop public/index.phpКоманда завершается с ошибкой, если какой-то файл не компилируется, поэтому скрипт деплоя остановится, а не выкатит неполный кеш. Большие проекты быстрее компилировать параллельно, например с
--workers=8. -
Запускайте приложение с
'debug' => falseи флагомPREBUILT_CACHE:public/index.php use Go\Aop\Features;ApplicationAspectKernel::getInstance()->init(['debug' => false,'appDir' => __DIR__ . '/..','cacheDir' => __DIR__ . '/../var/cache/aop','includePaths' => [__DIR__ . '/../src'],'features' => Features::PREBUILT_CACHE,]);
С PREBUILT_CACHE запрос никогда не компилирует код и никогда не пишет в каталог кеша, поэтому работает и на файловой системе только для чтения. Кеш должен быть полным: класс внутри include paths, о котором в кеше нет записи, роняет запрос с WeavingException. Пересобирайте кеш при каждом изменении кода или behavior classes.
OPcache, предзагрузка, Docker и Kubernetes описаны на странице Продакшен и производительность.
Что дальше
Заголовок раздела «Что дальше»Если вы используете фреймворк
Заголовок раздела «Если вы используете фреймворк»Если ваше приложение работает на Symfony, Laravel или Yii3, установите для него мост вместо того, чтобы писать код фронт-контроллера самостоятельно. Мост запускает ядро на раннем этапе жизненного цикла приложения и позволяет регистрировать behavior classes как сервисы контейнера вашего фреймворка. См. страницу Интеграции или репозитории goaop/goaop-symfony-bundle, goaop/goaop-laravel-bridge и goaop/goaop-yii3-bridge.
Обновление с 3.x
Заголовок раздела «Обновление с 3.x»Обновляете приложение с версии 3.x? Сначала прочитайте страницу Ограничения и переход на 4.0: там перечислены все изменения.
ИИ-агенты для разработки
Заголовок раздела «ИИ-агенты для разработки»Репозиторий фреймворка — это маркетплейс плагинов для агентов программирования. Его плагин goaop содержит Agent Skill, который учит агента писать behavior classes, behaviors и matching rules, интегрировать фреймворк, деплоить кеш и выяснять, почему behavior не выполняется. В Claude Code:
/plugin marketplace add goaop/framework/plugin install goaop@goaop© 2026 Alexander Lisachenko
