php-memcached

Build Status

Welcome to the official documentation for the php-memcached extension. This PECL extension provides a highly optimized, robust, and feature-rich interface for communicating with Memcached servers from PHP.

Under the hood, php-memcached acts as a binding for the libmemcached C library. This means it inherits the high performance, non-blocking I/O, and advanced distribution algorithms native to libmemcached, making it the industry standard for PHP applications requiring enterprise-grade caching.

When to Use This Extension

Memcached is a high-performance, distributed memory object caching system. It is generic in nature but intended for use in speeding up dynamic web applications by alleviating database load. You should use php-memcached when:

  • Scaling Web Applications: You need to cache expensive database queries, complex API responses, or rendered HTML blocks.
  • Stateless Scaling: You are scaling PHP across multiple servers and need a centralized, fast Session Handler to maintain user state without relying on sticky sessions.
  • Rate Limiting & Counting: You need atomic increment/decrement operations for tracking page views, API rate limits, or login attempts.

Key Architecture & Features

Unlike the older, purely PHP-based memcache (without the 'd') extension, php-memcached offers several critical architectural advantages:

  • Consistent Hashing (Ketama): Ensures that adding or removing a Memcached node from your server pool only invalidates a minimal fraction of your cache, preventing catastrophic cache misses (thundering herd) during scaling or hardware failures.
  • Advanced Serializers: Out-of-the-box support for igbinary, msgpack, and JSON. Using igbinary or msgpack drastically reduces the memory footprint of stored PHP objects and arrays compared to standard PHP serialization.
  • Transparent Compression: Automatically compress large payloads using FastLZ, Zlib, or the modern Zstd algorithm before sending them over the network. This trades a negligible amount of CPU time for massive savings in network bandwidth and Memcached RAM usage.
  • Binary Protocol Support: Fully supports the modern Memcached Binary protocol, which is more efficient to parse and required for advanced features like SASL authentication and Touch operations.
  • Asynchronous / Non-Blocking I/O: Supports getDelayed and fetch operations to request multiple keys concurrently without blocking the PHP thread until the data is actually needed.

System Requirements

To run php-memcached in your environment, you will need:

  • PHP: Version 7.0 through 8.3 (or higher).
  • libmemcached: Version 1.0.18 or higher. (The active fork libmemcached-awesome is highly recommended).
  • igbinary: Version 2.0+ (Optional, but highly recommended for performance).
  • msgpack: Version 2.0+ (Optional alternative serializer).

Ready to get started? Head over to the Installation guide, or jump straight into the Quick Start if your environment is already configured.