php-memcached: the PECL memcached extension on libmemcached

A thin binding, and the parts of PHP it has to mirror

php-memcached is the PECL memcached extension, using the libmemcached library to connect to memcached servers, and the repository listing shows that it is a thin binding rather than a reimplementation.

The C source is small and specific. `php_memcached.c` and `php_memcached.h` are the main files, `php_libmemcached_compat.c` and `php_libmemcached_compat.h` handle the differences between libmemcached versions, and there are dedicated server and session files, `php_memcached_server.c` and `php_memcached_session.c`, for the two areas that needed their own handling.

The arginfo files are the modern PHP detail. There is a `php_memcached.stub.php`, a `php_memcached_arginfo.h` and a `php_memcached_legacy_arginfo.h`. Stub files with generated arginfo are how a PHP extension declares its function signatures once, in PHP, and have the C header generated from them, and the separate legacy header exists for the older signature set that older PHP versions still need. The extension therefore has a modern build and a compatibility build in the same tree.

The `memcached-api.php` file is the API documentation, and `memcached.ini` is the configuration file that would carry the `memcached.*` directives, and `config.m4` and `config.w32` are the build system definitions for Unix and Windows respectively, with `README.win32.txt` covering the Windows specifics.

The `fastlz/` directory is a bundled compression library, and `server-example/` and `tests/` are the example and test directories.

So the shape is: a PHP extension that is mostly generated glue around libmemcached, with the interesting code in the compat layer, the server handling and the session handler.

Building it needs phpize and the libmemcached headers present first

The build section is four commands, and they are the standard PECL extension build.

$ phpize
$ ./configure
$ make
$ make test

`phpize` is the script that turns a PHP extension source tree into something the PHP build system understands, `./configure` then generates the build configuration, `make` builds, and `make test` runs the extension's test suite against a PHP binary with the extension loaded.

The dependencies section is where the compatibility story lives, and it is split by major version because the two lines are genuinely different products.

For php-memcached 3.x, it supports PHP 7.0 to 8.3 or higher, requires libmemcached 1.x or higher, and optionally supports igbinary 2.0 or higher and msgpack 2.0 or higher.

For php-memcached 2.x, it supports PHP 5.2 to 5.6, requires libmemcached 0.44 or higher, and optionally supports igbinary 1.0 or higher and msgpack 0.5 or higher.

The libmemcached line is worth a note. The documentation recommends libmemcached, or the new libmemcached-awesome version, at 1.0.18 or higher for best performance and compatibility with memcached servers. That points at a fork of the long-stalled original library, which is the sort of detail that matters when you are choosing what to build against on a supported PHP version.

The most recent release is v3.4.0 from 2025-10-14, with v3.3.0 from 2024-10-17 and a 3.3.0RC1 before it, and the last push was on 2026-08-14, so the 3.x line is the active one.

igbinary and msgpack are faster, but the install order is not optional

The two optional serialisation backends are the most interesting part of the dependency story, and both come with an installation constraint that is easy to miss.

igbinary is described as a faster and more compact binary serializer for PHP data structures. When installing php-memcached from source code, the igbinary module must be installed first so that php-memcached can access its C header files. Load both modules in your `php.ini` at runtime to begin using igbinary.

msgpack is described as a faster and more compact data structure representation that is interoperable with msgpack implementations for other languages. It has the same constraint: when installing php-memcached from source code, the msgpack module must be installed first so that php-memcached can access its C header files, and you load both modules in your `php.ini` at runtime to begin using msgpack.

The reason is straightforward once you understand what these are. These are C extensions themselves, and the php-memcached extension links against their C headers to call into their serialisation functions. If the headers are not on the include path when php-memcached is compiled, the code that would use them is compiled out, and the serialisation support silently does not exist in the binary you just built.

That is a genuinely nasty failure mode, because the extension builds fine and appears in `php -m`, and the default serialiser is the standard PHP one, so nothing breaks until you configure the extension to use igbinary and find it ignored. The documentation's advice to install the serialiser extension first, and to load both in `php.ini` at runtime, is the fix for both halves of the problem: the headers for the compile, the ini entries for the runtime.

The `composer.json` and `package.xml` at the root are the two manifests a PECL extension carries, one for Composer and one for the PECL package repository, and the `CREDITS` file and `ChangeLog` are the conventional attribution and history files.

What memcached itself is, and why the extension exists at all

The description of memcached in the readme is the standard one and worth repeating, because the extension exists to serve a specific purpose.

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

Two phrases there carry the design. Distributed memory object caching means the cache is a set of servers rather than a process, and the extension is a client for that set. And alleviating database load is the purpose: the cache exists to keep the database from doing work it does not need to do, so the extension's job is to be a fast way to talk to memcached from PHP, and specifically to make the serialisation of the stored values cheap.

That is where igbinary and msgpack fit into the story rather than being a separate feature. The default PHP serialiser turns an array into a string in a way that is portable but not compact and not fast, and the size of the serialised value matters twice over in a cache: it costs memory on the server and it costs network bandwidth on every miss. A binary serialiser addresses both. The extension's value proposition is therefore a combination of a fast memcached client and an optional faster encoding, and the two features are worth enabling together.

The interop point for msgpack is worth naming too. It is interoperable with msgpack implementations for other languages, so a PHP service and a service in another language can share a memcached instance and read each other's values, which is not true of igbinary and is a real reason to pick one over the other in a polyglot shop.

Where php-memcached is the wrong choice

The first case is a project that has not decided it wants memcached. A caching layer added on speculation is a liability, because every cached value is a second copy of something, and every cache is a place where stale data is served to a user who did not ask for it. The extension makes it easy to add memcached; it does not help you decide whether you want it.

The second case is a project on a modern PHP with a pure PHP client already working. The gains from a native extension are in the serialisation and the connection handling, and if you are not using igbinary or msgpack, a pure PHP client does most of the same work. The extension is a better answer for the extension-heavy case.

The third case is a shared hosting environment. This is a C extension, so it has to be compiled and installed on the host, and if you cannot install PHP extensions you cannot use it. On a managed platform the caching options are whatever the platform ships, and the choice is made for you.

The fourth is a team that wants the extension to talk to a memcached-compatible service with unusual semantics. The extension speaks memcached to memcached servers, and while the memcached protocol is widely implemented, a hosted key-value store that merely looks like memcached is not guaranteed to implement every command, and the extension's server and session handling assume the real thing.

A version caution. The 2.x line is for PHP 5.2 to 5.6, which is a different decade of PHP, and the 3.x line supports PHP 7.0 to 8.3 or higher. If your platform is on PHP 8.4 you are on the 3.x line, and the last push was on 2026-08-14 with the newest release v3.4.0 from October 2025, so the line is maintained but the tags are not frequent.

Editorial conclusion

php-memcached fits a PHP application that already speaks memcached and wants a native extension rather than a pure PHP client, especially with igbinary or msgpack enabled for the serialisation overhead. It does not fit a project that has not yet decided whether it wants memcached, since a caching layer added on speculation is a liability. Before you build it, check the header files as the documentation insists, because the igbinary and msgpack modules must be installed first so that php-memcached can reach their C headers, and confirm your libmemcached version against the 3.x requirement of 1.x or higher.

Frequently asked questions

Official sources

1. Issues
2. php-memcached-dev/php-memcached on GitHub
3. README
4. Releases