Phalcon 4 to 5 upgrade alongside PHP 7.4 to 8.x: which compatibility breaks should I expect first?

Short answer

The first things that break in a conventional MVC app are the renamed DI and dispatcher classes, followed by the Volt compiler relocation and stricter PHQL parsing. The extension itself is the second failure surface: Phalcon 5 requires PHP 8.0+, so your 7.4 build is simply unloadable, and php -m alone won't catch an ABI or version mismatch — only a real bootstrap will. PECL binaries do sometimes lag source tags, so if you need a specific 5.x minor, compiling is the reliable path.

What breaks first in application code

Based on the documented 5.x restructuring, expect these in roughly this order:

1. DI container: Phalcon\Di\FactoryDefault remains, but the container interface and related classes were reorganized (Phalcon\Di\Di as the base). Any custom factory defaults or service providers typed against 4.x interfaces need updating.
2. Dispatcher: the standalone dispatcher moved under Phalcon\Mvc\Dispatcher. Custom dispatcher plugins or direct instantiation will fail with class-not-found immediately at bootstrap — this is usually the very first fatal error.
3. Volt: the compiler moved to Phalcon\Mvc\View\Engine\Volt\Compiler. If you register custom Volt functions or filters, they must be re-registered against the new compiler instance; otherwise templates fail at render time, not at boot, which makes this easier to miss.
4. ORM/PHQL: model manager interfaces were renamed and PHQL parsing became stricter around reserved words and aliases. Queries that parsed leniently under 4.x can throw at runtime.

Also audit composer.json: community packages built for Phalcon 4 (devtools, incubator-style helpers) frequently have no 5.x release. And remember the phalcon/phalcon metapackage only checks extension_loaded('phalcon') — it installs nothing.

PECL vs. source

PECL publishes Phalcon builds after source tags, but minor releases can lag by days to weeks, and distro-packaged builds (RHEL, Alpine) are often further behind. If you're pinning a specific 5.x minor for PHP 8.1, compiling from source guarantees the match. One caveat: treat exact lag windows as worth checking against the actual PECL page and GitHub tags at migration time rather than assuming.

Verification that actually catches mismatches

php -m | grep phalcon
php --ri phalcon   # confirms version + build PHP API

Then a staging bootstrap that exercises each subsystem:

$di = new Phalcon\Di\FactoryDefault();
$dispatcher = $di->get('dispatcher');
assert($dispatcher instanceof Phalcon\Mvc\Dispatcher);
// compile a Volt template using a custom function
// run $modelsManager->executeQuery('SELECT ... LIMIT 1');

php -m only proves the shared object loads; the bootstrap catches missing symbols and renamed classes. Finally, test on PHP 8.1 itself — engine changes (readonly properties, mixed, stricter typing) can surface latent bugs unrelated to Phalcon.