Phalcon C-Extension and PHP Zend API Version Interoperability

Question

Phalcon operates as a compiled C-extension, meaning it is loaded directly into the PHP process memory. This architecture creates a strict dependency between the framework binary and the specific Zend API version of the installed PHP runtime.

When upgrading the environment, there is a risk of binary mismatch. Because the extension is loaded at process start, an incompatible version can trigger a segmentation fault, leading to a total PHP process crash rather than a catchable PHP exception.

Given that Phalcon cannot be managed via standard user-land version control, the boundary between the compiled .so/.dll file and the PHP-FPM process requires precise alignment.

What is the documented behavior for detecting a Zend API mismatch before the PHP process attempts to execute the extension?
  Are there specific configuration parameters in phalcon.ini that can mitigate process crashes during a version mismatch?

Muntasir · Answer

Answer
The PHP engine checks the extension’s declared ZEND_MODULE_API_NO against its own API number during module startup. If the numbers differ, PHP refuses to load the extension, emits a startup warning, and the request continues without Phalcon – no segmentation fault occurs at this stage.
Confirmed facts

Phalcon binaries expose the ZEND_MODULE_API_NO matching the PHP version they were compiled against.
  When the API numbers mismatch, PHP logs a warning similar to:

PHP Warning:  Unable to load dynamic library 'phalcon.so' - 
Phalcon: Unable to load extension ... API mismatch in Unknown on line 0

The extension is not initialized, so no Phalcon code runs and the PHP process does not crash due to the mismatch.
  Segfaults only appear if the binary is loaded despite the mismatch (e.g., forced via dl() or a broken build) and then calls incompatible Zend API functions.

Likely explanation
The check occurs in Zend’s module initialization routine (zend_get_module_api_no()) before any of the extension’s MINIT or RINIT hooks are executed. Therefore, a version mismatch is detected early, preventing execution of Phalcon code.
Steps to verify and resolve

Check the exact PHP version and thread‑safety mode:

php -v
php -i | grep -E "Thread Safety|ZTS"

Verify whether Phalcon loaded and if any API warning appears:

php -m | grep phalcon
php -i | grep phalcon

If a warning about API mismatch is shown or the module is missing, install the Phalcon package built for your PHP version (or rebuild from source against the matching php-dev headers).
  Restart the PHP SAPI (e.g., systemctl restart php-fpm or reload Apache).

Configuration in phalcon.ini
There are no Phalcon‑specific directives that can suppress or workaround a Zend API version mismatch. The safety check is performed by PHP itself, so the only effective mitigation is to use a correctly built extension.
Missing diagnostic detail
To confirm that the correct build type is being used, please specify whether your PHP installation is thread‑safe (ZTS) or non‑thread‑safe (NTS). This determines which Phalcon binary (phalcon_ts.so vs phalcon_nts.so) must be matched.

Phalcon C-Extension and PHP Zend API Version Interoperability

1 answer

Answer

Confirmed facts

Likely explanation

Steps to verify and resolve

Configuration in `phalcon.ini`

Missing diagnostic detail

Your perspective belongs here.

1 question comment