diff --git a/AGENTS.md b/AGENTS.md index 1429ebb..2bf005e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -201,6 +201,8 @@ composer test:internal # destructive/segfault-prone group, process-isolated build** (`tools/docker/php-debug.Dockerfile`, which CI builds inline and runs the group in). Process isolation keeps one crash from taking down the whole run. +- `OpCodeHookLifecycleTest` keeps the user opcode handler install/uninstall + path covered in every CI leg (the full hook suite is internal-group only). - FFI must be enabled (`ffi.enable=1`) and the JIT disabled (`opcache.jit=off`) — the JIT rewrites the executor internals z-engine hooks into. The PHPUnit config sets what it can; `ffi.enable` and `zend.assertions` must come from diff --git a/phpstan.dist.neon b/phpstan.dist.neon index 114fe3c..9337f45 100644 --- a/phpstan.dist.neon +++ b/phpstan.dist.neon @@ -9,9 +9,8 @@ includes: parameters: level: max - # TODO: bump to 80600 once PHPStan accepts it (2.2.9 still caps phpVersion - # at 80599 while PHP 8.6 is in beta); the runtime target of this branch is 8.6 - phpVersion: 80500 + # The runtime target of this branch (PHPStan >= 2.2.16 accepts 80600) + phpVersion: 80600 # Deterministic result-cache location (gitignored, /var/) so CI can cache it tmpDir: var/phpstan paths: @@ -39,6 +38,11 @@ parameters: # Sacrificial child pinning the ext-ffi abort on zend_throw_exception_hook: # pokes the raw engine symbol through an ad-hoc FFI::cdef on purpose - tests/System/Hook/scenarios/throw-hook-ffi-abort.php + # Leak-check child iterating a stub that deliberately does NOT implement + # Traversable (engine-level get_iterator handlers are the feature under + # test): statically its foreach yields nothing, so PHPStan >= 2.3 + # constant-folds the whole stress loop into always-true/unreachable noise + - tests/Memory/scenarios/get-iterator-hook.php # Analysis-only declarations of the runtime-generated specialized classes and the # deliberately-undefined placeholder type (see the file header for the rationale), # plus the generated engine struct stubs (ZEngine\Generated\*, emitted by @@ -70,6 +74,13 @@ parameters: - identifier: offsetAccess.nonOffsetAccessible path: src/Type/StructArray.php + # Core::getVirtualMachineKind() binds a dedicated one-symbol cdef (`int zend_vm_kind(void)`): + # methods declared by cdef source are not statically resolvable, exactly like the + # engine binding behind call() - scoped to this one symbol in this one file. + - + identifier: method.notFound + message: '#Call to an undefined method FFI::zend_vm_kind\(\)#' + path: src/Core.php # The dimension tests exist to prove that a plain `count($object)` reaches the engine's # count_elements handler on a class that never declared the count itself. Rewriting them # as assertCount() would measure PHPUnit's Count constraint instead of the language @@ -77,6 +88,18 @@ parameters: - identifier: phpunit.assertCount path: tests/Reflection/ReflectionClassDimensionTest.php + # The resolution-handler tests prove the get_properties handler rebuilds the + # property table on every (array) cast. PHPStan >= 2.3 constant-folds the cast + # from the last statically-visible property write instead, so the stress loop + # that overwrites the subject 1000 times reads as a single always-true pass. + - + identifier: smaller.alwaysTrue + message: '#Comparison operation "<" between 0 and 1000 is always true#' + path: tests/Reflection/ReflectionClassResolutionHandlersTest.php + - + identifier: notIdentical.alwaysTrue + message: '#between .second. and .value0.#' + path: tests/Reflection/ReflectionClassResolutionHandlersTest.php reportUnmatchedIgnoredErrors: false treatPhpDocTypesAsCertain: false diff --git a/src/Core.php b/src/Core.php index e3abb79..4f7c71e 100644 --- a/src/Core.php +++ b/src/Core.php @@ -27,6 +27,7 @@ use ZEngine\System\Hook\ErrorCallbackHook; use ZEngine\System\Hook\InheritanceCacheAddHook; use ZEngine\System\Hook\InterruptHook; +use ZEngine\System\VmKind; use ZEngine\Type\HashTable; /** @@ -199,6 +200,11 @@ class Core */ private static FFI $engine; + /** + * Cached zend_vm_kind() answer - a compile-time property of the php binary + */ + private static ?VmKind $vmKind = null; + /** * Windows only: binding to the C runtime that owns the malloc heap, for persistentFree() * @@ -748,6 +754,28 @@ public static function platformKey(): string ); } + /** + * The engine's VM dispatch kind + * + * Read through a dedicated one-symbol FFI binding rather than the generated engine + * definitions: the answer may be needed BEFORE init() (a consumer may probe platform + * support without booting the whole engine), and a plain `int zend_vm_kind(void)` + * carries no struct layout that the generated artifacts would need to verify. + * zend_vm_kind() is ZEND_API since PHP 7, so the symbol resolves on every supported + * build. + */ + public static function getVirtualMachineKind(): VmKind + { + if (self::$vmKind === null) { + $probe = FFI::cdef('int zend_vm_kind(void);', self::engineLibrary()); + $kind = $probe->zend_vm_kind(); + \assert(\is_int($kind)); + self::$vmKind = VmKind::from($kind); + } + + return self::$vmKind; + } + /** * Library FFI::cdef() must bind the engine definitions to, or null for the process image * diff --git a/src/System/VmKind.php b/src/System/VmKind.php new file mode 100644 index 0000000..fe06e95 --- /dev/null +++ b/src/System/VmKind.php @@ -0,0 +1,42 @@ + + * + * This source file is subject to the license that is bundled + * with this source code in the file LICENSE. + * + */ +declare(strict_types=1); + +namespace ZEngine\System; + +/** + * Named view of the executor's dispatch strategy, as reported by zend_vm_kind() + * + * The backing values are the ZEND_VM_KIND_* macro values from Zend/zend_vm_opcodes.h: a + * build-time choice baked into the running binary, so the whole process always reports a + * single case. They are preprocessor macros the header generator does not export, which is + * why the decode lives here rather than behind Core::engineConstant(). + * + * @see Core::getVirtualMachineKind() + */ +enum VmKind: int +{ + /** ZEND_VM_KIND_CALL: every opcode handler is a plain function called through a dispatch table */ + case Call = 1; + + /** ZEND_VM_KIND_SWITCH: one giant switch over the opcode number inside execute_ex() */ + case Switch = 2; + + /** ZEND_VM_KIND_GOTO: computed-goto dispatch between handler labels (GCC builds) */ + case Goto = 3; + + /** ZEND_VM_KIND_HYBRID: computed-goto fast path with callable handlers kept for the slow path */ + case Hybrid = 4; + + /** ZEND_VM_KIND_TAILCALL: clang musttail/preserve_none handler chains (new in PHP 8.6) */ + case TailCall = 5; +} diff --git a/tests/System/Hook/OpCodeHookLifecycleTest.php b/tests/System/Hook/OpCodeHookLifecycleTest.php new file mode 100644 index 0000000..c6d8c57 --- /dev/null +++ b/tests/System/Hook/OpCodeHookLifecycleTest.php @@ -0,0 +1,46 @@ + + * + * This source file is subject to the license that is bundled + * with this source code in the file LICENSE. + * + */ +declare(strict_types=1); + +namespace ZEngine\System\Hook; + +use PHPUnit\Framework\TestCase; +use ZEngine\Core; +use ZEngine\System\OpCode; +use ZEngine\System\VmKind; + +/** + * The user opcode hook install/uninstall lifecycle, exercised in every CI leg + * + * Deliberately NOT in the `internal` group: the full OpCodeHookTest is internal-only, so + * this is the one hook test release builds run on every platform. The handler is never + * dispatched (no probe code is compiled while it is installed), which keeps the happy + * path safe for release builds. + */ +final class OpCodeHookLifecycleTest extends TestCase +{ + public function testVmKindIsReported(): void + { + $this->assertContains(Core::getVirtualMachineKind(), VmKind::cases(), 'zend_vm_kind() must answer one of the known VM kinds'); + } + + public function testInstallAndUninstallLifecycle(): void + { + $hook = OpCode::setHandler(OpCode::EXT_STMT, static fn($scope): int => Core::ZEND_USER_OPCODE_DISPATCH); + try { + $this->assertTrue($hook->isInstalled()); + } finally { + $hook->uninstall(); + } + $this->assertFalse($hook->isInstalled()); + } +}