Runtime Compatibility

Phalcon Kit documentation supports the latest stable package release. The package’s composer.json, CI workflow, and release notes are the authorities for exact PHP, Phalcon extension, and development-tool versions.

Use this guide to verify that an application’s runtime matches those declared requirements without duplicating version numbers in application documentation.

Compatibility Has Several Layers

A working installation aligns all of these surfaces:

Changing only one layer can produce misleading results—for example, an IDE may accept a method that the loaded extension does not provide, or CLI PHP may load a different extension than PHP-FPM.

Inspect The Declared Requirements

From the application root:

composer show phalcon-kit/core
composer show phalcon/ide-stubs 2>/dev/null || true
composer check-platform-reqs

To inspect the installed native runtime directly:

php --version
php -r 'echo phpversion("phalcon") ?: "not installed", PHP_EOL;'
php --ri phalcon

Install Or Update An Application

Evergreen install instructions deliberately omit a Phalcon Kit version:

composer require phalcon-kit/core

Composer selects the newest release compatible with the application’s PHP and platform extensions. Applications that commit composer.lock should review and commit the resulting lock-file change.

For a focused update:

composer update phalcon-kit/core phalcon/ide-stubs --with-dependencies
composer check-platform-reqs

Do not use --ignore-platform-reqs as a permanent install strategy. A targeted ignore can help prepare metadata before a native extension is installed, but the final environment must pass composer check-platform-reqs without ignores.

Upgrade The Core Package Runtime

When maintainers change the supported runtime, keep the work in one reviewable slice:

1. Update PHP, ext-phalcon, and stub constraints in composer.json.
2. Update Docker build arguments and base images.
3. Update CI installers, download URLs, and extension cache keys.
4. Review upstream release notes for changed and removed APIs.
5. Search source, tests, examples, and patches for affected symbols.
6. Refresh dependency metadata and run the complete QA gate.
7. Record concrete compatibility changes in CHANGELOG.md.

Avoid mixing the runtime bump with unrelated model, schema, or API behavior. That separation makes failures attributable and makes downstream upgrades easier to review.

Review Framework Boundaries

Native runtime changes most often affect these integration points:

• DI container and service-provider contracts;
• events manager and event contract names;
• request, response, cookies, and session behavior;
• model relationships, eager loading, resultsets, and database metadata;
• router and dispatcher method signatures;
• validation, filtering, and message collections;
• debug rendering and error handling;
• PHPDoc/stub signatures used by Psalm, PHPStan, and IDEs.

Search both code and documentation. A compatibility fix is incomplete if the runtime works but public examples still teach removed APIs.

rg 'Phalcon\\|ext-phalcon|phalcon/ide-stubs|PHALCON_VERSION' \
  composer.json src tests guides .github Dockerfile*

Adjust the paths for the repository. Review every result rather than applying a blind namespace replacement.

Audit Deprecated Framework APIs

Treat the matching phalcon/ide-stubs package as the machine-readable deprecation inventory. Search its PHPDoc for @deprecated, then map every deprecated class, interface, method, and constant back to source, tests, public examples, and reusable skills.

Prefer canonical Phalcon\Contracts\... interfaces over legacy implementation namespace interfaces. Replace dispatcher aliases such as getParam(), getParams(), setParam(), and setParams() with their Parameter forms. Run PhalconDeprecationTest after every baseline upgrade so new upstream deprecations cannot silently enter published source or examples.

Some Phalcon 5.x native override signatures and canonical contracts still name legacy interfaces. Keep those exact native boundaries until upstream changes the parent signature; broadening a child signature can claim support the parent cannot actually accept. The test's narrow allowlist documents these temporary holds and will fail when a hold moves or a deprecated type is reintroduced elsewhere.

Validate In Increasing Scope

Start with fast checks:

php -m | rg '^phalcon$'
composer validate --strict --no-check-publish
composer check-platform-reqs
git diff --check

Then run package quality gates:

composer phpcs
composer psalm
composer psalm:taint
composer phpunit
composer skeleton

Finally, prove the application paths that static analysis cannot cover:

• bootstrap one HTTP request;
• run migrations against a disposable database;
• execute one representative model relationship query;
• create and update a model with validation enabled;
• run one CLI task;
• boot any long-lived worker or WebSocket process;
• build the production container from a clean cache.

Diagnose A Mismatch

Continue with Troubleshooting for application-level boot, DI, routing, database, and REST symptoms. Maintainers should also follow Quality And Maintenance and Release Process.