PHP-CPP for Building Native PHP Extensions with C++

Why PHP-CPP Targets Native Extension Development

PHP-CPP addresses the code and interface burden of creating a native PHP extension in C++. Its intended audience is developers who already work in PHP and C++ and want to combine the two without implementing much of the extension boundary through raw Zend Engine structures and pointer manipulation. The library presents C++11 classes for native functions, parameters, return values, arrays, objects, and interactions with the PHP runtime.

The abstraction is most useful when a PHP application needs code implemented as a native extension rather than ordinary PHP. The README does not claim that PHP-CPP accelerates those extensions, removes all platform dependencies, or provides a portable binary. Its documented benefit is development ergonomics: C++ functions can receive PHP arguments and return PHP values through `Php::Value` instead of requiring the extension author to perform the lower-level conversions directly.

PHP-CPP does not make every extension deployment concern disappear. The project still produces native code, relies on `php-config`, and has build settings for include directories and shared libraries. Its appropriateness therefore depends on whether the development team can compile and load a native extension for its PHP installation.

The Php::Value Bridge Between PHP and C++

At the center of the documented interface is `Php::Value`. A native C++ function can return one, and PHP-CPP converts it into a PHP value. In the other direction, an exported function can accept `Php::Parameters &params` and use indexed values such as `params[0]` and `params[1]`. The library handles the conversion between PHP variables, which the README describes as complicated internal C structures, and native C++ values.

The smallest documented example returns a string from a no-parameter C++ function:

Php::Value hello_world()
{
    return "hello world!";
}

Registering that native function with an extension object requires one `add` call:

extension.add("hello_world", hello_world);

For parameters, the C++ implementation can perform addition through values exposed by `Php::Parameters`:

Php::Value my_plus(Php::Parameters &params)
{
    return params[0] + params[1];
}

The registration example adds argument metadata and declares both arguments as numeric values passed by value:

extension.add<my_plus>("my_plus", {
    Php::ByVal("a", Php::numericType),
    Php::ByVal("b", Php::numericType)
});

This division of responsibility is important. The extension author defines the C++ function and its argument contract, while PHP-CPP performs the value conversion. The README does not specify every conversion rule, coercion policy, or error behavior, so an extension still needs explicit tests around boundary values.

Nested PHP Values and Object-Oriented Examples

PHP-CPP can represent more complicated PHP data structures rather than only scalar return values. The README demonstrates construction of a nested associative array through a local `Php::Value`. Values can be assigned by key, including a nested array indexed from zero:

Php::Value get_complex_array()
{
    Php::Value r;
    r["a"] = 123;
    r["b"] = 456;
    r["c"][0] = "nested value";
    r["c"][1] = "example";
    return r;
}

Based on the repository layout, native extension features are not limited to the basic functions highlighted in the README. `Examples/CppClassesInPhp/`, `Examples/ConstStaticProp/`, `Examples/Exceptions/`, `Examples/Globals/`, `Examples/ReturnObject/`, and `Examples/CallPhpFunctions/` indicate separate example areas for C++ classes, constants, static properties, exceptions, globals, returned objects, and calls into PHP. These are useful signals when selecting an example, but the repository does not show their complete build instructions or runtime contracts.

That limitation matters for evaluation. A basic addition function can be assessed quickly from the README, while object exposure and PHP callback behavior require inspecting and building the corresponding examples against the developer's PHP environment. The library should not be assumed to support every extension pattern identically. Each example represents a specific API path that must be checked against the intended extension design.

Building PHP-CPP and Performing a First Extension Exercise

The repository points readers to `http://www.php-cpp.com` for full documentation and includes both `CMakeLists.txt` and a top-level `Makefile`. The Makefile uses the standard `php-config` utility to locate PHP include directories, shared libraries, and the PHP binary path. Its default setting is:

PHP_CONFIG = php-config

On Linux, the Makefile selects `/usr` as the installation prefix, while Darwin selects `/usr/local`. It also records the shared object name as `2.4` and the library version as `2.4.16`. These settings come directly from the Makefile.

The project documentation does not give a complete, end-to-end installation command sequence, and the Makefile excerpt ends before its operational targets. For that reason, this tutorial does not invent compiler flags or claim that a generic build command is sufficient. Start by checking that the required discovery tool is available:

php-config

The reader should see the configuration output for the PHP installation that will own the extension. If `php-config` is not in the default location, change the `PHP_CONFIG` setting in the top-level `Makefile` to the available executable, following the explanation included there.

For a first extension exercise, create the no-parameter function shown earlier and register it with `extension.add("hello_world", hello_world)`. Then follow the extension scaffolding supplied by the full PHP-CPP documentation and the `Examples/FunctionNoParameters/` or `Examples/EmptyExtension/` directory. The expected PHP-side behavior of the first documented function is a call to `hello_world()` returning `hello world!`. The repository does not identify the required module entry point or build flags, so they should not be guessed.

Native Build Constraints and PHP-CPP Failure Modes

The main constraint is environmental rather than conceptual. PHP-CPP is a native C++ library that builds a shared library and extension code against PHP. The Makefile uses `php-config` to find build and installation information, and the source includes a `zend/` directory. A mismatch between the PHP installation queried during the build and the PHP runtime that later loads the extension can produce an unusable extension even when the C++ source compiles.

The README does not document rollback, ABI compatibility policy, supported compiler matrix, or a deployment procedure for mismatched PHP environments. It also does not claim that an extension built with PHP-CPP can be copied between arbitrary PHP installations. Engineers should therefore treat the target PHP build as part of the extension's packaging contract.

PHP-CPP is also the wrong tool when the requirement is simply to write reusable PHP code. Native code introduces compilation, `php-config`, library linking, and runtime loading into the process. It may also be a poor choice for a codebase that already depends on direct Zend Engine behavior that is not represented by PHP-CPP's interface. The abstraction reduces lower-level conversion work, but it does not remove the need to understand the native PHP extension environment.

PHP-CPP Versus Direct Zend Engine Extension Work

The clearest alternative is a regular PHP extension implemented directly against the Zend Engine. Both approaches produce native code and expose functionality to PHP. Their difference is the extension-authoring interface. A direct Zend implementation exposes the engine's C-level structures and requires the developer to manage representation details and pointer operations. PHP-CPP places `Php::Value`, `Php::Parameters`, argument declarations, and extension registration in front of those details.

That difference can reduce the amount of boilerplate for functions that accept and return ordinary values. The README's addition example shows this directly: PHP-CPP exports `my_plus` with named numeric arguments and performs addition through `params[0]` and `params[1]`. A direct implementation would instead address the same boundary through the Zend Engine API.

PHP-CPP is not a drop-in replacement for every low-level requirement. If an extension must manipulate engine internals that PHP-CPP does not expose, direct Zend work may provide the necessary control. The repository does not list the complete low-level API surface or document how PHP-CPP and direct Zend calls can be mixed. The decision should therefore be based on the extension's required features, not only on the shorter scalar-function examples.

Release Activity, Upgrades, and Apache-2.0 Obligations

The repository is not archived, and its last push was on 2026-07-06. Releases include PHP-CPP 2.4.16 on 2026-07-06, 2.4.15 on 2026-07-05, and 2.4.14 on 2026-05-03. The Makefile for the current source identifies `VERSION = 2.4.16` and `SONAME = 2.4`. Its comments state that the shared object name and minor version should be raised when the ABI changes, while release-only changes increment the release version. That gives maintainers and packagers explicit signals to consider during upgrades.

An upgrade may still require rebuilding dependent extension code and the PHP-CPP shared library. The repository does not describe ABI compatibility across particular PHP versions or provide an automated migration procedure, so those points cannot be assumed. Before replacing a deployed version, verify the library version, shared object version, target `php-config` output, and extension build against the intended runtime.

The repository is licensed under Apache-2.0. That identifier permits reuse and modification subject to its license conditions, while distribution normally requires attention to notices and license text. The repository includes a `LICENSE` file. This is a practical compliance check rather than legal advice, and downstream distributions should retain the applicable Apache-2.0 licensing information.

Editorial conclusion

PHP-CPP is appropriate for C++ developers who need a native PHP extension and prefer its value interface to direct Zend Engine work. It is a poor fit for developers seeking a pure-PHP solution, a portable extension, or turnkey packaging. Before adoption, verify compatibility with the exact PHP build, compiler configuration, required `php-config` paths, and extension-loading process. The first acceptance check should be a minimal `hello_world` extension built and loaded in the intended deployment environment.

Frequently asked questions

Official sources

1. CopernicaMarketingSoftware/PHP-CPP on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases