Macro Laravel Package

Getting Started

Start by requiring the package via Composer: composer require aimeos/macro. The core concept is enabling dynamic method injection on any class or object using closures. The package provides a Macroable trait—attach it to any class to gain macro capabilities. First use case: define custom string manipulation methods on the Str class or your own domain-specific classes without subclassing.

use Aimeos\Macro\Macroable;

class TextProcessor
{
    use Macroable;
}

TextProcessor::macro('capitalizeWords', function ($str) {
    return ucwords($str);
});

$processor = new TextProcessor();
echo $processor->capitalizeWords('hello world'); // "Hello World"

Check the src/ folder for the Macroable trait implementation and the tests/ for real-world examples.

Implementation Patterns

• Static Macros: Register macros on classes using ClassName::macro('name', $closure) during application boot (e.g., in AppServiceProvider).
• Instance-Level Macros: Attach macros directly to object instances via instance()->macro()—useful for runtime-specific customization.
• Dynamic Dispatch: Implement custom DSL-like interfaces by chaining macros across objects (e.g., query builders, formatters).
• Conditional Macros: Register macros only when certain conditions are met (e.g., Laravel version, environment, feature flag).
• Macro Registration Containers: Create dedicated macro providers that group related functionality (e.g., App\Macros\DateTimeMacros).

For Laravel apps, bind macros inside service providers or use auto-discovery via MacroServiceProvider pattern. Keep macros short, focused, and side-effect-free.

Gotchas and Tips

• Macro names conflict silently—use unique prefixes (e.g., myapp_) to avoid collision with native methods or future PHP features.
• Macros defined on static methods don’t automatically inherit to child classes unless static::class is used inside the closure—test inheritance carefully.
• Debugging macros: method_exists() and is_callable() work, but ReflectionMethod won’t show macros unless you implement custom reflection logic.
• Performance: Macros add negligible overhead, but avoid expensive closures in hot paths; cache results if needed.
• To extend third-party classes (e.g., Laravel’s Collection), use Macroable trait (if supported) or monkey-patch via service provider—but prefer composition over macro injection when possible.
• The package relies on PHP’s __call() magic method; ensure your IDE supports auto-completion for macros via @method annotations or IDE helper packages.