README

🧠 Memoize - PHP Memoization Library

High-performance memoization and function caching library for PHP

🎯 About Memoize

Memoize is a lightweight PHP library designed to implement memoization and function caching techniques with ease.

Transform expensive function calls into lightning-fast cache lookups with zero configuration.

✨ Features

🚀 Quick Start - PHP Memoization

Installation

composer require tomloprod/memoize

Basic Usage

🏷️ Namespace Organization

If you want to get the most out of the package and better organize your memoization, we recommend using namespaces.

When using namespaces, if you use a $key with a null value, the callback won’t be executed (especially useful in certain cases).

// Organize cache by context
$userSettings = memoize()
    ->for(UserSettings::class)
    ->memo($userId, fn() => UserSettings::where('user_id', $userId)->first());

$productCache = memoize()
    ->for(Product::class)  
    ->memo($productId, fn() => Product::with('variants')->find($productId));

🔑 Key-based Memoization

You can also not use namespaces and just memoize keys.

// Expensive API call cached by key
$weather = memoize()->memo(
    'weather_london', 
    fn() => Http::get('api.weather.com/london')->json()
);

// Database query with dynamic key
$user = memoize()->memo(
    "user_{$id}", 
    fn() => User::with('profile', 'orders')->find($id)
);

⚡ Single Execution Functions

// Initialize expensive resources only once
$services = memoize()->once(fn() => [
    'redis' => new Redis(),
    'elasticsearch' => new Client(),
    'logger' => new Logger(),
]);

$redis = $services()['redis']; // Initialized once
$same = $services()['redis'];  // Same instance

🧠 Memory Management

The library uses an LRU (Least Recently Used) algorithm to automatically manage memory and prevent unlimited cache growth.

How does LRU work?

• Maintains a record of the access order for cache entries
• When the maximum limit (maxSize) is reached, automatically removes the least recently used entry
• Every time you access an entry (read or write), it moves to the front of the queue
• Older entries remain at the end and are candidates for removal

This ensures that the most relevant and frequently used data remains in memory, while obsolete data is automatically removed.

// Set LRU cache limit (by default, there is no max size)
memoize()->setMaxSize(1000);

// Cache statistics
$stats = memoize()->getStats();
// ['size' => 150, 'maxSize' => 1000, 'head' => [...], 'tail' => [...]]

// Clear specific or all cache
memoize()->forget('user_123');
memoize()->for('App\\Model\\User')->forget('123');

// Or clear all cache
memoize()->flush();

🔄 Enable/Disable Memoization

You can temporarily disable memoization to bypass caching when needed. When disabled, callbacks are executed every time without storing results in cache.

// Disable memoization
memoize()->disable();

// Now all memo() calls will execute callbacks without caching
$result1 = memoize()->memo('key', fn() => expensiveOperation()); // Executes
$result2 = memoize()->memo('key', fn() => expensiveOperation()); // Executes again

// Re-enable memoization
memoize()->enable();

// Now caching works normally again
$result3 = memoize()->memo('key', fn() => expensiveOperation()); // Executes and caches
$result4 = memoize()->memo('key', fn() => expensiveOperation()); // Returns cached value

// Check current state
if (memoize()->isEnabled()) {
    // Memoization is active
}

Use cases:

• Debugging: Temporarily disable caching to see fresh data
• Testing: Ensure callbacks execute every time during tests
• Conditional behavior: Disable caching based on environment or conditions

🏃 Runtime Flags

Control memoization behavior dynamically during execution with runtime flags. These flags exist only in memory and reset between requests/processes.

How do runtime flags work?

• Flags are stored in memory during the current execution
• They allow conditional behavior without external configuration
• Perfect for debug modes, logging control, and dynamic optimizations
• Automatically cleared when the process ends

// Skip cache during testing
memoize()->enableFlag('bypass_cache');

$userData = memoize()->memo("user_{$id}", function() use ($id) {
    if (memoize()->hasFlag('bypass_cache')) {
        return User::fresh()->find($id); // Always fetch from DB in tests
    }
    return User::find($id);
});


// Feature toggles without external dependencies
memoize()->enableFlag('new_algorithm');

$result = memoize()->memo($cacheKey, function() {
    if (memoize()->hasFlag('new_algorithm')) {
        return $this->calculateWithNewAlgorithm();
    }
    return $this->calculateWithOldAlgorithm();
});

// Development vs Production behavior
if (app()->environment('local') && memoize()->hasFlag('dev_mode')) {
    memoize()->enableFlags(['verbose_logging', 'bypass_cache']);
}

// Model boot method with conditional service calls
class Product extends Model
{
    protected static function boot()
    {
        parent::boot();
        
        static::updated(function ($product) {
            // Only call external stock service if flag is not set
            if (! memoize()->hasFlag('disableStockService')) {
                app(StockService::class)->updateInventory($product);
            }
        });
    }
}

Runtime Flag Methods:

💡 Advanced Examples

🏃‍♂️ Performance Optimization

// Fibonacci with memoization - O(n) instead of O(2^n)
function fibonacci(int $n): int {
    return memoize()->memo(
        "fib_{$n}", 
        fn() => $n <= 1 ? $n : fibonacci($n - 1) + fibonacci($n - 2)
    );
}

// Complex data aggregation
$salesReport = memoize()->memo(
    "sales_report_{$month}", 
    fn() => Order::whereMonth('created_at', $month)
        ->with('items.product')
        ->get()
        ->groupBy('status')
        ->map(fn($orders) => $orders->sum('total'))
);

📖 API Reference

Core Methods

Cache Management

⚙️ Requirements & Installation

• PHP 8.2+
• Composer

composer require tomloprod/memoize

🧑‍🤝‍🧑 Contributing

Contributions are welcome, and are accepted via pull requests. Please review these guidelines before submitting any pull requests.

Memoize was created by Tomás López and open-sourced under the MIT license.