Merge pull request #2 from phan/optimize-array-shape-cache

Add phan_array_shape_cache_key()

Author: rlerdorf

README.md

@@ -97,6 +97,27 @@ if (function_exists('phan_unique_union_id')) {
 return UnionType::generateUniqueIdFallback($this->type_set, $this->real_type_set);
 ```
 
+### `phan_array_shape_cache_key(array $field_types, bool $is_nullable): string`
+
+Generate the stable cache key used by `ArrayShapeType::fromFieldTypes()` without allocating intermediate PHP structures.
+
+**Description**:
+Produces a deterministic ASCII key incorporating field identifiers and their union type ids, plus the nullable flag. This replaces the PHP logic that built a temporary array and called `serialize()`.
+
+**Performance advantages**:
+- Avoids repeated `serialize()` calls and temporary arrays.
+- Reuses `generateUniqueId()`/`phan_unique_union_id()` from C without bouncing through PHP.
+- Emits a compact key suited for static caches.
+
+**Usage in Phan**:
+```php
+if (function_exists('phan_array_shape_cache_key')) {
+    $cache_key = phan_array_shape_cache_key($field_types, $is_nullable);
+} else {
+    $cache_key = ArrayShapeType::generateCacheKeyFallback($field_types, $is_nullable);
+}
+```
+
 ## Benchmark
 
 Test with varying array sizes of Type objects:

phan_helpers.c

@@ -27,6 +27,7 @@
 #include "ext/hash/php_hash_xxhash.h"
 #include "Zend/zend_smart_str.h"
 #include "Zend/zend_sort.h"
+#include "Zend/zend_interfaces.h"
 #include "php_phan_helpers.h"
 #include "phan_helpers_arginfo.h"
 #include "Zend/zend_exceptions.h"
@@ -135,6 +136,18 @@ static void phan_swap_zend_long(void *a, void *b)
     *(zend_long *)b = tmp;
 }
 
+static void phan_smart_str_append_long(smart_str *str, zend_long value)
+{
+    zend_string *tmp = zend_long_to_str(value);
+    smart_str_append(str, tmp);
+    zend_string_release_ex(tmp, 0);
+}
+
+static void phan_smart_str_append_size(smart_str *str, size_t value)
+{
+    phan_smart_str_append_long(str, (zend_long)value);
+}
+
 /* {{{ PHP_FUNCTION(phan_unique_union_id)
  * Builds the unique union identifier composed of sorted object ids.
  *
@@ -222,6 +235,87 @@ PHP_FUNCTION(phan_unique_union_id)
 }
 /* }}} */
 
+/* {{{ PHP_FUNCTION(phan_array_shape_cache_key)
+ * Builds a deterministic cache key for ArrayShapeType::fromFieldTypes().
+ *
+ * Arguments:
+ *   array $field_types - map of field keys to UnionType/AnnotatedUnionType instances
+ *   bool $is_nullable  - whether the array shape is nullable
+ *
+ * Returns:
+ *   string - cache key
+ */
+PHP_FUNCTION(phan_array_shape_cache_key)
+{
+    zval *field_types;
+    zend_bool is_nullable;
+
+    ZEND_PARSE_PARAMETERS_START(2, 2)
+        Z_PARAM_ARRAY(field_types)
+        Z_PARAM_BOOL(is_nullable)
+    ZEND_PARSE_PARAMETERS_END();
+
+    HashTable *ht = Z_ARRVAL_P(field_types);
+    smart_str key = {0};
+    zval *entry;
+    zend_ulong idx;
+    zend_string *str_key;
+
+    smart_str_appendc(&key, is_nullable ? '1' : '0');
+
+    ZEND_HASH_FOREACH_KEY_VAL(ht, idx, str_key, entry) {
+        smart_str_appendc(&key, '|');
+        if (str_key) {
+            smart_str_appendc(&key, 'S');
+            smart_str_appendc(&key, ':');
+            phan_smart_str_append_size(&key, ZSTR_LEN(str_key));
+            smart_str_appendc(&key, ':');
+            smart_str_append(&key, str_key);
+        } else {
+            smart_str_appendc(&key, 'I');
+            smart_str_appendc(&key, ':');
+            phan_smart_str_append_long(&key, (zend_long)idx);
+        }
+
+        smart_str_appendc(&key, ':');
+
+        if (UNEXPECTED(Z_TYPE_P(entry) != IS_OBJECT)) {
+            zval tmp;
+            ZVAL_COPY(&tmp, entry);
+            convert_to_string(&tmp);
+            phan_smart_str_append_size(&key, Z_STRLEN(tmp));
+            smart_str_appendc(&key, ':');
+            smart_str_append(&key, Z_STR(tmp));
+            zval_ptr_dtor(&tmp);
+            continue;
+        }
+
+        zval retval;
+        ZVAL_UNDEF(&retval);
+        zend_call_method_with_0_params(Z_OBJ_P(entry), Z_OBJCE_P(entry), NULL, "generateuniqueid", &retval);
+        if (UNEXPECTED(Z_TYPE_P(&retval) == IS_UNDEF)) {
+            smart_str_free(&key);
+            RETURN_EMPTY_STRING();
+        }
+        if (UNEXPECTED(Z_TYPE(retval) != IS_STRING)) {
+            convert_to_string(&retval);
+        }
+
+        phan_smart_str_append_size(&key, Z_STRLEN(retval));
+        smart_str_appendc(&key, ':');
+        smart_str_append(&key, Z_STR(retval));
+        zval_ptr_dtor(&retval);
+    } ZEND_HASH_FOREACH_END();
+
+    smart_str_0(&key);
+    if (!key.s) {
+        RETURN_EMPTY_STRING();
+    }
+
+    RETURN_STR(key.s);
+}
+/* }}} */
+
 /* Forward declarations for XXH3-128-based hashing with normalization */
 static void phan_hash_node_xxh3(smart_str *str, zval *node);
 static void phan_hash_value_xxh3(smart_str *str, zval *val);
@@ -482,6 +576,7 @@ PHP_FUNCTION(phan_ast_hash)
 static const zend_function_entry phan_helpers_functions[] = {
     PHP_FE(phan_unique_types, arginfo_phan_unique_types)
     PHP_FE(phan_unique_union_id, arginfo_phan_unique_union_id)
+    PHP_FE(phan_array_shape_cache_key, arginfo_phan_array_shape_cache_key)
     PHP_FE(phan_ast_hash, arginfo_phan_ast_hash)
     PHP_FE_END
 };

phan_helpers_arginfo.h

@@ -10,6 +10,11 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_phan_unique_union_id, 0, 1, IS_S
 	ZEND_ARG_TYPE_INFO(0, real_type_list, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_phan_array_shape_cache_key, 0, 2, IS_STRING, 0)
+	ZEND_ARG_TYPE_INFO(0, field_types, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO(0, is_nullable, _IS_BOOL, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_phan_ast_hash, 0, 1, IS_STRING, 0)
 	ZEND_ARG_INFO(0, node)
 ZEND_END_ARG_INFO()

php_phan_helpers.h

@@ -26,6 +26,7 @@ extern zend_module_entry phan_helpers_module_entry;
 
 PHP_FUNCTION(phan_unique_types);
 PHP_FUNCTION(phan_unique_union_id);
+PHP_FUNCTION(phan_array_shape_cache_key);
 PHP_MINFO_FUNCTION(phan_helpers);
 
 #endif  /* PHP_PHAN_HELPERS_H */