Download the PHP package sarkis-sh/spray-aop without Composer

Spray AOP

A lightweight, high-performance Aspect-Oriented Programming (AOP) package for Laravel, built specifically for PHP 8.2+ Attributes.

Spray AOP enables you to apply cross-cutting concerns to your application classes using native PHP Attributes and dynamically generated proxy classes. It hooks into the Laravel Service Container to automatically resolve proxied versions of your classes whenever aspects are detected, ensuring clean separation of logic with zero manual boilerplate.

Table of Contents

• Features
• Requirements
• Installation
• Publish Configuration
• Configuration
• Usage
  • Create an Aspect and Attribute
  • Example Aspect Attribute
  • Example Aspect Handler
  • Full Examples of Generated Aspects
  • Apply the Attribute
  • How It Works
• Artisan Commands
• Production
• Notes
• License

Features

• Modern AOP: Leverages native PHP 8.2+ Attributes for declarative interception.
• Smart Proxy Engine: Automatic proxy generation with full method signature compatibility.
• Production-Ready: High-performance proxy caching to eliminate runtime I/O overhead.
• Seamless Integration: Automatically swaps target classes within the Laravel Service Container.
• Lifecycle Hooks: Simplified logic through Spray\Aop\Aspects\BaseAspect (Around, Before, After, and Exception hooks).
• Developer Experience: Powerful Artisan commands for proxy management (cache, clear, rebuild).
• Rapid Scaffolding: Built-in generator to create Aspects and Attributes in seconds (spray:make-aspect).

Requirements

• PHP 8.2 or higher
• Laravel 10.0 or higher (compatible with 11.0, 12.0, 13.0)
• Composer for dependency management

Installation

Laravel will auto-discover the provider via Spray\Aop\Providers\AopServiceProvider.

Publish Configuration

This publishes the configuration file to config/spray-aop.php.

Configuration

The published config supports:

• enabled - Enable or disable the AOP engine entirely
• storage_path - Relative storage path for generated proxy classes
• scan_paths - Directories scanned for classes with AOP attributes
• auto_generate - Allow on-the-fly proxy generation when a proxy is missing

Default config values:

Usage

Create an Aspect and Attribute

You can create both using the built-in generator:

The generated files include:

• an Aspect handler class under app/Aspects
• a matching Attribute class under app/Attributes

Command Options

Customize your Aspect and Attribute generation with the following options:

Examples

Generate with before and after hooks on methods:

Generate with exception handling on classes:

Generate a full-featured repeatable Aspect:

Example Aspect Attribute

Example Aspect Handler

The $invocation array contains the following keys:

• 'instance': The object instance being intercepted (the proxied class instance).
• 'method': The name of the method being called (e.g., 'create').
• 'args': An array of arguments passed to the method.
• 'options': The configuration options defined in the attribute (e.g., ['action' => 'user.created']).

Full Examples of Generated Aspects

Here are complete examples of aspects generated with different options using php artisan spray:make-aspect. Each example shows the Aspect class and its corresponding Attribute.

Before Hook Only (--before)

Corresponding Attribute:

After Hook Only (--after)

Exception Hook Only (--exception)

Around Hook (--around)

For full control, use the handle method (around advice):

Combined Hooks (--before --after --exception)

Apply the Attribute

How It Works

• Laravel resolves a service from the container
• Spray AOP inspects the class for AspectAttribute usage
• If aspects exist, it generates or loads a proxy class
• Proxied methods execute through the Spray\Aop\Engines\Pipeline
• Each aspect is executed in order, with support for before, after, and exception handling
• Proxies are generated once and cached as plain PHP files, ensuring near-native execution speed

Artisan Commands

• php artisan spray:aop-cache - Pre-generate all proxy classes for production
• php artisan spray:aop-clear - Remove all generated proxy classes
• php artisan spray:aop-rebuild - Clear and regenerate proxies immediately
• php artisan spray:make-aspect - Generate a new Aspect handler and Attribute

Production

For production deployments, disable runtime generation and cache proxies ahead of time:

Then run:

Notes

• Spray AOP only intercepts public, non-static, non-final, non-constructor methods.
• It ignores Laravel internals and proxy classes to avoid bootstrap recursion.
• The package uses storage/framework/aop/proxies by default for generated PHP files.
• If you change the storage_path in the configuration, ensure the new directory is writable by the web server.

License

MIT — see LICENSE