Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
19 changes: 19 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,6 +271,25 @@ line, the fix is a named public method here, not a reach-through there: class-ta
eviction became `ClassSpecializer::evict()` and `sizeof(type(...))` became
`Core::sizeOfType()` for exactly that reason.

**Every raw accessor carries `@internal`.** A public method that returns a raw
`FFI\CData`/`FFI\CType`, or a generated stub view (a CData handle at run time), is marked
`@internal` in the docblock right above it. Keep one docblock per method: PHP and PHPStan
read only the last one, so an `@internal` in an earlier, stacked block is lost. A class
marked `@internal` as a whole (`StructArray`, `FunctionLikeInterface`) covers its methods.
`tools/phpstan/RawEngineAccessorRule.php` enforces this for `ZEngine\Type` and
`ZEngine\Reflection`. Name a new accessor by what it hands out:

- `getRawValue()`: the struct the wrapper owns (`StringEntry`, `ObjectEntry`, `HashTable`,
`ReflectionClass`, `ReflectionValue`, ...).
- `getRaw<Thing>()`: a struct reached through the owned one
(`ReflectionValue::getRawString()`, `ClosureEntry::getRawFunction()`,
`ResourceEntry::getRawData()`).
- `get<Field>Pointer()`: a view into one field or embedded part of the owned struct
(`ObjectEntry::getPropertyTablePointer()`, `getOpArrayPointer()`).

`FunctionLikeInterface::getEntryPointer()` is older than this convention (by it, the name
would be `getRawValue()`); existing names stay as they are, so callers do not break.

## Engine structs are owned by their reflection/type class, never poked from call sites

This applies to EVERY class: if a class is responsible for a structure, then all external
Expand Down
5 changes: 5 additions & 0 deletions phpstan.dist.neon
Original file line number Diff line number Diff line change
Expand Up @@ -85,3 +85,8 @@ services:
-
class: ZEngine\PHPStan\TypedEntryPointReturnExtension
tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension]

# Every public method of ZEngine\Type / ZEngine\Reflection that returns a raw CData/CType or a
# generated struct stub view must carry @internal (AGENTS.md, issue #194)
rules:
- ZEngine\PHPStan\RawEngineAccessorRule
10 changes: 5 additions & 5 deletions src/Reflection/ClassSpecializer.php
Original file line number Diff line number Diff line change
Expand Up @@ -79,11 +79,6 @@ class ClassSpecializer
'__unserialize',
];

/**
* ce_flags that describe the storage location of the source class (shared memory,
* opcache file cache, preload region) and must never travel onto a runtime copy
* that lives in plain request memory
*/
/**
* The three operand slots of a zend_op, paired with the field naming their node type
*
Expand All @@ -95,6 +90,11 @@ class ClassSpecializer
'result_type' => 'result',
];

/**
* ce_flags that describe the storage location of the source class (shared memory,
* opcache file cache, preload region) and must never travel onto a runtime copy
* that lives in plain request memory
*/
private const STORAGE_CE_FLAGS = ['ZEND_ACC_IMMUTABLE', 'ZEND_ACC_CACHED', 'ZEND_ACC_FILE_CACHED', 'ZEND_ACC_PRELOADED'];

/**
Expand Down
29 changes: 14 additions & 15 deletions src/Reflection/FunctionLikeTrait.php
Original file line number Diff line number Diff line change
Expand Up @@ -751,19 +751,6 @@ public function getStaticVariables(): ?HashTable
return HashTable::fromCData($defaultTable);
}

/**
* Dereferences the offset form of a ZEND_MAP_PTR field into the per-process map-ptr area
*
* The slot address is CG(map_ptr_base) + offset: the engine pre-biases the base, so no
* -1 adjustment is applied (see zend_map_ptr.h:ZEND_MAP_PTR_OFFSET2PTR and the identical
* arithmetic in StringEntry::setCachedClassEntry()). The bound check mirrors
* ZSTR_VALID_CE_CACHE: a slot beyond CG(map_ptr_last) was never handed out.
*
* @param int $slotOffset Raw field value with the low bit set (ZEND_MAP_PTR_IS_OFFSET)
*
* @return CData|null HashTable* stored in the slot, or null while the slot is not yet
* materialized (or the map-ptr area cannot vouch for it)
*/
/**
* Returns the materialized live static-variables table of this user function as the raw
* `HashTable *`, or null while no call has bound the statics yet (both slot forms, see
Expand Down Expand Up @@ -792,6 +779,19 @@ public function getLiveStaticsPointer(): ?object
return Core::cast(HashTableStruct::class, $materialized);
}

/**
* Dereferences the offset form of a ZEND_MAP_PTR field into the per-process map-ptr area
*
* The slot address is CG(map_ptr_base) + offset: the engine pre-biases the base, so no
* -1 adjustment is applied (see zend_map_ptr.h:ZEND_MAP_PTR_OFFSET2PTR and the identical
* arithmetic in StringEntry::setCachedClassEntry()). The bound check mirrors
* ZSTR_VALID_CE_CACHE: a slot beyond CG(map_ptr_last) was never handed out.
*
* @param int $slotOffset Raw field value with the low bit set (ZEND_MAP_PTR_IS_OFFSET)
*
* @return CData|null HashTable* stored in the slot, or null while the slot is not yet
* materialized (or the map-ptr area cannot vouch for it)
*/
private function dereferenceMapPointerSlot(int $slotOffset): ?CData
{
$mapPointerBase = Core::$compiler->getMapPointerBaseAddress();
Expand Down Expand Up @@ -1044,8 +1044,7 @@ public function getAddress(): int
*
* @internal shared with the body-swap machinery (FunctionBodySwap), which performs
* the low-level engine surgery on the entry
*/
/**
*
* @return zend_function|zend_internal_function
*/
public function getEntryPointer(): object
Expand Down
12 changes: 5 additions & 7 deletions src/Reflection/ReflectionClass.php
Original file line number Diff line number Diff line change
Expand Up @@ -819,8 +819,7 @@ public function bindClassNameCache(?ReflectionClass $namesake = null): void
* this class over poking fields on the result.
*
* @internal shared with the hot-swap machinery (ClassDelta/HotSwap)
*/
/**
*
* @return zend_class_entry
*/
public function getRawValue(): object
Expand Down Expand Up @@ -2175,8 +2174,7 @@ private function compactStaticMembersTables(array $ownStaticInfos, int $zvalSize
* table (zend_class_init_statics) and every further access goes through it. Map-ptr
* offsets (low bit set, opcache-shared classes) and the legacy case where the map ptr
* aliases default_static_members_table are reported as null - nothing extra to fix then.
*/
/**
*
* @return zval|null Pointer to the first zval slot of the materialized table
*/
private function getMaterializedStaticMembersTable(): ?object
Expand Down Expand Up @@ -2932,6 +2930,9 @@ private function keepLazyLinkingCopyProcessLocal(string $handlerName): void
*
* This method is useful within create_object handler
*
* @internal hands out a raw zend_object pointer - consumers create objects through
* CreateObjectHook::proceed() instead
*
* @param CData|zend_class_entry $classType zend_class_entry type to create
* @param bool $persistent Whether object should be allocated persistent or not. Low-level feature!
*
Expand Down Expand Up @@ -2990,9 +2991,6 @@ private function hasParentClass(): bool
/**
* Performs low-level initialization of fields
*
* @param CData $classEntry
*/
/**
* @param CData|zend_class_entry $classEntry
*/
private function initLowLevelStructures(object $classEntry): void
Expand Down
2 changes: 2 additions & 0 deletions src/Reflection/ReflectionClassConstant.php
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ public static function fromRawEntry(object $constantEntry): ReflectionClassConst
* The pointer is a live view into engine memory; prefer the typed accessors
* (getReflectionValue(), equals(), getDeclaringClass()) over poking fields.
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_class_constant
*/
public function getRawValue(): object
Expand Down
33 changes: 16 additions & 17 deletions src/Reflection/ReflectionMethod.php
Original file line number Diff line number Diff line change
Expand Up @@ -194,21 +194,6 @@ private static function publicationBoard(): object
return self::$publicationBoard;
}

/**
* Binds the zend_function embedded into a closure to the given class as a method
*
* All function surgery goes through the wrapper API: the entry is renamed, attached to
* the class scope and stripped of its ZEND_ACC_CLOSURE flag. The caller stays responsible
* for the closure lifetime (the embedded zend_function lives inside the closure object)
* and for publishing the function in the class method table.
*
* Note: the native reflection state of the returned wrapper is not initialized (the
* method is not registered in the class yet), so only the low-level API is usable on it.
* Re-wrap the function after publishing to get a fully functional reflection, like
* ReflectionClass::addMethod() does.
*
* @internal
*/
/**
* Creates a low-level reflection over a raw zend_function structure without
* initializing the native reflection state
Expand All @@ -221,8 +206,7 @@ private static function publicationBoard(): object
* isUserDefined()/isRemovable()) is usable, native introspection is not.
*
* @internal used by the hot-swap machinery (ClassDelta)
*/
/**
*
* @param CData|zend_function|zend_internal_function $functionEntry
*/
public static function fromRawEntry(object $functionEntry): ReflectionMethod
Expand All @@ -235,6 +219,21 @@ public static function fromRawEntry(object $functionEntry): ReflectionMethod
return $reflectionMethod;
}

/**
* Binds the zend_function embedded into a closure to the given class as a method
*
* All function surgery goes through the wrapper API: the entry is renamed, attached to
* the class scope and stripped of its ZEND_ACC_CLOSURE flag. The caller stays responsible
* for the closure lifetime (the embedded zend_function lives inside the closure object)
* and for publishing the function in the class method table.
*
* Note: the native reflection state of the returned wrapper is not initialized (the
* method is not registered in the class yet), so only the low-level API is usable on it.
* Re-wrap the function after publishing to get a fully functional reflection, like
* ReflectionClass::addMethod() does.
*
* @internal
*/
public static function fromClosureEntry(
ClosureEntry $closureEntry,
string $className,
Expand Down
20 changes: 19 additions & 1 deletion src/Reflection/ReflectionValue.php
Original file line number Diff line number Diff line change
Expand Up @@ -386,6 +386,8 @@ public function getIndirectValue(): self
/**
* Type-friendly getter to return zend_class_entry directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_class_entry
*/
public function getRawClass(): object
Expand All @@ -402,6 +404,8 @@ public function getRawClass(): object
/**
* Type-friendly getter to return zend_function/zend_internal_function directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_function|zend_internal_function
*/
public function getRawFunction(): object
Expand All @@ -423,6 +427,8 @@ public function getRawFunction(): object
/**
* Type-friendly getter to return zend_string directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_string
*/
public function getRawString(): object
Expand All @@ -439,6 +445,8 @@ public function getRawString(): object
/**
* Type-friendly getter to return zend_array directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_array
*/
public function getRawArray(): object
Expand All @@ -455,6 +463,8 @@ public function getRawArray(): object
/**
* Type-friendly getter to return zend_object directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_object
*/
public function getRawObject(): object
Expand All @@ -471,6 +481,8 @@ public function getRawObject(): object
/**
* Type-friendly getter to return zend_resource directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_resource
*/
public function getRawResource(): object
Expand All @@ -485,7 +497,9 @@ public function getRawResource(): object
}

/**
* Type-friendly getter to return zend_resource directly
* Type-friendly getter to return zend_reference directly
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_reference
*/
Expand Down Expand Up @@ -528,6 +542,8 @@ public function dereference(): self
/**
* Type-friendly getter to return pointer
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return \FFI\CData
*/
public function getRawPointer(): object
Expand All @@ -548,6 +564,8 @@ public function getRawPointer(): object
* state and writes go straight to the engine. Prefer the typed accessors
* (getType(), getNativeValue(), equals()) over poking fields on the result.
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zval
*/
public function getRawValue(): object
Expand Down
2 changes: 2 additions & 0 deletions src/Type/ClosureEntry.php
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,8 @@ public function setThis(object $object): void
/**
* Returns raw zend_function data for this closure
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_function
*/
public function getRawFunction(): object
Expand Down
9 changes: 5 additions & 4 deletions src/Type/ObjectEntry.php
Original file line number Diff line number Diff line change
Expand Up @@ -343,9 +343,9 @@ public function getDynamicPropertiesPointer(): ?object
*
* No refcounting is performed on either the previous or the new table - the caller
* keeps ownership of both, exactly like setClass() does for class entries.
*
* @internal
*/
/**
*
* @param CData|HashTableStruct|null $hashTable
*/
public function setDynamicPropertiesPointer(?object $hashTable): void
Expand All @@ -372,6 +372,8 @@ public function setHandlers(object $handlers): void
/**
* Returns raw C value entry
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_object
*/
public function getRawValue(): object
Expand Down Expand Up @@ -439,8 +441,7 @@ protected function doRelease(bool $ownsReference, bool $ownsContainer): void

/**
* Performs low-level initialization of object
*/
/**
*
* @param CData|zend_object $pointer
*/
private function initLowLevelStructures(object $pointer): void
Expand Down
2 changes: 2 additions & 0 deletions src/Type/OpLine.php
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,8 @@ public function __construct(object $opline, ?ExecutionData $context = null)
/**
* Returns a raw pointer to the opcode handler
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return \FFI\CData
*/
public function getHandler(): object
Expand Down
2 changes: 2 additions & 0 deletions src/Type/PersistentObjectFactory.php
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,8 @@ final class PersistentObjectFactory
* the caller releases it the same way it does the
* rest of that region.
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_object zend_object* in persistent memory, not yet registered in the store
*/
public static function persistentClone(object $sourceObject, ?Allocator $allocator = null): object
Expand Down
2 changes: 2 additions & 0 deletions src/Type/ResourceEntry.php
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,8 @@ public function getHandle(): int
/**
* Returns the low-level raw data, associated with this resource
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return \FFI\CData
*/
public function getRawData(): object
Expand Down
2 changes: 2 additions & 0 deletions src/Type/StringEntry.php
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,8 @@ public static function persistentInterned(string $value, ?Allocator $allocator =
/**
* Returns raw C value entry
*
* @internal raw-CData escape hatch for the core layer (see AGENTS.md)
*
* @return zend_string
*/
public function getRawValue(): object
Expand Down
Loading
Loading