Installation & Configuration

Installing php-memcached requires compiling the extension from source, either manually or via the PECL package manager. Because this extension is a wrapper around libmemcached, you must install the underlying C libraries on your operating system first.

1. Install System Dependencies

Before you can compile the PHP extension, you need libmemcached, developer headers for Zlib (for compression), and SASL (for authentication).

Ubuntu / Debian

sudo apt-get update
# Install core requirements
sudo apt-get install libmemcached-dev zlib1g-dev libsasl2-dev build-essential

# Optional: Install Zstd for advanced compression
sudo apt-get install libzstd-dev

RHEL / CentOS / Rocky Linux / AlmaLinux

sudo dnf install epel-release
sudo dnf install libmemcached-devel zlib-devel cyrus-sasl-devel gcc make

# Optional: Install Zstd
sudo dnf install libzstd-devel

2. Install Optional PHP Serializers

For production environments, it is highly recommended to use igbinary or msgpack instead of the default PHP serializer. They are faster and use significantly less memory. You must install these before compiling php-memcached so the compiler can detect their header files.

pecl install igbinary
pecl install msgpack

Note: Ensure you add extension=igbinary.so and extension=msgpack.so to your php.ini before proceeding.

3. Install php-memcached

Method A: Using PECL (Recommended)

The easiest way to install the extension is via PECL. When you run this command, you will be prompted to answer yes/no to enabling optional features (like igbinary, msgpack, and sasl).

pecl install memcached

If you want to automate this process (e.g., in a Dockerfile or CI/CD pipeline), you can pre-configure the PECL answers:

printf "\n\n\n\n\nyes\nyes\nyes\n" | pecl install memcached

Method B: Compiling from Source

If you need strict control over the build process, custom library paths, or want to compile the latest master branch from GitHub, compile from source:

# 1. Clone the repository
git clone https://github.com/php-memcached-dev/php-memcached.git
cd php-memcached

# 2. Prepare the build environment
phpize

# 3. Configure the build. 
# Adjust these flags based on the optional dependencies you installed earlier.
./configure \
    --enable-memcached \
    --enable-memcached-session \
    --enable-memcached-igbinary \
    --enable-memcached-msgpack \
    --enable-memcached-json \
    --enable-memcached-sasl \
    --with-zstd

# 4. Compile and install
make
sudo make install

Key ./configure Options Explained

• --with-libmemcached-dir=DIR: Use this if your libmemcached is installed in a non-standard location (e.g., /opt/local or a Homebrew path on macOS).
• --enable-memcached-session: Compiles the custom session handler. You almost always want this enabled.
• --enable-memcached-protocol: Enables the experimental MemcachedServer class, allowing you to write your own Memcached protocol server in PHP.

Method C: Dockerfile Example

If you are using Docker, here is a standard, production-ready snippet for official PHP images:

FROM php:8.2-fpm

# Install system dependencies
RUN apt-get update && apt-get install -y \
    libmemcached-dev \
    zlib1g-dev \
    libsasl2-dev \
    libzstd-dev

# Install igbinary first
RUN pecl install igbinary \
    && docker-php-ext-enable igbinary

# Install memcached with igbinary and msgpack support
RUN pecl install memcached \
    && docker-php-ext-enable memcached

4. Enable and Verify the Extension

Finally, add the extension to your php.ini file. Crucial: If you compiled with igbinary or msgpack support, their extensions must be loaded before memcached.so.

; Correct Loading Order
extension=igbinary.so
extension=msgpack.so
extension=memcached.so

Verify the installation from your command line:

php -m | grep memcached
php -i | grep "memcached support"

Troubleshooting Compilation Errors

Error: Cannot find igbinary.h

Cause: You passed --enable-memcached-igbinary but the igbinary extension header files are missing.

Fix: Ensure you have run pecl install igbinary first. On some specific OS setups, you may need to specify the path manually or ensure the php-dev package matches your PHP version.

Error: libmemcached built with sasl disabled

Cause: You passed --enable-memcached-sasl, but the libmemcached version installed on your OS was compiled without SASL support.

Fix: Either recompile libmemcached with SASL, install the libsasl2-dev package before installing libmemcached, or pass --disable-memcached-sasl to the PHP extension configure script if you do not need authentication.