Language: __callStatic magic method — static call dispatch (Zend object handlers parity)

[PurHur]

Category

language

Problem

Zend invokes __callStatic(string $name, array $args) when a static method is called on a class but no matching method exists. PurHur/php-compiler fails static calls to undefined methods at runtime today; __callStatic is not dispatched.

Related but distinct from #146 (__get / __set / __call / __toString instance magic) and #3273 sibling #3319 (PR tracker).

Frameworks use __callStatic for static proxy facades (Proxy::__callStatic forwarding to services).

php-src reference

• php/php-src Zend/zend_object_handlers.c — zend_std_get_static_method, magic fallback
• php/php-src Zend/zend_API.c — zend_call_known_static_method when method missing
• php/php-src Zend/zend_compile.c — __callStatic registered on class entry

Repro (failure today)

<?php
class Proxy {
    public static function __callStatic(string $name, array $args): string {
        return $name . ':' . count($args);
    }
}
echo Proxy::missing('a', 'b'), "\n";

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'
php repro.php

Runtime	Output
Zend PHP 8.x	missing:2
bin/vm.php	fatal / unknown static method

Maintainer probe (2026-05-30): static Proxy::missing() with __callStatic defined → compile/runtime error in lib/VM.php.

Visibility (done-when)

private __callStatic must not be callable from outside (mirror #145 static visibility rules).

Scope (this repo)

Layer	Files	Notes
VM	lib/VM.php — TYPE_STATIC_CALL	Slow path: if method missing, lookup __callStatic on class
Class metadata	lib/VM/ClassEntry.php	Store magic static method id
Compiler	lib/Compiler.php	Emit generic static dispatch (no compile-time magic name requirement)
Args	pack $args as array for second parameter (Zend subset)
JIT	lib/JIT.php	v1: VM fallback at magic sites (#146 pattern)
Tests	test/compliance/cases/language/magic_call_static.phpt

Done when

• Repro prints missing:2 on VM
• __callStatic not invoked when declared static method exists
• Private/protected __callStatic respects visibility from call site
• ./script/ci-fast.sh --filter magic_call_static green
• JIT: document VM fallback or implement phase-1 deopt

Verification

./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && vendor/bin/phpunit --filter magic_call_static'
./script/docker-exec.sh -- bash -lc 'source script/php-env.sh && php bin/vm.php repro.php'

Dependencies

• Static dispatch baseline: Language: static methods on user-defined classes (Expr_StaticCall) #2209, Language: Class methods and property access in JIT #58
• Instance magic: Language: Magic methods (__get, __set, __call, __toString) #146
• Visibility: Language: Visibility, constructors, and destructors #145

Links

• North star Epic: Self-host critical path — compiler compiles itself (M3→M5) #1492 · Wave 2 Language features wave 2: JIT/syntax gaps tracker (#1222–#1235) #1238

[PurHur]

VM __callStatic dispatch landed in PR #3229 (continuing #146 branch agent/issue-146-magic-methods). Compliance: test/compliance/cases/language/magic_call_static.phpt.

[PurHur]

claim: worker-lane-a-automation — starting this run