Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b3085b3
chore(diagnostics): add issue #280 probe ladder + temporary CI workflow
claude Aug 29, 2026
c4e7b8f
chore(diagnostics): stage markers, install-only mode, working lldb ba…
claude Aug 29, 2026
a5d85bf
fix(hook): refuse user opcode handlers on PHP 8.6's tail-call VM (#280)
claude Aug 29, 2026
b963f60
chore(diagnostics): add the pure-FFI php-src repro for the tail-call …
claude Aug 29, 2026
7d4077f
chore(diagnostics): make the issue #280 workflow dispatch-only
claude Aug 29, 2026
d88d693
ci(diagnostics): don't let the x64 control leg fail the issue #280 run
claude Sep 30, 2026
837c2b6
test: satisfy PHPStan 2.2.16's ArrayObject generics in ErrorCallbackH…
claude Sep 30, 2026
542d13a
chore(headers): refresh linux 8.6 definitions for the vm_stack page c…
claude Sep 30, 2026
f8cd6bf
chore(headers): refresh darwin arm64 8.6 definitions for the vm_stack…
claude Sep 30, 2026
0b80ea6
chore(phpstan): analyse as PHP 8.6 now that PHPStan accepts phpVersio…
claude Sep 30, 2026
73a4068
Generate darwin FFI engine definitions for PHP 8.6 (#58)
github-actions[bot] Oct 10, 2026
ddd11d9
ci(diagnostics): make the x64 control leg required again
claude Oct 10, 2026
789f14d
chore(phpstan): absorb 2.3's constant folding of the engine-handler s…
claude Oct 10, 2026
b005b3c
feat(hook): retire the tail-call VM guard - php-src fixed the dispatc…
claude Oct 10, 2026
9bbff81
Merge remote-tracking branch 'origin/master' into claude/zdebug-php-8…
claude Oct 12, 2026
432fec3
docs: drop the tail-call VM bug-fix mentions from README and AGENTS
claude Oct 12, 2026
bb73345
refactor(core): type the VM dispatch kind as the VmKind enum
claude Oct 12, 2026
ffff5b1
refactor(core): rename vmKind() to getVirtualMachineKind()
claude Oct 12, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 26 additions & 3 deletions phpstan.dist.neon
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -70,13 +74,32 @@ 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
# construct under test, so phpstan-phpunit's suggestion is declined for this file only.
-
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

Expand Down
28 changes: 28 additions & 0 deletions src/Core.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;

/**
Expand Down Expand Up @@ -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()
*
Expand Down Expand Up @@ -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
*
Expand Down
42 changes: 42 additions & 0 deletions src/System/VmKind.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
<?php

/**
* Z-Engine framework
*
* @copyright Copyright 2026, Lisachenko Alexander <lisachenko.it@gmail.com>
*
* 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;
}
46 changes: 46 additions & 0 deletions tests/System/Hook/OpCodeHookLifecycleTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
<?php

/**
* Z-Engine framework
*
* @copyright Copyright 2026, Lisachenko Alexander <lisachenko.it@gmail.com>
*
* 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());
}
}
Loading