How do I install an extension of Kafka for PHP?

How do I install an extension of Kafka for PHP?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

How do I install an extension of Kafka for PHP?

You are looking to integrate phpkafka from the EVODelavega repository into your stack. This library is a wrapper around librdkafka, the C client library that provides high-performance access to Apache Kafka. The core constraint here isn't just the PHP code; it is the underlying C dependency. If you cannot find librdkafka/rdkafka.h in your default path, the build process halts immediately because the C compiler cannot locate the header files required to compile the extension.

The standard installation documentation points to Arnaud LB's guide for building librdkafka. When the 1st and 4th methods fail with a "not found" error regarding rdkafka.h, it usually indicates that the C library was not compiled and installed into a system location where your PHP build environment can see it. The error message configure: error: Please reinstall the rdkafka distribution suggests that either the source wasn't extracted correctly, or the installation path (--prefix) during the build did not match where your phpize script is looking.

To resolve this, you must ensure librdkafka is built and linked before attempting to compile phpkafka. The most robust approach involves installing the system libraries first if they exist in your OS package manager, or manually building them from source with a specific prefix. If you are on Ubuntu or Debian, check for the availability of librdkafka-dev. If that is missing, you must clone the librdkafka repository, run ./configure, make, and make install. Crucially, after running make install, verify that the headers are present in /usr/local/include or whatever directory your --prefix specified.

Once librdkafka is successfully installed, you can proceed to compile the PHP extension. The repository requires a specific version of librdkafka. Mismatching versions between the C library and the PHP extension often leads to runtime errors where the PHP extension loads but cannot communicate with the Kafka broker. Ensure that the headers found during the configuration step match the installed .so file version.

After compiling the extension, you must load it in your PHP configuration. If using Laravel or another framework, you typically need to add the line extension=php_kafka.so to your php.ini file. However, simply loading the extension is not enough for the JSON requirement you mentioned. The messages passed to the queue must be serialized to JSON before being sent via the producer. The phpkafka library handles this serialization internally if configured correctly, but you must ensure your message payload is an array or string compatible with its expectations.

A common pitfall in this setup is handling SSL certificates. If your Kafka broker uses SASL_SSL, the default build of librdkafka might not include the necessary security modules unless you compile it with --enable-security. This requires passing specific flags to the CMake or Make configuration step for librdkafka before you even attempt to build the PHP layer.

For those working within a Laravel ecosystem, managing these dependencies often requires careful handling of Composer autoloading alongside system-level binaries. While there are managed services and wrappers available that abstract away some of this complexity, understanding the dependency chain—specifically librdkafka → phpkafka → PHP runtime—is essential for debugging connection issues or serialization errors. If you encounter persistent header file errors, double-check your environment variables; sometimes the build system defaults to /usr/include, while your package manager installs headers to a custom location that isn't in the standard include path.

Our network