Run the application with a PHP/Phalcon combination satisfying its Composer
requirements. The current package requires PHP 8.5 or later and Phalcon
^5.23.0. Composer's platform checks are the authoritative installation check.
php --version
php --ini
php -r 'echo "PHP ", PHP_VERSION, " / Phalcon ", phpversion("phalcon") ?: "missing", PHP_EOL;'
composer check-platform-reqsThe native extension supplies Phalcon classes at runtime. phalcon/ide-stubs
provides editor/analyzer signatures and does not install or load the extension.
Keep the IDE stubs compatible with the native version you test.
| Process | Verify |
|---|---|
| Composer and CLI tasks | PHP executable and loaded CLI ini files |
| PHP-FPM | Pool's PHP binary, extension directory, ini, environment, worker user |
| Containers | PHP image, built extension ABI, runtime environment |
| WebSocket/queue workers | Supervisor command, environment, restart after dependency/config changes |
| Tests | Same native extension behavior as the deployed application |
A CLI success does not prove PHP-FPM has Phalcon loaded. Check a private runtime
health endpoint or deployment diagnostics without leaving a public phpinfo()
page. Restart long-lived workers after replacing code/config/extensions.
Use the correct PDO extension and database connection options. MySQL and MariaDB can differ in collations, SQL modes, JSON functions, and spatial/regexp support. Use Configuration for a MariaDB driver and validate the operators your API exposes on your actual database.
Keep transaction boundaries paired. Before optional rollback cleanup, check
isUnderTransaction() so cleanup does not hide the original exception. Native
model casts, decimal types, nullable values, and eager loading should be verified
with save/reload tests, not only static analysis.
Commit the application lockfile and install it in CI/deployment:
composer install --no-interaction --prefer-dist
composer check-platform-reqs
composer phpunitUse --no-dev for a runtime artifact only when development tools are not needed
there. The skeleton's migration runner is a development dependency; run migrations
from an artifact/environment that includes it. Never use --ignore-platform-reqs
as proof of runtime compatibility.
After schema changes and scaffold regeneration, clear/rebuild the application's model metadata and relevant caches, then restart persistent workers. Native Phalcon annotations can use docblocks or an attributes reader; choose the reader before caching metadata. Attribute and docblock value types can differ, so test custom metadata strategies against the model definitions you ship.
Use Troubleshooting when one runtime succeeds and another fails. Historical release changes remain in the changelog.