Zephir: writing PHP extensions in a compiled language that emits C

What Zephir solves for PHP extension authors

Writing a PHP extension in C means managing reference counting, memory allocation, argument parsing and the Zend API by hand. Zephir takes a different route. The README describes it as "a high level programming language that eases the creation and maintainability of extensions for PHP", and the repository's topics list php-extension and php-internals, which is a fair summary of the audience. You write classes and functions in Zephir's syntax, the compiler translates them to C, and a C compiler such as gcc, clang or vc++ builds the result into a loadable extension. The functionality is then exposed to PHP like any other extension.

The people who benefit are narrow and specific. If you maintain a library where the hot path is algorithmic work that PHP's interpreter cannot make fast enough, or where you need to reach into PHP internals, Zephir gives you a middle layer. If you are writing ordinary application code, this is the wrong tool entirely, and the build chain alone will cost you more than it returns.

The compile-to-C pipeline and what is in the repository

The data flow is one-directional: Zephir source in, C out, then a native shared object. The repository layout reflects that pipeline rather than hiding it. There is a kernel/ directory, an ext/ directory, a templates/ directory and a stub/ directory, alongside a config/ directory and a top-level config.json. The presence of templates and stubs suggests the compiler generates boilerplate C from parameterised templates rather than concatenating strings, though the README does not explain the internals and the official documentation is the place to look for that.

The repository is also a PHP project in its own right. composer.json and composer.lock sit at the top level, there is a src/ directory, and the tooling includes phpunit.xml.dist, psalm.xml, phpmd.xml.dist, phpcs.xml.dist, phpbench.json and a .php-cs-fixer.dist.php config. The compiler is written in PHP and installed as a PHP package, which is worth internalising before you start: the tool that produces C is itself interpreted.

Two launcher scripts ship at the top level, zephir for Unix-like systems and zephir.bat for Windows, plus a zephir-autocomplete file for shell completion. WINDOWS.md exists as a separate document, which tells you Windows support is real but has its own notes rather than being folded into the main README.

Installing Zephir and compiling a first extension

The README points to the official documentation at docs.zephir-lang.com and lists the package on Packagist as phalcon/zephir, so Composer is the distribution channel. The README itself does not print install commands, and the exact global-install invocation belongs to the documentation; check it there before running anything.

The repository does ship a docker-compose.yml for local development, and it is explicit about its purpose in a comment: "For local development only." It defines six services, zephir-8.0 through zephir-8.5, each built from a matching .docker/8.x directory, each with working_dir set to /srv and the repository mounted at /srv. That gives you a defined environment per PHP version without installing compilers on your host.

docker compose up -d zephir-8.2
docker compose exec zephir-8.2 bash

Inside that container you are in /srv with a PHP 8.2 toolchain. The zephir script at the repository root is the entry point for compiler commands; the documentation covers the specific subcommands for initialising a project, generating C and building the extension.

./zephir

Run without arguments, the launcher prints its available commands. Treat that output as the authoritative list of subcommands for the release you installed rather than relying on any command name you have seen elsewhere.

If you prefer a host install, Composer is the route the README implies through the Packagist link, and the documentation carries the exact command. Either way, the first real use is the same: initialise a project, write one class, compile it to C, build the extension, and confirm the class is visible from PHP.

Where Zephir stops being the right answer

The build chain is the limitation. Every change to your Zephir source requires a recompile and a rebuild of the extension, and the resulting artifact must be loaded by a matching PHP build. That is a slow loop compared with editing a .php file, and it is a deployment constraint: you now ship a binary per platform and per PHP version, not a directory of source.

There is a second constraint in the repository itself. The docker-compose.yml defines development containers for PHP 8.0, 8.1, 8.2, 8.3, 8.4 and 8.5 only. That is the range the project's own local environment targets. If you need to support an older PHP branch, the repository gives you no container for it, and you would be building that environment yourself.

Finally, the README does not document rollback, and it does not describe what happens when a Zephir release and a PHP release fall out of step. For a compiled extension that gap matters more than it would for a library, because a version mismatch is a load-time failure rather than a runtime warning.

How this differs from hand-written C and from FFI

The obvious alternative is writing the extension in C directly against the Zend API. That approach gives you total control: no compiler layer, no generated code to reason about, no dependency on Zephir's release cadence. It also means you own argument parsing, memory management and every refcount by hand, and the README's framing of Zephir as easing "creation and maintainability" is a direct claim about that cost. If your extension is a thin binding over an existing C library, hand-written C is often less work, not more.

The other alternative is PHP's FFI, which calls into C from userland PHP without producing an extension at all. The difference in approach is fundamental: FFI keeps you in interpreted PHP and calls out, while Zephir compiles your logic into the extension itself. FFI avoids the build-and-install step entirely, which is a large advantage for internal tooling. Zephir is the better fit when the extension has to be distributed, installed like any other PHP extension, and available to code that cannot depend on FFI being enabled.

Maintenance, releases and the MIT licence

The repository is not archived, and its last push was on 2026-09-23, so it is being worked on. Release cadence is visible in the tags: 1.5.0 on 2026-09-18, 1.4.0 on 2026-09-08 and 1.3.0 on 2026-08-25. Three releases inside roughly a month is a fast pace, which cuts both ways. You get fixes quickly, and you also carry an upgrade cost each time you move, because a compiler change can alter the C it emits.

The upgrade cost is real but bounded by the layout. The compiler is a Composer package, so moving between Zephir versions is a dependency bump plus a rebuild of your extension. The expensive part is not the compiler; it is re-verifying that the C it now generates still compiles and behaves the same on every PHP version you support.

Zephir is MIT licensed, and the README states this plainly with a link to the LICENSE file. MIT is permissive, so it places few conditions on the extensions you build with it. I am not giving legal advice, and the LICENSE file is the text that governs.

Editorial conclusion

Adopt Zephir if you maintain a PHP extension and want its logic in a language that compiles to C, or if you are extending something like Phalcon that already uses this toolchain. Do not adopt it if you only need faster application code: opcache, JIT and profiling will get you further with far less build machinery. Before committing, verify two things against the official documentation at docs.zephir-lang.com: that a Zephir release supports the PHP version you target, and that you can build and load the extension on every platform you ship. The repository's docker-compose.yml pins local development containers to PHP 8.0 through 8.5, so that range is the one the project itself tests against.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zephir-lang/zephir on GitHub