README

Powerful macro system for runtime class extension in PHP with comprehensive management capabilities.

Overview

The Macros component provides a sophisticated system for dynamically extending classes at runtime using closures and callables. It enables powerful extension patterns, domain-specific languages, and flexible API design through the Macroable trait and comprehensive macro management tools.

Features

Macroable Trait: Add dynamic methods to any class at runtime
Rich Macro Objects: Full-featured macro definitions with metadata
Global Registry: Centralized macro management with categorization
Advanced Patterns: Pipe, memoize, conditional, and validated macros
Caching Support: Optional result caching for performance optimization
Search & Discovery: Pattern-based macro searching and organization
Mixin Support: Mix entire objects or classes into target classes

Installation

composer require hierone/macros

Usage

Basic Macro Usage

use Hierone\Component\Support\Macros\Macroable;

class MyClass
{
    use Macroable;
    
    protected $data;
    
    public function __construct($data = null)
    {
        $this->data = $data;
    }
}

// Register a macro
MyClass::macro('transform', function (callable $callback) {
    $this->data = $callback($this->data);
    return $this;
});

// Use the macro
$instance = new MyClass(10);
$result = $instance->transform(fn($x) => $x * 2); // $data becomes 20

Advanced Macro Patterns

use Hierone\Component\Support\Macros\MacroUtils;

// Create a pipe macro
$pipe = MacroUtils::pipe('process', [
    fn($x) => $x * 2,
    fn($x) => $x + 10,
    fn($x) => "Result: {$x}"
]);

// Create a memoized macro
$memoized = MacroUtils::memoize('expensive', function ($n) {
    // Expensive computation
    return fibonacci($n);
});

// Create conditional macro
$conditional = MacroUtils::conditional(
    'processIfPositive',
    fn($x) => $x > 0,
    fn($x) => $x * 2,
    fn($x) => 0
);

Global Registry

use Hierone\Component\Support\Macros\MacroRegistry;
use Hierone\Component\Support\Macros\Macro;

// Create registry with caching
$registry = new MacroRegistry(true);

// Register macros
$registry->register(Macro::create('double', fn($x) => $x * 2));
$registry->register(Macro::create('greet', fn($name) => "Hello, {$name}!"));

// Execute macros
$result = $registry->execute('double', [21]); // 42
$greeting = $registry->execute('greet', ['World']); // "Hello, World!"

// Search and categorize
$mathMacros = $registry->getByCategory('math');
$searchResults = $registry->search('gr*'); // Find macros starting with 'gr'

Mixin Support

class StringHelpers
{
    public function reverse()
    {
        return fn() => strrev($this->data);
    }
    
    public function uppercase()
    {
        return fn() => strtoupper($this->data);
    }
}

// Mix all methods from StringHelpers into MyClass
MyClass::mixin(new StringHelpers());

$instance = new MyClass('hello');
echo $instance->reverse()->uppercase(); // "OLLEH"

Macro Utilities

The MacroUtils class provides convenient factory methods:

simple() - Basic macro from closure
cacheable() - Macro with caching enabled
categorized() - Macro with category
constant() - Macro returning constant value
pipe() - Macro that pipes through functions
memoize() - Macro with memoization
conditional() - Conditional execution macro
validated() - Macro with input validation
retry() - Macro with retry logic
timed() - Macro with execution timing

Requirements

PHP 8.2 or higher
hierone/depreciation-contracts ^1.0

License

This package is open-sourced software licensed under the MIT license.

hierone / macros

Maintainers

Details