HashTable 是 PHP 內核的「瑞士軍刀」:數組、符號表、對象屬性、函數表、類屬性、資源列表……無一不建立在 HashTable 之上。理解其 API 與數據結構,是進階 PHP 內核開發、編寫擴展、優化性能的必修課。本文梳理 zend_hash.h 導出的全部 API,並解析其四大核心組件。
zend_hash_func(),將字符串 Key 映射為整數哈希值。Bucket **arBuckets,存儲桶指針,大小為 2 的冪次,動態擴容。pNext/pLast 形成雙向鏈表,解決哈希衝突(Separate Chaining)。pListNext/pListLast 串聯,維護插入順序,支撐 foreach 遍歷。以下為 zend_hash.h 導出的核心 API(PHP 7/8 版本可能增減,以當前版本為準):
_zend_hash_init(ht, nSize, pHashFunction, pDestructor, persistent)
zend_hash_destroy(ht) // 釋放所有數據與 Bucket
zend_hash_clean(ht) // 僅清空數據,保留 Bucket 數組
zend_hash_graceful_destroy(ht) // 安全銷毀(處理遞歸)
zend_hash_copy(target, source, pCopyConstructor, tmp, size)
_zend_hash_merge(target, source, pCopyConstructor, tmp, size, overwrite)
zend_hash_merge_ex(target, source, pCopyConstructor, size, merge_checker_func, pParam)
_zend_hash_add_or_update(ht, arKey, nKeyLength, pData, nDataSize, pDest, flag)
_zend_hash_quick_add_or_update(ht, arKey, nKeyLength, h, pData, nDataSize, pDest, flag) // 預計算哈希
_zend_hash_index_update_or_next_insert(ht, h, pData, nDataSize, pDest, flag) // 數字索引
zend_hash_del_key_or_index(ht, arKey, nKeyLength, h, flag)
zend_hash_find(ht, arKey, nKeyLength, pData)
zend_hash_quick_find(ht, arKey, nKeyLength, h, pData)
zend_hash_exists(ht, arKey, nKeyLength)
zend_hash_index_find(ht, h, pData)
zend_hash_index_exists(ht, h)
zend_hash_internal_pointer_reset_ex(ht, pos)
zend_hash_internal_pointer_end_ex(ht, pos)
zend_hash_move_forward_ex(ht, pos)
zend_hash_move_backwards_ex(ht, pos)
zend_hash_get_current_key_ex(ht, str_index, str_length, num_index, duplicate, pos)
zend_hash_get_current_key_type_ex(ht, pos)
zend_hash_get_current_data_ex(ht, pData, pos)
zend_hash_update_current_key_ex(ht, key_type, str_index, str_length, num_index, mode, pos)
zend_hash_apply(ht, apply_func)
zend_hash_apply_with_argument(ht, apply_func_arg, argument)
zend_hash_apply_with_arguments(ht, apply_func_args, num_args, ...)
zend_hash_reverse_apply(ht, apply_func)
zend_hash_num_elements(ht)
zend_hash_sort(ht, sort_func, compare_func, renumber)
zend_hash_compare(ht1, ht2, compare_func, ordered)
zend_hash_minmax(ht, compare_func, flag, pData)
zend_hash_next_free_element(ht) // 下一個可用數字索引
zend_hash_display(ht)
zend_hash_display_pListTail(ht)
typedef struct _Bucket {
ulong h; // 哈希值(數字索引為索引值)
uint nKeyLength; // 鍵長(0 表示數字索引)
void *pData; // 數據指針
void *pDataPtr; // 指向數據的指針(優化小數據)
struct _Bucket *pNext; // 衝突鏈表 next
struct _Bucket *pLast; // 衝突鏈表 prev
struct _Bucket *pListNext; // 全局遍歷 next
struct _Bucket *pListLast; // 全局遍歷 prev
char arKey[1]; // 變長鍵名
} Bucket;
typedef struct _hashtable {
uint nTableSize; // Bucket 數組大小 (2^n)
uint nTableMask; // nTableSize - 1,用於快速取模
uint nNumOfElements; // 元素數量
ulong nNextFreeElement; // 下一個免費數字索引
Bucket *pInternalPointer; // 遍歷指針
Bucket *pListHead; // 全局鏈表頭
Bucket *pListTail; // 全局鏈表尾
Bucket **arBuckets; // Bucket 指針數組
dtor_func_t pDestructor; // 數據銷毀回調
zend_bool persistent; // 是否持久化分配
unsigned char nApplyCount; // 遞歸保護計數
zend_bool bApplyProtection;
} HashTable;
obj->properties 為 HashTable,動態屬性存儲。EG(function_table)、EG(class_table)、EG(zend_constants)。EG(regular_list) 追蹤所有資源(文件句柄、DB 連接等)。zend_hash_init(ht, 128, ...) 避免頻繁擴容。Z_ADDREF/Z_DELREF,防止內存洩漏或 UAF。HashTable 以「哈希表 + 雙向鏈表」混合結構,兼顧 O(1) 查找與有序遍歷,支撐了 PHP 靈活的數組語義。熟練掌握 zend_hash_* API,是編寫高性能擴展、理解核心行為、排查疑難雜癥的基石。