Document zend_get_op_array_extension_handle

This very sharp edge should have been documented long ago.

Author: morrisonlevi

Zend/zend_extensions.c

@@ -264,13 +264,35 @@ ZEND_API int zend_get_resource_handle(const char *module_name)
 	}
 }
 
+/**
+ * The handle returned by this function can be used with
+ * `ZEND_OP_ARRAY_EXTENSION(op_array, handle)`.
+ *
+ * The extension slot has been available since PHP 7.4 on user functions and
+ * has been available since PHP 8.2 on internal functions.
+ * 
+ * # Safety
+ * The extension slot made available by calling this function is initialized on
+ * the first call made to the function in that request. If you need to
+ * initialize it before this point, call `zend_init_func_run_time_cache`.
+ *
+ * The function cache slots are not available if the function is a trampoline,
+ * which can be checked with something like:
+ * 
+ *     if (fbc->type == ZEND_USER_FUNCTION
+ *         && !(fbc->op_array.fn_flags & ZEND_ACC_CALL_VIA_TRAMPOLINE)
+ *     ) {
+ *         // Use ZEND_OP_ARRAY_EXTENSION somehow
+ *     }
+ */  
 ZEND_API int zend_get_op_array_extension_handle(const char *module_name)
 {
 	int handle = zend_op_array_extension_handles++;
 	zend_add_system_entropy(module_name, "zend_get_op_array_extension_handle", &zend_op_array_extension_handles, sizeof(int));
 	return handle;
 }
 
+/** See zend_get_op_array_extension_handle for important usage information. */
 ZEND_API int zend_get_op_array_extension_handles(const char *module_name, int handles)
 {
 	int handle = zend_op_array_extension_handles;