perf: cache property lookups across repeated accesses (#726)

When PHP reads or writes an object property (e.g. `$obj->name`), ext-php-rs
previously searched through all registered properties by name on every single
access. In a loop hitting the same property 100k times, that same search ran
100k times.

PHP provides a per-opcode "cache slot" mechanism to avoid this. On the first
access, we now store the resolved property descriptor pointer in the cache
slot. On all subsequent accesses to the same property on the same class, we
skip the search entirely and read the cached pointer directly -- a single
pointer comparison instead of string conversions and linear scans.

Applied to all three property handlers: read, write, and isset/exists.

Benchmarks (callgrind, 100k iterations):
  - Property reads:  235M -> 93.5M instructions (-60%)
  - Property writes: 220M -> 75.7M instructions (-66%)

Author: ptondereau

src/zend/handlers.rs

@@ -10,6 +10,7 @@ use crate::{
         zend_std_read_property, zend_std_write_property, zend_throw_error,
     },
     flags::{PropertyFlags, ZvalTypeFlags},
+    internal::property::PropertyDescriptor,
     types::{ZendClassObject, ZendHashTable, ZendObject, ZendStr, Zval},
 };
 
@@ -135,24 +136,23 @@ impl ZendObjectHandlers {
             cache_slot: *mut *mut c_void,
             rv: *mut Zval,
         ) -> PhpResult<*mut Zval> {
-            let prop_name = unsafe {
-                member
-                    .as_ref()
-                    .ok_or("Invalid property name pointer given")?
-            };
             let self_ = &*obj;
-            let prop = T::get_metadata().find_property(prop_name.as_str()?);
+            let prop = unsafe { resolve_property::<T>(member, cache_slot)? };
 
             // retval needs to be treated as initialized, so we set the type to null
             let rv_mut = unsafe { rv.as_mut().ok_or("Invalid return zval given")? };
             rv_mut.u1.type_info = ZvalTypeFlags::Null.bits();
 
             Ok(match prop {
                 Some(prop_info) => {
-                    // Check visibility before allowing access
                     let object_ce = unsafe { (*object).ce };
                     if !unsafe { check_property_access(prop_info.flags, object_ce) } {
                         let is_private = prop_info.flags.contains(PropertyFlags::Private);
+                        let prop_name = unsafe {
+                            member
+                                .as_ref()
+                                .ok_or("Invalid property name pointer given")?
+                        };
                         unsafe {
                             throw_property_access_error(
                                 T::CLASS_NAME,
@@ -208,21 +208,20 @@ impl ZendObjectHandlers {
             value: *mut Zval,
             cache_slot: *mut *mut c_void,
         ) -> PhpResult<*mut Zval> {
-            let prop_name = unsafe {
-                member
-                    .as_ref()
-                    .ok_or("Invalid property name pointer given")?
-            };
             let self_ = &mut *obj;
-            let prop = T::get_metadata().find_property(prop_name.as_str()?);
+            let prop = unsafe { resolve_property::<T>(member, cache_slot)? };
             let value_mut = unsafe { value.as_mut().ok_or("Invalid return zval given")? };
 
             Ok(match prop {
                 Some(prop_info) => {
-                    // Check visibility before allowing access
                     let object_ce = unsafe { (*object).ce };
                     if !unsafe { check_property_access(prop_info.flags, object_ce) } {
                         let is_private = prop_info.flags.contains(PropertyFlags::Private);
+                        let prop_name = unsafe {
+                            member
+                                .as_ref()
+                                .ok_or("Invalid property name pointer given")?
+                        };
                         unsafe {
                             throw_property_access_error(
                                 T::CLASS_NAME,
@@ -341,12 +340,7 @@ impl ZendObjectHandlers {
             has_set_exists: c_int,
             cache_slot: *mut *mut c_void,
         ) -> PhpResult<c_int> {
-            let prop_name = unsafe {
-                member
-                    .as_ref()
-                    .ok_or("Invalid property name pointer given")?
-            };
-            let prop = T::get_metadata().find_property(prop_name.as_str()?);
+            let prop = unsafe { resolve_property::<T>(member, cache_slot)? };
             let self_ = &*obj;
 
             match has_set_exists {
@@ -411,6 +405,54 @@ impl ZendObjectHandlers {
     }
 }
 
+/// Resolves a property descriptor via `cache_slot` or linear scan fallback.
+///
+/// On cache hit (`cache_slot[1]` matches this class's metadata pointer), returns
+/// the cached `&PropertyDescriptor<T>` directly, skipping string conversion and
+/// `find_property`. On miss, performs the full lookup and populates the cache for
+/// subsequent calls.
+///
+/// # Safety
+///
+/// - `member` must be a valid `ZendStr` pointer.
+/// - `cache_slot` must be null or point to at least 2 writable `*mut c_void` slots
+///   (guaranteed by PHP's opcode compiler for all property access opcodes).
+#[allow(clippy::inline_always)]
+#[inline(always)]
+unsafe fn resolve_property<T: RegisteredClass>(
+    member: *mut ZendStr,
+    cache_slot: *mut *mut c_void,
+) -> PhpResult<Option<&'static PropertyDescriptor<T>>> {
+    let meta = T::get_metadata();
+    let meta_ptr = ptr::from_ref(meta).cast::<c_void>().cast_mut();
+
+    if !cache_slot.is_null() {
+        let guard = unsafe { *cache_slot.add(1) };
+        if guard == meta_ptr {
+            let desc = unsafe { &*(*cache_slot).cast::<PropertyDescriptor<T>>() };
+            return Ok(Some(desc));
+        }
+    }
+
+    let prop_name = unsafe {
+        member
+            .as_ref()
+            .ok_or("Invalid property name pointer given")?
+    };
+    let Some(descriptor) = meta.find_property(prop_name.as_str()?) else {
+        return Ok(None);
+    };
+
+    if !cache_slot.is_null() {
+        unsafe {
+            *cache_slot = ptr::from_ref(descriptor).cast::<c_void>().cast_mut();
+            *cache_slot.add(1) = meta_ptr;
+        }
+    }
+
+    Ok(Some(descriptor))
+}
+
 /// Gets the current calling scope from the executor globals.
 ///
 /// # Safety

tests/src/integration/class/class.php

@@ -350,3 +350,32 @@ public function __construct(string $data) {
 
 $uncloneable = new TestUncloneableClass('test');
 assert_exception_thrown(fn() => clone $uncloneable, 'Cloning uncloneable class should throw');
+
+// Test cache_slot: repeated property access in a tight loop.
+// After the first access resolves via find_property, subsequent accesses should
+// hit the cache_slot fast path and return the same correct value.
+$cacheObj = test_class('cached', 999);
+for ($i = 0; $i < 1000; $i++) {
+    assert($cacheObj->string === 'cached', "Cached read failed at iteration $i");
+    assert($cacheObj->number === 999, "Cached read (number) failed at iteration $i");
+}
+
+// Test cache_slot: write then read in the same loop iteration.
+// Validates the cache returns the updated descriptor (same descriptor, new value).
+for ($i = 0; $i < 100; $i++) {
+    $cacheObj->number = $i;
+    assert($cacheObj->number === $i, "Write-then-read failed at iteration $i");
+}
+
+// Test cache_slot: isset() followed by read on the same property.
+// Both has_property and read_property share cache_slot for the same member name.
+$issetObj = test_class('isset_test', 42);
+assert(isset($issetObj->string), 'isset should return true for defined property');
+assert($issetObj->string === 'isset_test', 'Read after isset should return correct value');
+
+// Test cache_slot: visibility is still enforced after caching.
+// The cached descriptor must still go through the access check.
+$vis = new TestPropertyVisibility(1, 'secret', 'guarded');
+assert($vis->publicNum === 1, 'Public read should work before cache warms');
+assert($vis->publicNum === 1, 'Public read should work after cache warms');
+assert_exception_thrown(fn() => $vis->privateStr, 'Private access should throw even if cache_slot is warm');