Laminas Cache Storage Adapter Memcached Laravel Package

Getting Started

Minimal Setup

1. Install the package (PHP 8.4 compatible):

   composer require laminas/laminas-cache-storage-adapter-memcached:^3.1
   

2. Basic Memcached Adapter Usage (PHP 8.4+):

   use Laminas\Cache\Storage\Adapter\Memcached as MemcachedAdapter;
   
   $memcached = new \Memcached();
   $memcached->addServer('localhost', 11211);
   
   $adapter = new MemcachedAdapter(
       'my_cache',
       0, // TTL in seconds
       $memcached
   );
   

3. First Use Case: Caching API Responses (PHP 8.4 type-safe):

   $cacheKey = 'api_user_data_' . $userId;
   $data = $adapter->getItem($cacheKey);
   
   if (!$data->isHit()) {
       $data = fetchFromExternalApi($userId);
       $adapter->save($data);
   }
   

Key Documentation Links

• Official Documentation
• PSR-16/PSR-6 Compatibility
• PHP 8.4 Migration Guide

Implementation Patterns

Core Workflows

1. PHP 8.4 Dependency Injection Setup (Laravel)

// config/cache.php
'stores' => [
    'memcached' => [
        'driver' => 'memcached',
        'connection' => 'default',
        'php_version' => '8.4', // Explicit version note
    ],
],

// In a Service Provider (PHP 8.4 constructor injection)
public function register(): void
{
    $this->app->singleton(\Memcached::class, function ($app) {
        $memcached = new \Memcached();
        $memcached->setOption(\Memcached::OPT_CONNECT_TIMEOUT, 1000);
        $memcached->addServer(
            config('cache.memcached.host'),
            config('cache.memcached.port')
        );
        return $memcached;
    });

    $this->app->bind(\Laminas\Cache\Storage\Adapter\Memcached::class, function ($app) {
        return new \Laminas\Cache\Storage\Adapter\Memcached(
            'laravel_cache',
            3600, // 1 hour TTL
            $app->make(\Memcached::class)
        );
    });
}

2. Tag-Based Cache Invalidation (PHP 8.4)

// Save with tags (PHP 8.4 strict types)
$item = $adapter->getItem('user_profile_123');
$item->setTags(['user', 'profile']);
$adapter->save($item);

// Clear by tag (PHP 8.4 array type)
$adapter->removeItemByTag('user');

3. Fallback Cache Strategy with PHP 8.4 Exceptions

try {
    $data = $adapter->getItem('expensive_data')->get();
} catch (\Psr\Cache\InvalidArgumentException $e) {
    // Fallback to database or other source
    $data = fallbackDataSource();
    $adapter->save($data);
} catch (\Laminas\Cache\Exception\RuntimeException $e) {
    // Handle Memcached-specific errors
    log::error("Memcached failure: " . $e->getMessage());
}

4. Batch Operations (PHP 8.4 Generics)

// Batch save with PHP 8.4 generics support
$items: array<string, mixed> = [
    'key1' => serialize($data1),
    'key2' => serialize($data2),
];

foreach ($items as $key => $value) {
    $adapter->saveDeferred($key, $value);
}
$adapter->commit();

Integration Tips

1. Laravel Cache Integration (PHP 8.4)

// Extend Laravel's Cache Manager with PHP 8.4 return types
Cache::extend('memcached', function ($app) {
    $memcached = new \Memcached();
    $memcached->setOption(\Memcached::OPT_CONNECT_TIMEOUT, 1000);
    $memcached->addServer(
        config('cache.memcached.host'),
        config('cache.memcached.port')
    );

    return Cache::repository(new \Laminas\Cache\Storage\Adapter\Memcached(
        'laravel_cache',
        $app['config']['cache.ttl'],
        $memcached
    ));
})->extend('memcached', function ($app) {
    return Cache::store('memcached');
});

2. PSR-16 Cache Pool (PHP 8.4)

use Laminas\Cache\Storage\Adapter\Memcached as MemcachedAdapter;
use Psr\SimpleCache\CacheInterface;

$adapter = new MemcachedAdapter('psr_cache', 3600, $memcached);
$cache: CacheInterface = new \Laminas\Cache\Storage\Psr6\SimpleCacheAdapter($adapter);

3. Custom Metadata Handling (PHP 8.4)

$item = $adapter->getItem('metadata_example');
$item->setMetadata([
    'last_updated' => time(),
    'source' => 'api_v2',
    'version' => '1.0'
]);
$adapter->save($item);

// Retrieve with PHP 8.4 typed access
$metadata = $item->getMetadata();
$lastUpdated = $metadata['last_updated'] ?? null;

Gotchas and Tips

Common Pitfalls

1. Key Length Limitations (Unchanged)

   • Memcached has a 250-byte key limit (not 255).
   • Solution: Use shorter keys or implement key hashing:

     $key = hash('sha256', $originalKey, true);
     $key = substr($key, 0, 249); // Ensure length < 250
     

2. PHP 8.4 Type Safety

   • New: Strict typing in constructor parameters.
   • Solution: Ensure all constructor arguments match expected types:

     // Correct (PHP 8.4)
     $adapter = new MemcachedAdapter(
         'cache', // string
         3600,    // int
         $memcached // \Memcached
     );
     

3. Connection Timeouts (Enhanced)

   • Memcached operations may hang if servers are unreachable.
   • Solution: Set connection timeout in options (PHP 8.4):

     $memcached->setOption(\Memcached::OPT_CONNECT_TIMEOUT, 1000); // 1 second
     $memcached->setOption(\Memcached::OPT_RETRY_TIMEOUT, 2000); // 2 seconds
     

4. TTL Granularity (Unchanged)

   • Memcached uses seconds for TTL, not milliseconds.
   • Solution: Round values to nearest second:

     $ttl = (int)ceil($milliseconds / 1000);
     

Debugging Tips

1. Enable Memcached Debugging (PHP 8.4)

   $memcached->setOption(\Memcached::OPT_DEBUG, 255); // Enable all debug levels
   error_reporting(E_ALL); // Ensure PHP 8.4 error reporting
   

2. Check Server Statistics (PHP 8.4)

   $stats = $memcached->getStats();
   // Inspect for errors or connection issues
   foreach ($stats as $server => $data) {
       if (isset($data['uptime'])) {
           echo "Server $server is healthy (uptime: {$data['uptime']}s)\n";
       }
   }
   

3. Handle Serialization Errors (PHP 8.4)

   • Memcached requires serializable data.
   • Solution: Implement JsonSerializable or use serialize():

     $adapter->save(serialize($data));
     $data = unserialize($adapter->getItem('key')->get());
     

Advanced Patterns

1. Custom Resource Manager (PHP 8.4 Interface)

   use Laminas\Cache\Storage\Adapter\Memcached\MemcachedResourceManagerInterface;
   
   class CustomResourceManager implements MemcachedResourceManagerInterface {
       public function getResource(): \Memcached {
           // Custom logic (e.g., connection pooling)
           return $memcached;
       }
   }
   
   $options = new \Laminas\Cache\Storage\Adapter\Memcached\MemcachedOptions();
   $options->setResourceManager(new CustomResourceManager());
   $adapter = new MemcachedAdapter('custom', 0, $options);
   

2. Libketama Consistent Hashing (PHP 8.4)

   $memcached->set