Back to Blog
TypePHP’s Compatibility Trap (What Will Not Port From Everyday PHP)
TypePHP is not drop-in PHP. Their docs split gaps into Hard Limit, Intentional Rule, Pending, and Partial. Learn that vocabulary before you rewrite a Laravel app.
Back
Engineering
Table of contents
TypePHP’s Compatibility Trap (What Will Not Port From Everyday PHP)
After what TypePHP actually is and a Mac hello with --nano, the next honest question is not “how fast?”
It is what breaks when you bring everyday PHP habits into an AOT compiler.
TypePHP answers that in its own docs, not in marketing. The useful part is their vocabulary: Hard Limit, Intentional Rule, Pending, and Partial. Mix those up and you either panic (“this can never work”) or daydream (“Laravel next weekend”).
The trap
The trap is assuming TypePHP is “PHP, but compiled.”
It is closer to a PHP-shaped language with AOT constraints. Some gaps are temporary. Some are permanent design. Some “work,” but not the Zend story you remember from FPM apps.
If you only read a hello world, you miss that.
Hard Limit means do not expect exact PHP parity. Intentional Rule means rewrite for good; this is product design. Pending means unsupported now and maybe later. Partial means it works with a documented boundary. That vocabulary alone is worth skimming PHP_INCOMPATIBILITY_CLASSIFICATION.md. Blog posts that only say “unsupported” without a label get sloppy fast.
What hits you first
Before fancy types, structure rules show up.
No executable statements at global scope. Declarations, use, declare, and constants are fine. A top-level echo is not. Nested function declarations and nested named classes are out. Binary mode wants a global main() that returns void, either with no args or with int $argc, array $argv.
That is why a normal “open a file and start coding” PHP script fails the TypePHP path even when tpc.php --help works. The entry model changed. Soft typing is gone too: TypePHP is always strict, so strict_types=0 is rejected and strict_types=1 is basically redundant.
A few Intentional Rules feel like “broken PHP” if you come from app code. Non-variadic functions are strict about argument count; func_get_args() does not quietly make you variadic. A default parameter before a required one is rejected, even though legacy PHP treated that as “default ignored.” Once a local is inferred as a concrete native type, reassigning an incompatible type in the same scope is rejected. Reserved conversion methods like toInt(), toString(), and toArray(), plus non-overridable toAny() / toRef(), have TypePHP-specific rules.
Those are not “the compiler is unfinished.” They are the cost of fixed storage and static lowering.
Partial hope, Pending caution
eval() is the Partial example I keep in my head. Docs say it can execute PHP through the Zend VM, but it cannot see compiled locals. Return results explicitly (a returned static closure is the documented pattern). Do not use $GLOBALS. Learn that boundary once so it does not become a weekly surprise.
Pending items are implementable later, not promised on your roadmap: variable variables ($$var), closures or arrow functions returning by reference, PHP 8.5 #[NoDiscard], and a pile of foreach / match / dynamic-name edges listed in the classification doc.
Dynamic calls are Partial too. Zend fallback can handle dynamic calls and callbacks, but by-reference arguments still need explicit std::ref() / toRef(), and native-call optimization is not guaranteed.
If your codebase treats dynamic PHP as a feature (variable variables, heavy eval, signature-unknown callbacks with references), TypePHP is a research project for that code. It is not a migration button.
If you live in Laravel / FPM
I would not start with “compile the app.”
I would start with a CLI tool or worker that has a clear main, types I am willing to keep stable, and a checklist against Hard Limit / Intentional Rule before I promise stakeholders a port.
Laravel’s request lifecycle assumes bootstrap, globals, and frameworks that love dynamic dispatch. TypePHP can still matter beside that stack as extensions, native helpers, or CPU-heavy workers. As a whole-app replacement it is a poor first goal.
My take
The compatibility trap is emotional as much as technical.
You see a PHP file become a binary and your brain fills in “my PHP.” The docs are clearer than that feeling. Some rules are intentional. Some are pending. Some are partial with sharp edges.
Read INCOMPATIBLE_PHP_FEATURES.md and PHP_INCOMPATIBILITY_CLASSIFICATION.md before you schedule a rewrite. The labels tell you whether to redesign, wait, or keep that path on Zend PHP.
TypePHP stays interesting. It just stops being a fantasy once you respect the trap.
Sources
Checked against the TypePHP docs on 20 November 2026 (release v0.10.1).
Comments
No comments yet
Loading comments...