Memcachebundle Laravel Package

Getting Started

First, calibrate your expectations: this is a Symfony bundle, not a Laravel package. It registers the PHP Memcached extension as a container service for Symfony's AppKernel/bundles.php, and the repo is archived (22 stars). There is no service provider, no facade, no auto-discovery, and no compatibility promise for modern Laravel/Symfony versions.

For a Laravel codebase, the realistic "getting started" is not composer require. Instead:

1. Read Resources/config/services.* and the DependencyInjection/*Extension class — that is where the actual value lives (how servers, weights, and options are wired).
2. Ensure the environment has the native extension, which is the only hard requirement:

   php -m | grep memcached   # the extension, not "memcache"
   php -r 'var_dump(class_exists("Memcached"));'
   

3. If you genuinely need this bundle's wiring on a Symfony app: register Tarjei\MemcacheBundle\... in config/bundles.php, add a memcache: config block (host/port list), and inject the service via constructor autowiring.
4. On Laravel, skip the bundle and mirror its service definition in a tiny provider (below). Your first use case should be cache-aside reads — a Memcached singleton you get()/set() small, regenerable values (config snapshots, API responses, rendered fragments).

Before writing any code, check whether Laravel's built-in memcached cache driver already covers you. It almost always does.

Implementation Patterns

Port the container wiring, not the package. The bundle's only durable idea is "one configured Memcached instance, injected everywhere." Recreate that in a provider:

// app/Providers/MemcachedServiceProvider.php
public function register(): void
{
    $this->app->singleton(\Memcached::class, function () {
        $mc = new \Memcached();
        $mc->setOption(\Memcached::OPT_BINARY_PROTOCOL, true);
        $mc->setOption(\Memcached::OPT_DISTRIBUTION, \Memcached::DISTRIBUTION_CONSISTENT);
        foreach (config('memcached.servers') as $s) {
            $mc->addServer($s['host'], $s['port'], $s['weight'] ?? 0);
        }
        return $mc;
    });
}

Keep the server list in config/memcached.php with an env()-driven host/port so it follows the same shape the bundle used.

Use Laravel's cache layer as the façade. Wrap the singleton behind a repository or just switch the memcached store in config/cache.php and use Cache::store('memcached'). This gives you tags, TTLs, and remember() without reimplementing them.

Key namespacing is mandatory. Prefix every key with app + environment + version (prod:v3:users:42). This is the single pattern that saves you during deploys and shared-cluster incidents. Centralize it in a CacheKeys helper.

Cache-aside, always with a fallback path. Memcached is ephemeral; treat a miss and a server failure identically:

$value = $mc->get($key);
if ($mc->getResultCode() === \Memcached::RES_NOTFOUND) {
    $value = $this->expensiveQuery();
    $mc->set($key, $value, 300);
}

Binary protocol + consistent hashing are the two setOption calls worth copying from the bundle. Binary avoids a class of multi-server key-routing bugs; consistent hashing keeps most keys stable when you add a node.

If you must run it on Symfony (legacy app), the integration tip is: define the service as public in a compiler pass or use service_locator — modern Symfony private services won't be reachable via $container->get('memcache'), which is how most old tutorials show it.

Gotchas and Tips

• Archived + Symfony bundle + Laravel = friction. Composer will likely pull symfony/framework-bundle and can conflict with Laravel's own Symfony components. Don't install it just to get a Memcached wrapper; 40 lines of provider do the same thing.
• memcached vs memcache. The bundle targets the memcached extension (libmemcached). The older memcache extension is unrelated and unsupported on modern PHP. No Windows support for either — plan CI accordingly.
• 1 MB value ceiling and 250-byte key ceiling. Oversized values silently fail (RES_E2BIG) or, worse, return false. Check getResultCode() after every write during development.
• No persistence, no eviction guarantee. Memcached can drop any key at any time under memory pressure. Never store anything you can't rebuild. Never use it as a queue, lock (unless you understand add() semantics), or session source of truth without a DB fallback.
• No auth by default. SASL requires OPT_BINARY_PROTOCOL plus setSaslAuthData(). The bundle predates widespread SASL usage; if your cluster requires it, you're writing that yourself.
• Serialization mismatch is the classic silent bug. PHP's Memcached serializes with its own flags. If another service (or another language) writes the same key, you'll get garbage or false. Set an explicit serializer or store JSON strings.
• Debugging checklist. $mc->getVersion() (per-node reachability), $mc->getStats(), $mc->getResultCode()/getResultMessage(), and $mc->getServerList(). If getVersion() returns empty, it's a network/firewall issue, not a code issue.
• Extension points are thin. The bundle exposes essentially one service and a config tree. If you need retry logic, circuit breaking, or observability, wrap the Memcached instance in your own decorator rather than patching the archived code.
• Verdict for day-to-day work: use Laravel's native memcached driver, borrow this package's server-config and option patterns, and don't add the dependency.