Ir al contenido
Documentación

Primeros pasos

Instala el framework con Composer, crea un kernel, escribe tu primer behavior y míralo ejecutarse alrededor de tu código.

Traducido del inglés. La página en inglés es la referencia. Leer el original

Escribes un behavior (comportamiento), como logging, caché, una comprobación de seguridad o una transacción, una sola vez, y el framework lo adjunta como middleware dinámico a cada método que selecciones. En el código, los behaviors viven en una behavior class (clase de comportamiento; un aspect (aspecto), en la API): cada behavior es un método cuyo atributo indica cuándo se ejecuta y que contiene una matching rule (regla de coincidencia) que indica dónde. Tus clases conservan solo su lógica de negocio. La tabla de términos relaciona los nombres de la API con las palabras que usa esta documentación.

  • PHP 8.4 o posterior. Funciona en todas las versiones modernas de PHP.
  • Ninguna extensión PECL ni PIE. Es PHP puro: sin php-aop, runkit ni uopz, y sin eval(). Usa la extensión tokenizer.
  • Composer. El framework y sus dependencias se instalan como paquetes normales de Composer.

Empezar lleva cinco pasos:

  1. Instala el framework con Composer.
  2. Crea el kernel de la aplicación.
  3. Inicializa el kernel en el controlador frontal.
  4. Escribe una behavior class.
  5. Registra la behavior class en el kernel.
Ventana de terminal
composer require goaop/framework

Composer instala el framework en vendor/goaop/framework.

Los ejemplos de esta página usan la siguiente estructura. Dan por hecho que Composer carga automáticamente las clases de app/ y src/, por ejemplo mediante la sección autoload de tu 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
{
}
}

El kernel gestiona en un solo lugar todas las behavior classes de tu aplicación. Extiende la clase abstracta Go\Core\AspectKernel e implementa configureAop(). Por ahora queda vacío; más abajo registrarás en él tu primera behavior class.

Inicializa el kernel en el controlador frontal

Sección titulada «Inicializa el kernel en el controlador frontal»
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

Llama a init() una sola vez, justo después del autoloader de Composer y antes de que tu aplicación cargue sus propias clases. Estas cuatro opciones bastan para empezar:

Opción Para qué sirve
debug true activa el modo de desarrollo. Usa false en producción.
appDir La raíz de la aplicación. Solo se compilan los archivos que están por debajo. Por defecto es el directorio que contiene vendor/.
cacheDir Dónde se escribe el código generado. Esta opción es obligatoria.
includePaths Los directorios que se compilan. Un array vacío significa todo lo que hay por debajo de appDir.

Mantén includePaths acotado. Compilar el código de vendor es lento y rara vez hace falta. Una clave de opción desconocida lanza Go\Aop\Exception\InvalidConfigurationException, así que una errata falla en el acto en lugar de pasar inadvertida. La lista completa de opciones está en la página Configuración y 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";
}
}

Una behavior class es una clase PHP normal que implementa Go\Aop\Aspect. Cada behavior es un método público con un atributo de Go\Lang\Attribute que indica cuándo se ejecuta.

  • Un behavior #[Before] se ejecuta antes de la llamada interceptada. Los otros atributos son #[After], #[AfterThrowing] y #[Around].
  • La cadena del atributo es la matching rule. execution(public Example->*(*)) selecciona la ejecución de todos los métodos públicos y no estáticos de la clase Example.
  • El behavior recibe un MethodInvocation, que te da la llamada interceptada: getArguments() devuelve sus argumentos, y la invocación se convierte en una cadena que nombra el método.

Los métodos de behavior deben ser public. El framework los llama directamente sobre la instancia de la behavior class, así que un método de behavior protected o private se rechaza al cargar la clase. Un método lleva como máximo un atributo de 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());
}
}

Una behavior class es un servicio del contenedor del kernel. addLazyService() registra una factoría. El compile step (paso de compilación) solo lee la behavior class, así que la factoría se ejecuta cuando uno de sus behaviors se ejecuta por primera vez, no antes.

Si prefieres crear la behavior class de antemano, registra una instancia:

$container->add(MonitorAspect::class, new MonitorAspect());

Las behavior classes también pueden obtener sus dependencias del contenedor PSR-11 de tu aplicación, que conectas al contenedor del kernel con setDelegate(). La página Configuración y CLI explica cómo.

Añade una clase para que la matching rule la seleccione:

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

Después úsala en el controlador frontal, tras init():

public/index.php
<?php
include __DIR__ . '/../vendor/autoload.php';
ApplicationAspectKernel::getInstance()->init([/* … as above … */]);
$example = new Example();
echo $example->greet('World');

Abre la página en el navegador o ejecuta php public/index.php. Antes de Hello, World verás la línea del behavior, con el nombre del método y sus argumentos ["World"]. Example no tiene ninguna referencia a la behavior class. El behavior se adjuntó a la clase cuando el autoloader la cargó y la compiló.

Nunca llamas al behavior tú mismo. Para cambiar los métodos en los que se ejecuta, cambias la matching rule, no las clases. La página Behaviors y matching rules explica cuándo se ejecuta cada behavior y la sintaxis completa de las matching rules.

La consola bin/aspect necesita symfony/console:

Ventana de terminal
composer require symfony/console
vendor/bin/aspect debug:aspect public/index.php

debug:aspect lista las behavior classes registradas y sus behaviors. Todos los comandos de bin/aspect reciben la ruta del archivo que inicializa tu kernel, aquí el controlador frontal, y ejecutan ese archivo. debug:advisor --advisor=... muestra las llamadas interceptadas que coinciden con un advisor (un behavior con su matching rule). Usa estos comandos cuando un behavior no se ejecuta.

Tus clases se compilan cuando PHP las carga. Nada envuelve tus objetos en tiempo de ejecución, y no se genera código con eval(). Cada clase compilada es un archivo PHP normal en el directorio de caché, y ese archivo es lo que PHP ejecuta.

En una clase compilada, el cuerpo original de la clase pasa a un trait. Una clase generada con el nombre original usa ese trait, de modo que el nombre de la clase, sus padres y self:: siguen igual. Cada método interceptado recibe un call context (contexto de llamada) con sus behaviors:

static $__joinPoint = InterceptorInjector::forMethod(
self::class,
'doSomething',
[
Interceptor::before(The::aspect(MonitorAspect::class)->beforeMethodExecution(...)),
],
$this->doSomethingOriginalAlias(...),
);

The::aspect() obtiene la instancia de la behavior class del contenedor del kernel. ->beforeMethodExecution(...) es el método de behavior que escribiste, referenciado con la sintaxis de first-class callable. Puedes hacer Ctrl-clic sobre él en tu IDE, poner un breakpoint dentro y recorrer paso a paso el código generado. El último argumento apunta al cuerpo del método original.

Los números de línea se conservan, así que los breakpoints de Xdebug en tu código original siguen funcionando. Los atributos de la clase, de sus métodos, parámetros, constantes y propiedades se copian al código generado, de modo que leerlos por reflexión funciona como antes. Los métodos que ninguna matching rule selecciona se ejecutan sin ningún código de interceptación.

cacheDir contiene los fuentes compilados, los proxies, las cachés de advisors y el class map. Las rutas de la caché reflejan las rutas de los fuentes relativas a appDir. Los archivos son PHP normal, así que puedes abrirlos, compararlos con diff y analizarlos con tus herramientas de seguridad.

No hagas commit del directorio de caché. En desarrollo, el framework lo llena a medida que se cargan las clases. En producción, lo construyes en el despliegue.

Con 'debug' => true, cada clase y cada include se cargan a través del stream filter del framework, que los compila. Los cambios en el archivo del kernel y en los archivos de behavior classes invalidan la caché, y los archivos modificados se vuelven a compilar en la siguiente petición. No hay paso de build: edita una clase o un behavior y recarga la página.

El modo de desarrollo es notablemente más lento que el de producción en las peticiones hot (calientes). No lo uses en producción.

Con 'debug' => false, las clases compiladas se cargan desde la caché a través del class map de Composer. El parser y los transformadores no se cargan en las peticiones warm (templadas).

Para desplegar, construye la caché una vez e indica al kernel que confíe en ella:

  1. Vacía el directorio de caché.

  2. Precalienta la caché:

    Ventana de terminal
    vendor/bin/aspect cache:warmup:aop public/index.php

    El comando falla cuando un archivo no se puede compilar, así que un script de despliegue se detiene en lugar de publicar una caché incompleta. Los proyectos grandes compilan más rápido en paralelo, por ejemplo con --workers=8.

  3. Ejecuta con 'debug' => false y la feature 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,
    ]);

Con PREBUILT_CACHE, una petición nunca compila ni escribe en el directorio de caché, así que también funciona en un sistema de archivos de solo lectura. La caché debe estar completa: una clase dentro de las include paths de la que la caché no tiene registro hace fallar la petición con una WeavingException. Reconstruye la caché cada vez que cambien el código o las behavior classes.

La página Producción y rendimiento trata OPcache, el preloading, Docker y Kubernetes.

Si tu aplicación funciona sobre Symfony, Laravel o Yii3, instala su bridge en lugar de escribir tú el código del controlador frontal. El bridge arranca el framework al principio del ciclo de vida de la aplicación y te permite registrar las behavior classes como servicios del contenedor de tu framework. Consulta la página Integraciones o los repositorios goaop/goaop-symfony-bundle, goaop/goaop-laravel-bridge y goaop/goaop-yii3-bridge.

¿Vas a actualizar una aplicación desde la versión 3.x? Lee primero la página Limitaciones y actualización. Enumera todos los cambios.

El repositorio del framework es un marketplace de plugins para agentes de programación. Su plugin goaop incluye una Agent Skill que enseña a un agente a escribir behavior classes, behaviors y matching rules, a integrar el framework, a desplegar la caché y a averiguar por qué un behavior no se ejecuta. En Claude Code:

/plugin marketplace add goaop/framework
/plugin install goaop@goaop

© 2026 Alexander Lisachenko