Перейти к содержимому
Документация

Начало работы

Установите фреймворк через 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.

Начало работы укладывается в пять шагов:

  1. Установить фреймворк через Composer.
  2. Создать ядро (kernel) приложения.
  3. Инициализировать ядро во фронт-контроллере.
  4. Написать behavior class.
  5. Зарегистрировать behavior class в ядре.
Окно терминала
composer require goaop/framework

Composer установит фреймворк в vendor/goaop/framework.

Примеры на этой странице используют такую структуру каталогов. Предполагается, что Composer автозагружает классы из app/ и src/, например через секцию autoload вашего composer.json.

app/ApplicationAspectKernel.php the kernel
public/index.php the front controller
src/ your application code, compiled by the framework
src/Aspect/MonitorAspect.php your first behavior class
var/cache/aop/ the cache of generated code
app/ApplicationAspectKernel.php
<?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.

public/index.php
<?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.

src/Aspect/MonitorAspect.php
<?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.

app/ApplicationAspectKernel.php
<?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:

src/Example.php
<?php
class Example
{
public function greet(string $name): string
{
return "Hello, {$name}";
}
}

Затем используйте его во фронт-контроллере после init():

public/index.php
<?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/console
vendor/bin/aspect debug:aspect public/index.php

debug:aspect выводит зарегистрированные behavior classes и их behaviors. Каждая команда bin/aspect принимает путь к файлу, который инициализирует ваше ядро (здесь это фронт-контроллер), и выполняет этот файл. debug:advisor --advisor=... показывает перехваченные вызовы, которые выбирает один advisor (behavior вместе с его matching rule). Обращайтесь к этим командам, когда behavior не выполняется.

Ваши классы компилируются, когда 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. Парсер и трансформеры на тёплых запросах не загружаются.

Для деплоя соберите кеш один раз и скажите ядру полностью ему доверять:

  1. Очистите каталог кеша.

  2. Прогрейте кеш:

    Окно терминала
    vendor/bin/aspect cache:warmup:aop public/index.php

    Команда завершается с ошибкой, если какой-то файл не компилируется, поэтому скрипт деплоя остановится, а не выкатит неполный кеш. Большие проекты быстрее компилировать параллельно, например с --workers=8.

  3. Запускайте приложение с '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? Сначала прочитайте страницу Ограничения и переход на 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