Aller au contenu
Documentation · Intégrations

Laravel

Du middleware pour n’importe quelle méthode, pas seulement pour les routes. goaop/goaop-laravel-bridge 2.0 attache des behaviors à vos classes, et le conteneur, la configuration et Artisan de Laravel font le reste.

Traduit de l’anglais. La page anglaise fait référence. Lire l’original

Le middleware est l’une des meilleures idées de Laravel. Une requête traverse une pile de petites classes, et chacune ajoute une seule chose (authentification, limitation de débit, session) sans toucher à votre contrôleur. Le bridge goaop/goaop-laravel-bridge 2.0 étend cette idée à chaque méthode et chaque propriété de votre application, qu’elle soit publique, protégée ou privée. Vous écrivez un behavior (comportement) une seule fois, vous indiquez où il s’applique, et il s’exécute autour de ces appels comme un middleware dynamique : dans les services, les actions, les jobs et toute autre classe de app/.

app/Services/OrderService.php
use App\Attributes\Transactional;
final class OrderService
{
public function __construct(private readonly Inventory $inventory) {}
#[Transactional]
public function place(Cart $cart): Order
{
$order = Order::create(['customer_id' => $cart->customerId]);
$order->lines()->createMany($cart->lines());
$this->inventory->reserve($cart);
return $order;
}
}
app/Behaviors/TransactionalBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Illuminate\Support\Facades\DB;
final class TransactionalBehavior implements Aspect
{
#[Around('@execution(App\Attributes\Transactional)')]
public function inTransaction(MethodInvocation $invocation): mixed
{
return DB::transaction(fn () => $invocation->proceed());
}
}

C’est tout le principe. Si vous avez déjà écrit le handle($request, $next) d’un middleware, vous le connaissez : $invocation->proceed() est votre $next($request). Chaque méthode marquée #[Transactional] est désormais validée ou annulée d’un seul bloc, et OrderService ne contient toujours que la logique métier. Vous n’avez besoin ni d’une classe de base, ni d’une interface, ni d’un décorateur, ni d’un appel à app()->extend().

  • S’installe comme n’importe quel autre paquet. Un composer require, et la package discovery enregistre le service provider. Un seul fichier de configuration publiable, config/go_aop.php, avec des surcharges par variables d’environnement GOAOP_*.
  • Les behavior classes (classes de comportement) sont des services du conteneur. Le conteneur Laravel construit chaque behavior class la première fois que l’un de ses behaviors s’exécute. L’injection par constructeur fonctionne, tout comme les facades, config() et chaque service que votre application déclare.
  • Enregistrez-les là où vous enregistrez tout le reste. Listez une classe dans la configuration, ou ajoutez le tag goaop.aspect à un service dans un service provider : un paquet peut ainsi apporter ses propres behaviors.
  • Artisan se charge du travail de production. php artisan aop:warmup construit le cache au déploiement, dans des workers parallèles si vous le souhaitez. Il s’intègre au déploiement que vous lancez déjà, après composer install et php artisan optimize. php artisan about affiche l’emplacement du cache et le mode debug.
  • Aucune étape de build en développement. Avec debug activé, une classe modifiée est recompilée à la requête suivante, et les points d’arrêt fonctionnent dans vos fichiers d’origine.

Ce qu’un behavior atteint et qu’un décorateur ne peut pas atteindre

Section intitulée « Ce qu’un behavior atteint et qu’un décorateur ne peut pas atteindre »

Un décorateur enveloppe un objet que vous résolvez depuis le conteneur : il ne voit donc que les méthodes publiques, et seulement sur ce chemin. Un behavior est attaché à la classe elle-même pendant son chargement, donc :

  • Chaque instance en bénéficie. Les objets issus du conteneur et ceux que vous créez avec new se comportent de la même façon. Les type hints, instanceof et le nom de la classe sont inchangés, car aucun objet enveloppant n’existe.
  • Tous les types de méthodes sont éligibles. Méthodes privées, protégées, final et statiques, et méthodes des classes final et readonly (Intercept anything).
  • Les propriétés aussi. Lectures et écritures de propriétés publiques, protégées et privées, y compris celles promues par le constructeur, grâce aux property hooks natifs de PHP 8.4 : access(private App\Domain\Order->status) ou @access(App\Attributes\Audited) (Behaviors sur les propriétés).
  • Une seule règle peut couvrir un espace de noms. execution(public App\Services\**->*(*)) sélectionne chaque méthode publique sous App\Services, y compris les classes que vous ajouterez le mois prochain (Matching rules).
  • Le coût est faible. Les méthodes et propriétés sans behavior ne coûtent rien de plus. Une méthode ou une propriété dotée d’un behavior paie moins de 1 µs par appel (coûts mesurés).
  • C’est du PHP ordinaire. Aucune extension PECL et aucun eval(). Les classes compilées sont des fichiers .php ordinaires dans storage/framework/aop : vous pouvez les lire (Pure PHP).
  • PHP 8.4 ou plus récent
  • Laravel 12 ou 13
  • goaop/framework ^4.0 (behaviors déclarés par attributs), installé avec le bridge
Fenêtre de terminal
composer require goaop/goaop-laravel-bridge

La package discovery enregistre automatiquement le service provider. Publiez la configuration si vous voulez la modifier :

Fenêtre de terminal
php artisan vendor:publish --tag=goaop-config

Une behavior class (un aspect, dans l’API) est une classe ordinaire qui implémente Go\Aop\Aspect. Chacune de ses méthodes publiques portant #[Before], #[After], #[Around] ou #[AfterThrowing] est un behavior, et la chaîne passée à cet attribut est sa matching rule (règle de correspondance ; un pointcut (point de coupe), dans l’API) : elle indique où le behavior s’exécute.

  1. Créez un attribut pour marquer les méthodes, ou sautez cette étape et sélectionnez les méthodes par leur nom (voir la section suivante).

    app/Attributes/Transactional.php
    namespace App\Attributes;
    use Attribute;
    #[Attribute(Attribute::TARGET_METHOD)]
    final class Transactional {}
  2. Écrivez la behavior class. Le TransactionalBehavior du haut de cette page est complet. #[Around] exécute le behavior à la place de la méthode, et @execution(App\Attributes\Transactional) sélectionne chaque méthode qui porte l’attribut.

  3. Enregistrez la behavior class dans config/go_aop.php :

    config/go_aop.php
    'aspects' => [
    App\Behaviors\TransactionalBehavior::class,
    ],
  4. Marquez une méthode avec #[Transactional] et appelez-la. La requête suivante l’exécute dans une transaction.

Un behavior n’a pas besoin d’un attribut sur sa cible. Une matching rule peut sélectionner des méthodes par nom, espace de noms ou visibilité : toute une couche de l’application reçoit ainsi le behavior sans aucune modification de ses classes.

app/Behaviors/ServiceTimingBehavior.php
namespace App\Behaviors;
use Go\Aop\Aspect;
use Go\Aop\Intercept\MethodInvocation;
use Go\Lang\Attribute\Around;
use Go\Lang\Attribute\Before;
use Illuminate\Support\Facades\Log;
final class ServiceTimingBehavior implements Aspect
{
#[Before('execution(public App\Services\**->*(*))')]
public function logCall(MethodInvocation $invocation): void
{
Log::debug('Calling ' . $invocation->getMethod()->getName());
}
#[Around('execution(public App\Services\PaymentService->charge(*))')]
public function measureCharge(MethodInvocation $invocation): mixed
{
$start = hrtime(true);
try {
return $invocation->proceed();
} finally {
Log::info('charge() took ' . (hrtime(true) - $start) / 1e6 . ' ms');
}
}
}

logCall() s’exécute avant chaque méthode publique sous App\Services. measureCharge() enveloppe une seule méthode et la chronomètre, y compris lorsqu’elle lève une exception. Les quatre attributs, le call context (contexte d’appel, $invocation) et la syntaxe complète des règles sont décrits dans Behaviors et matching rules. Pour des exemples complets pas à pas, voir le behavior de mise en cache et le behavior de journalisation.

Vous ne confiez jamais vous-même les behavior classes au moteur. Pendant la phase de boot, une fois que tous les service providers se sont enregistrés et avant que le code de votre application ne s’exécute, le bridge les collecte à partir de deux sources.

La liste de la configuration. Listez la classe dans config/go_aop.php, comme dans les étapes ci-dessus. Une classe listée est enregistrée dès le démarrage du noyau (kernel), sans que la classe soit chargée. Le conteneur Laravel la résout au premier appel de l’un de ses behaviors : une behavior class peut donc dépendre de services qui n’existent qu’une fois l’application entièrement démarrée. Une requête qui n’exécute aucun de ses behaviors ne l’instancie jamais.

Le tag goaop.aspect. Ajoutez le tag à un service dans l’un de vos service providers :

app/Providers/AppServiceProvider.php
use App\Behaviors\ServiceTimingBehavior;
use Psr\Log\LoggerInterface;
// in register()
$this->app->singleton(ServiceTimingBehavior::class, function ($app) {
return new ServiceTimingBehavior($app->make(LoggerInterface::class));
});
$this->app->tag([ServiceTimingBehavior::class], 'goaop.aspect');

Utilisez le tag lorsqu’une behavior class demande une construction non triviale, ou lorsqu’un paquet apporte des behavior classes sans toucher à votre configuration. Les services taggés sont résolus au boot du provider du bridge, car un tag Laravel ne peut être énuméré qu’en résolvant ses services. Préférez la liste de la configuration pour les behavior classes dont le constructeur est lourd ou dépend du boot.

Vous pouvez combiner les deux sources ; les doublons ne sont enregistrés qu’une fois. Une classe découverte qui n’implémente pas Go\Aop\Aspect échoue avec une exception explicite. Le conteneur Laravel est rattaché au conteneur du noyau en tant que délégué PSR-11 : les behaviors et les factories des behavior classes peuvent donc y chercher les services de l’application.

Les options principales de config/go_aop.php. Chacune peut être surchargée par l’environnement.

Option Valeur par défaut Rôle
debug GOAOP_DEBUG → APP_DEBUG Recompiler quand les sources changent, avec les points d’arrêt dans les fichiers d’origine ; à désactiver en production
appDir base_path() Répertoire racine auquel le compilateur peut toucher
cacheDir storage_path('framework/aop') (GOAOP_CACHE_DIR) Emplacement du cache des sources compilées et des proxies
cacheFileMode 0770 (GOAOP_CACHE_PERMISSIONS, chiffres octaux, par ex. "770") chmod des fichiers de cache
parsedFilesLimit 100 (GOAOP_PARSED_FILES_LIMIT) Fichiers source analysés (environ 0,2 Mo chacun) gardés en mémoire pendant la compilation ; valeur par défaut de aop:warmup --cached-files
includePaths [app_path()] Seuls ces répertoires sont compilés
excludePaths [] Ne jamais compiler ceux-ci
features 0 (GOAOP_FEATURES) Masque de bits des drapeaux Go\Aop\Features : INTERCEPT_INCLUDES = 4, PREBUILT_CACHE = 64, PARTIAL_REFLECTION = 256
aspects [] Behavior classes à enregistrer

Les behaviors sur les appels de fonctions et sur la création d’objets sont pilotés par leurs matching rules et n’ont besoin d’aucun drapeau. php artisan about affiche l’emplacement actuel du cache du framework et le mode debug.

Fenêtre de terminal
php artisan aop:warmup

Sans préchauffage du cache, chaque classe est compilée à son premier chargement. Lancez aop:warmup au déploiement pour toutes les compiler d’avance ; c’est recommandé avec debug désactivé. La commande se termine avec un statut non nul lorsqu’un fichier ne peut pas être compilé, si bien qu’un script de déploiement s’arrête au lieu de livrer un cache incomplet. Passez --fail-fast pour vous arrêter à la première erreur.

Fenêtre de terminal
php artisan aop:warmup --workers=8
php artisan aop:warmup --cache-dir=/srv/app/releases/next/storage/framework/aop
php artisan aop:warmup --preload
  • --workers=N compile dans des processus workers parallèles. Chaque worker est votre propre artisan : il démarre donc avec le même environnement, la même configuration et les mêmes behavior classes.
  • --cache-dir=DIR construit le cache d’une nouvelle release à côté de celle qui tourne. Le cache construit ainsi est complet et indépendant de son emplacement.
  • --preload écrit un script opcache.preload : _preload.php dans le répertoire de cache en cours de construction, ou le fichier indiqué par --preload=FILE.

Pour livrer des scripts compilés avec une image de conteneur, amorcez opcache.file_cache après le préchauffage et après php artisan optimize, dans l’image finale :

Fenêtre de terminal
php artisan optimize
mkdir -p /var/cache/opcache && php -d opcache.enable_cli=1 -d opcache.file_cache_only=1 \
-d opcache.file_cache=/var/cache/opcache \
artisan aop:warmup-opcache --file-cache=/var/cache/opcache
Fenêtre de terminal
composer install --no-dev --optimize-autoloader # runs package:discover, with an empty framework cache
php artisan optimize # the cached configuration carries GOAOP_FEATURES
php artisan aop:warmup

Avec GOAOP_FEATURES=64 (PREBUILT_CACHE), une requête ne compile jamais. Une classe sous les chemins d’inclusion absente du cache échoue avec une WeavingException : lancez donc aop:warmup à chaque déploiement. Les commandes de cache de Laravel (package:discover, optimize, optimize:clear, et les commandes de mise en cache et de vidage de config, event, route et view) ne servent aucune requête : elles chargent donc les classes depuis leur source d’origine. C’est pourquoi l’ordre ci-dessus fonctionne.

Une fois la configuration mise en cache, env() n’est plus lu. Lancez optimize (ou config:cache) avec l’environnement de production, GOAOP_FEATURES compris. La liste de contrôle complète se trouve dans Production et performances.

  • La compile step (étape de compilation) commence au début de la phase de boot. Les classes chargées avant (code de bootstrap très précoce, internes du register() d’autres paquets, vos propres service providers) ne peuvent pas recevoir de behaviors.
  • Seules les classes sous appDir et includePaths sont prises en compte. Le code vendor n’est pas compilé.
  • Excluez les gestionnaires d’exceptions via excludePaths : lors d’une erreur fatale, un gestionnaire compilé peut ne pas être chargeable depuis un cache froid.

© 2026 Alexander Lisachenko