PHP扩展中使用HashTable需按五步操作：一、用zend_hash_init初始化；二、用str/index_add插入键值；三、用str/index_find查找元素；四、用ZEND_HASH_FOREACH_KEY_VAL遍历；五、先zend_hash_destroy再efree销毁。
如果您在开发PHP扩展时需要使用HashTable数据结构来存储和管理键值对，则可能是由于PHP内核中HashTable是实现数组、对象属性、符号表等核心功能的基础结构。以下是使用HashTable的几种主要方法：
一、初始化HashTable
HashTable必须在使用前进行初始化，以分配内存并设置默认函数指针，确保后续插入、查找等操作能正确执行。未初始化的HashTable会导致段错误或不可预测行为。
1、在zval或自定义结构体中声明HashTable成员，例如：HashTable ht;
2、调用zend_hash_init()函数进行初始化，传入地址、初始大小、哈希函数指针、析构回调、持久化标志等参数。
立即学习“PHP免费学习笔记（深入）”；
3、典型调用形式为：zend_hash_init(&ht, 0, NULL, ZVAL_PTR_DTOR, 0); 其中ZVAL_PTR_DTOR用于自动释放zval值内存。
二、向HashTable插入元素
插入操作需指定键（字符串或数字）与对应zval值，HashTable会根据键类型选择内部存储策略（索引数组或关联数组），并处理重复键的覆盖逻辑。
1、插入字符串键元素：调用zend_hash_str_add()，传入HashTable指针、键名字符串、键长、zval指针。
2、插入整数键元素：调用zend_hash_index_add()，传入HashTable指针、索引值、zval指针。
3、若需覆盖已有键且不关心返回值，可使用zend_hash_str_update()或zend_hash_index_update()；注意：这些函数会自动复制zval，调用者无需手动zval_copy_ctor()。
三、从HashTable查找元素
查找操作通过键定位对应zval地址，返回成功与否状态，常用于条件判断或值读取。查找失败时返回NULL，不应解引用该指针。
1、查找字符串键：调用zend_hash_str_find()，传入HashTable指针、键名、键长，返回zval**类型指针。
2、查找整数键：调用zend_hash_index_find()，传入HashTable指针、索引值，返回zval**类型指针。
3、若仅需判断存在性，可使用zend_hash_str_exists()或zend_hash_index_exists()；注意：所有find系列函数返回的是zval**，需通过**解引用获取实际zval值。
四、遍历HashTable中的所有元素
遍历时需借助zend_hash_get_current_key_ex()与zend_hash_get_current_data_ex()配合游标（HashTable指针与position变量），确保线性访问每个键值对，适用于导出、校验或批量处理场景。
1、声明zend_ulong key_type; zend_string *key; zend_ulong num_key; zval *val; zend_string *str_key;
2、使用ZEND_HASH_FOREACH_KEY_VAL(&ht, key_type, key, num_key, val)宏开始遍历，该宏自动管理position游标。
3、在循环体内根据key_type区分处理：若为HASH_KEY_IS_STRING，则key为zend_string*；若为HASH_KEY_IS_LONG，则num_key为整型键；注意：遍历中不得调用可能重排HashTable的修改函数（如zend_hash_del）。
五、销毁HashTable
HashTable占用的内存必须显式释放，否则造成内存泄漏。销毁操作会逐个调用注册的析构函数释放值内存，并释放HashTable自身结构内存。
1、调用zend_hash_destroy()释放所有元素内存及内部桶数组，但不释放HashTable结构体本身内存。
2、若HashTable为栈上分配（如局部变量），则无需调用efree()；若为emalloc分配，需在destroy后调用efree()释放结构体空间。
3、典型清理序列：zend_hash_destroy(&ht); efree(&ht); 注意：必须先destroy再efree，顺序颠倒将导致崩溃。
