Pular para o conteúdo
Documentação · Integrações

Yii3

Integração com o Yii3 via goaop/goaop-yii3-bridge 1.0: configuração pelo yiisoft/config, behavior classes com tags e ./yii aop:warmup.

Traduzido do inglês. A página em inglês é a referência. Ler o original

A bridge goaop/goaop-yii3-bridge 1.0 se conecta ao yiisoft/config. As suas behavior classes (classes de comportamento) são serviços comuns do container do Yii, e o engine resolve cada uma só quando um dos seus behaviors (comportamentos) roda pela primeira vez.

  • PHP 8.4 ou mais novo
  • Pacotes do Yii3: yiisoft/config, yiisoft/di, yiisoft/aliases (como no template de aplicação)
  • goaop/framework ^4.0 (behaviors declarados com atributos)
Janela do terminal
composer require goaop/goaop-yii3-bridge

O plugin do yiisoft/config incorpora a configuração da bridge. Se você a instalou com o plugin desativado, rode composer yii-config-rebuild.

public/index.php
use App\Environment;
use Go\Yii3\GoAopBridge\AopBootstrap;
use Yiisoft\Yii\Runner\Http\HttpApplicationRunner;
// ...
$runner = new HttpApplicationRunner(
rootPath: dirname(__DIR__),
debug: Environment::appDebug(),
checkEvents: Environment::appDebug(),
environment: Environment::appEnv(),
);
AopBootstrap::init($runner->getConfig(), rootPath: dirname(__DIR__));
$runner->run();

Acrescente a linha AopBootstrap::init() a todo entry script, entre a criação do runner e a sua execução: public/index.php, yii (com o seu ConsoleApplicationRunner e rootPath: __DIR__) e o bootstrap dos seus testes funcionais. Ela lê os parâmetros da bridge e os aliases a partir da configuração do runner. O runner guarda essa configuração, então os parâmetros não são montados duas vezes.

A compile step (etapa de compilação) só se aplica às classes carregadas depois que o kernel inicia, e o runner do Yii carrega classes pelo autoloader enquanto monta o container. Se você pular essa linha, o grupo de configuração bootstrap da bridge ainda inicia o kernel, mas tarde: as classes carregadas durante a montagem do container não são compiladas. Em modo debug, isso inclui toda classe com uma definição em array, então a aplicação se comportaria de forma diferente em desenvolvimento e em produção.

<?php
declare(strict_types=1);
namespace App\Aspect;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Psr\Log\LoggerInterface;
final readonly class LoggingAspect implements Aspect
{
public function __construct(private LoggerInterface $logger) {}
#[Before('execution(public App\Service\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
$this->logger->debug('Calling {method}', ['method' => $invocation->getMethod()->getName()]);
}
#[Around('execution(public App\Service\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
$this->logger->info('charge() took {ms}ms', ['ms' => (hrtime(true) - $start) / 1e6]);
}
}
}

Liste as behavior classes no parâmetro aspects:

config/common/params.php
'goaop/goaop-yii3-bridge' => [
'aspects' => [
App\Aspect\LoggingAspect::class,
App\Aspect\AuditAspect::class,
],
],

Argumentos de construtor que não podem ser resolvidos por autowiring vêm de uma definição no container, como para qualquer outro serviço:

use App\Aspect\AuditAspect;
use Yiisoft\Definitions\Reference;
return [
AuditAspect::class => [
'__construct()' => [
'logger' => Reference::to('auditLogger'),
'level' => $params['app']['auditLevel'],
],
],
];

Como uma behavior class é resolvida:

  1. Nada é carregado pelo autoloader quando o kernel inicia: os nomes das classes só são validados sintaticamente.
  2. Quando o compilador precisa dos behaviors de uma classe, ele os lê da classe via reflection. O objeto da behavior class é um lazy proxy nativo e ainda não foi construído.
  3. Na primeira chamada de um dos seus behaviors, o proxy é inicializado com $container->get(AspectClass::class), a instância compartilhada do container do Yii.

Uma behavior class que depende de uma conexão com o banco de dados ou de um cliente HTTP não os cria em requisições que nunca chegam a um método com behavior. Em modo debug, a bridge verifica se cada classe listada existe e implementa Go\Aop\Aspect.

Um pacote pode contribuir com behavior classes a partir do seu próprio config/params.php. O grupo params é mesclado recursivamente, as listas são concatenadas e as duplicatas são registradas uma única vez:

config/params.php
return [
'goaop/goaop-yii3-bridge' => [
'aspects' => [
Vendor\Package\Aspect\CacheAspect::class,
],
],
];

Defina 'aspectTag' => 'goaop.aspect'. Depois, adicione a tag às definições do grupo de configuração comum di ('tags' => ['goaop.aspect']), ou liste-as em um mapa de tags comum di-tags (['goaop.aspect' => [LoggingAspect::class]]). Os serviços com a tag precisam estar registrados pelo nome da classe.

Essa busca vem desligada por padrão por causa do seu custo. A bridge lê as declarações de tags dos arquivos de configuração antes que o kernel inicie, então toda classe que esses arquivos referenciam (por uma constante de classe ou um case de enum, por exemplo) é carregada nesse momento e não pode mais ser compilada. Só os grupos comuns são lidos. As tags de definições di-web/di-console, os mapas di-tags-web/di-tags-console e os service providers não são considerados.

Os padrões ficam no grupo params da bridge. Sobrescreva-os em config/common/params.php, ou por ambiente em config/environments/<env>/params.php.

Parâmetro Padrão Finalidade
debug null Recompila quando os fontes ou as behavior classes mudam. null segue GOAOP_DEBUG e, depois, APP_DEBUG. Mantenha desligado em produção.
appDir '@root' Raiz da aplicação; só os arquivos abaixo dela são compilados.
cacheDir null Fontes compilados, proxies e caches de advisors. null segue GOAOP_CACHE_DIR (um alias é permitido) e, depois, '@runtime/aop'.
cacheFileMode null Permissões dos arquivos de cache: um inteiro (0770) ou dígitos octais ('770'). null significa 0770 menos a umask.
features 0 Bitmask de flags de Go\Aop\Features: PREBUILT_CACHE, PARTIAL_REFLECTION, INTERCEPT_INCLUDES.
includePaths ['@src'] Só estes diretórios são compilados. Mantenha a lista restrita.
excludePaths [] Nunca compilados. O diretório de cache e o framework são sempre excluídos.
parsedFilesLimit null Arquivos analisados mantidos em memória durante a compilação; também é o padrão de aop:warmup --cached-files. null significa o padrão do kernel (100).
aspects [] Behavior classes, resolvidas de forma lazy a partir do container do Yii.
aspectTag null Tag opcional de container que registra behavior classes, p. ex. 'goaop.aspect'.

Um parâmetro malformado falha logo, com uma mensagem que o identifica. O kernel está disponível no container como Go\Core\AspectKernel (e Go\Yii3\GoAopBridge\Kernel\AspectYii3Kernel), e o container dele como Go\Core\AspectContainer. Depois que o callback bootstrap roda, o container do kernel delega os ids desconhecidos ao container do Yii.

Com o yiisoft/yii-console instalado, a bridge acrescenta estes comandos ao ./yii:

Comando Finalidade
./yii aop:warmup Compila para o cache todas as classes abaixo dos include paths. --fail-fast, --workers=N, --cache-dir=DIR, --preload[=FILE], --cached-files=N.
./yii aop:opcache Pré-aquece o file cache do opcache com o cache do framework, a aplicação e a sua configuração, depois do aop:warmup.
./yii aop:debug:aspect Lista as behavior classes com suas matching rules (regras de correspondência) e advisors (--aspect=... para uma só).
./yii aop:debug:advisor Lista os advisors, ou aquilo que um advisor seleciona (--advisor=...).
./yii aop:debug:weaving Compila duas vezes e reporta os proxies que diferem, o que revela dependências circulares entre behavior classes e classes compiladas.

Estes são os comandos do próprio framework, registrados no namespace aop. Eles rodam sobre o kernel que a linha de entrada inicializou, então omita o argumento opcional loader. Os workers de --workers=N executam o ./yii de novo e precisam da linha de entrada. Quando foi o fallback bootstrap que iniciou o kernel, o comando compila no próprio processo e avisa isso.

Janela do terminal
./yii aop:warmup --workers=4

Em produção, desligue o debug e gere o cache no deploy. --cache-dir=DIR gera o cache em outro diretório enquanto o kernel continua usando o seu. Os arquivos de cache são independentes de localização, então você pode mover o diretório para o lugar definitivo.

Dockerfile
ENV GOAOP_CACHE_DIR=/app/aop
RUN ./yii aop:warmup --workers=4 --preload

Em sistemas de arquivos somente leitura, acrescente Features::PREBUILT_CACHE a features. O engine então confia totalmente no cache e nunca grava nele, então gere-o de novo a cada deploy. Uma classe abaixo dos include paths que o cache não conhece falha com uma Go\Aop\Exception\WeavingException. O próprio processo do aop:warmup fica isento, para poder compilar essas classes para o cache.

Com o opcache, ./yii aop:warmup --preload grava _preload.php no diretório de cache para o opcache.preload, e ./yii aop:opcache pré-aquece o file cache na imagem final:

Janela do terminal
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
./yii aop:opcache --file-cache=/var/cache/opcache
  • Só as classes abaixo de appDir e includePaths são compiladas. Código de vendor, não.
  • Classes carregadas antes de AopBootstrap::init(), como App\Environment, não podem ser compiladas. Nem as classes que a configuração carrega enquanto a linha de entrada a lê.
  • As próprias behavior classes não precisam ser compiladas: exclua o diretório delas, p. ex. 'excludePaths' => ['@src/Aspect'].
  • Quando criar uma behavior class executa um dos seus próprios behaviors, esse behavior falha com uma Go\Aop\Exception\AspectCircularReferenceException. Injete essa dependência de forma lazy (uma closure ou Psr\Container\ContainerInterface) ou restrinja a matching rule.
  • O kernel é global no processo. Workers de longa duração (RoadRunner, Swoole, FrankenPHP) o inicializam uma vez por worker. Faça o reset das behavior classes que guardam estado por requisição como faria com qualquer outro serviço compartilhado.

© 2026 Alexander Lisachenko