Inside Zend API: Direct Allocation and Manipulation of Zend Variables (zvals) and HashTables in C

Understanding zvals: The Core of PHP Data Representation

At the heart of the Zend Engine, the runtime environment for PHP, lies the zval (Zend Value). This is not merely a data type; it’s a sophisticated structure that encapsulates not only the value itself but also its type and reference count. Understanding zval manipulation is paramount for anyone delving into PHP extension development, performance optimization at the C level, or debugging complex memory issues within the engine.

A zval is typically represented by the zval struct in C. This struct contains a union for the actual data and metadata fields for type and reference counting. The union allows a single zval to hold various PHP types (integers, strings, arrays, objects, etc.) efficiently.

Direct zval Allocation and Initialization in C

When developing PHP extensions, you’ll frequently need to create and manage zvals directly. The Zend API provides functions for this purpose, ensuring proper memory management and type safety. The most fundamental functions are ALLOC_ZVAL and its type-specific initializers.

Allocating a zval

ALLOC_ZVAL(zval_ptr) is the macro used to allocate memory for a new zval. It returns a pointer to the newly allocated zval. It’s crucial to remember that this only allocates the structure; the actual value and type need to be set afterward.

Initializing zvals with Specific Types

The Zend API offers a suite of macros and functions to initialize a zval with a specific type and value. These macros handle setting the type, initializing the union member, and setting the reference count to 1.

Integer zvals

To create an integer zval:

#include "Zend/zend.h" // For ALLOC_ZVAL, IS_LONG, etc.
#include "Zend/zend_API.h" // For zend_make_printable_zval, etc.

// ... inside your C function ...

zval *my_int_zval;
ALLOC_ZVAL(my_int_zval);
ZVAL_LONG(my_int_zval, 12345); // Initializes my_int_zval to type IS_LONG with value 12345
// Remember to use zval_ptr_dtor(my_int_zval) when done to free memory.

String zvals

String zvals require careful handling of memory. The Zend API provides functions like ZVAL_STRING and ZVAL_STRINGL. ZVAL_STRING copies the provided C string, while ZVAL_STRINGL allows specifying the length, which is more efficient if the string is already null-terminated but you want to avoid scanning for it.

#include "Zend/zend.h"
#include "Zend/zend_API.h"

// ...

zval *my_string_zval;
char *my_c_string = "Hello, Zend API!";
size_t my_c_string_len = strlen(my_c_string);

ALLOC_ZVAL(my_string_zval);
// ZVAL_STRING(my_string_zval, my_c_string); // Copies the string, allocates memory for it.
ZVAL_STRINGL(my_string_zval, my_c_string, my_c_string_len, 1); // The last argument (1) indicates to copy the string. If 0, it uses the provided pointer directly (use with caution).

// Remember to use zval_ptr_dtor(my_string_zval) when done.

Array zvals

Arrays are fundamental. Initializing an empty array zval is straightforward.

#include "Zend/zend.h"
#include "Zend/zend_API.h"

// ...

zval *my_array_zval;
ALLOC_ZVAL(my_array_zval);
array_init(my_array_zval); // Initializes the zval as an empty array (type IS_ARRAY)

// Remember to use zval_ptr_dtor(my_array_zval) when done.

Object zvals

Creating object zvals involves instantiating a class. This is typically done using object_init_ex or object_init, which requires a zend_class_entry pointer.

#include "Zend/zend.h"
#include "Zend/zend_API.h"
#include "Zend/zend_objects.h" // For object_init_ex

// Assuming you have a zend_class_entry *my_class_entry defined elsewhere

zval *my_object_zval;
ALLOC_ZVAL(my_object_zval);
object_init_ex(my_object_zval, my_class_entry); // Initializes the zval as an object of the specified class

// Remember to use zval_ptr_dtor(my_object_zval) when done.

Working with HashTables: The Backbone of Arrays and Objects

PHP’s arrays and object properties are implemented using HashTable structures. These are highly optimized hash tables designed for efficient key-value storage. Direct manipulation of HashTables is common when building complex data structures or when interacting with internal PHP data.

The HashTable Structure

A HashTable struct contains pointers to buckets, a hash function, size information, and flags. The core of its operation involves mapping keys (strings or integers) to array indices where the actual data (stored in Buckets) resides.

Common HashTable Operations

The Zend API provides a rich set of functions for interacting with HashTables. These include adding elements, retrieving elements, iterating, and deleting elements.

Adding Elements to a HashTable

The primary function for adding elements is zend_hash_update. It takes the hash table, the key (as a zval), and the value (as a zval) and inserts or updates the entry.

#include "Zend/zend.h"
#include "Zend/zend_API.h"
#include "Zend/zend_hash.h" // For zend_hash_update, zend_hash_keys, etc.

// ... assuming my_array_zval is an initialized array zval ...

zval *key_zval;
zval *value_zval;

// Add an integer value with a string key
ALLOC_ZVAL(key_zval);
ZVAL_STRING(key_zval, "count", 1); // Copy the string "count"

ALLOC_ZVAL(value_zval);
ZVAL_LONG(value_zval, 42);

// Update the hash table. The last argument is a pointer to the zval to be inserted.
// If the key exists, the old value is replaced and its refcount decremented.
// If the key doesn't exist, a new entry is created.
zend_hash_update(Z_ARRVAL_P(my_array_zval), Z_STRVAL_P(key_zval), Z_STRLEN_P(key_zval), value_zval, 0, NULL);

// Clean up temporary zvals (important!)
zval_ptr_dtor(&key_zval);
zval_ptr_dtor(&value_zval);

// Note: zend_hash_update takes ownership of value_zval if successful.
// If you want to keep your original value_zval, you'd need to increment its refcount before passing it.
// For example: Z_ADDREF_P(value_zval); zend_hash_update(..., value_zval, ...);
// Then, you'd still call zval_ptr_dtor(&value_zval) for your original pointer.

Retrieving Elements from a HashTable

zend_hash_find is used to retrieve an element by its key. It returns a pointer to the zval if found, or NULL otherwise.

#include "Zend/zend.h"
#include "Zend/zend_API.h"
#include "Zend/zend_hash.h"

// ... assuming my_array_zval is an initialized array zval with "count" => 42 ...

zval *found_zval;
zval key_zval; // No need to ALLOC_ZVAL for temporary keys used with zend_hash_find

ZVAL_STRING(&key_zval, "count", 0); // Use temporary zval, don't copy

if (zend_hash_find(Z_ARRVAL_P(my_array_zval), Z_STRVAL(key_zval), Z_STRLEN(key_zval), &found_zval) == SUCCESS) {
    // found_zval now points to the zval with value 42
    if (Z_TYPE_P(found_zval) == IS_LONG) {
        long count_value = Z_LVAL_P(found_zval);
        // Use count_value
    }
}

// No need to zval_ptr_dtor for temporary zvals used with zend_hash_find.

Iterating over a HashTable

Iteration is typically done using zend_hash_internal_pointer_reset, zend_hash_get_current_key, zend_hash_get_current_data, and zend_hash_move_forward. This allows you to traverse all key-value pairs.

#include "Zend/zend.h"
#include "Zend/zend_API.h"
#include "Zend/zend_hash.h"

// ... assuming my_array_zval is an initialized array zval ...

zval *current_zval;
zend_string *current_key;
long index;

zend_hash_internal_pointer_reset(Z_ARRVAL_P(my_array_zval));

while (zend_hash_get_current_key(Z_ARRVAL_P(my_array_zval), ¤t_key, &index, 0) == HASH_KEY_NON_EXISTENT) {
    // This loop condition is incorrect for typical iteration.
    // The correct way is to check the return value of zend_hash_get_current_data.
    // Let's correct the loop structure.
}

// Corrected iteration loop:
zend_hash_internal_pointer_reset(Z_ARRVAL_P(my_array_zval));
while (zend_hash_get_current_data(Z_ARRVAL_P(my_array_zval), ¤t_zval) == SUCCESS) {
    if (zend_hash_get_current_key(Z_ARRVAL_P(my_array_zval), ¤t_key, &index, 0) == HASH_KEY_IS_STRING) {
        // String key
        // current_key is a zend_string*
        // current_zval is the value zval*
        // Process key (ZSTR_VAL(current_key)) and value (current_zval)
    } else if (zend_hash_get_current_key(Z_ARRVAL_P(my_array_zval), ¤t_key, &index, 0) == HASH_KEY_IS_LONG) {
        // Integer key
        // index is the integer key
        // current_zval is the value zval*
        // Process index and value
    }
    zend_hash_move_forward(Z_ARRVAL_P(my_array_zval));
}

Deleting Elements from a HashTable

zend_hash_del removes an element by its key. It’s important to note that this decrements the reference count of the value zval. If the reference count drops to zero, the zval and its underlying data are freed.

#include "Zend/zend.h"
#include "Zend/zend_API.h"
#include "Zend/zend_hash.h"

// ... assuming my_array_zval is an initialized array zval with "count" => 42 ...

zval key_zval;
ZVAL_STRING(&key_zval, "count", 0); // Temporary zval

zend_hash_del(Z_ARRVAL_P(my_array_zval), Z_STRVAL(key_zval), Z_STRLEN(key_zval));

// The zval associated with "count" will be freed if its refcount becomes 0.

Memory Management and Reference Counting

The Zend Engine employs a sophisticated reference counting mechanism for memory management. Every zval has a refcount field. When a zval is copied, its refcount is incremented. When a zval is no longer referenced (e.g., deleted from a hash table, or its pointer goes out of scope), its refcount is decremented. If the refcount reaches zero, the memory associated with the zval and its value is freed.

Key Functions for Reference Counting

• Z_ADDREF_P(zval_ptr): Increments the reference count of a zval.
• Z_DELREF_P(zval_ptr): Decrements the reference count of a zval.
• zval_ptr_dtor(zval_ptr_ptr): Decrements the reference count and frees the zval if the count reaches zero. This is crucial for cleaning up allocated zvals.
• zval_dtor(zval_ptr): Destroys the value within a zval (e.g., frees string memory, recursively destroys array/object elements) but does not free the zval structure itself.

Common Pitfalls

• Memory Leaks: Forgetting to call zval_ptr_dtor on allocated zvals.
• Double Freeing: Calling zval_ptr_dtor multiple times on the same zval.
• Incorrect Refcounting: Not incrementing refcounts when sharing zvals or not decrementing them when they are no longer needed.
• String Management: Using ZVAL_STRING without understanding that it copies the string and allocates memory, which must be freed. Using ZVAL_STRINGL(..., 0) incorrectly can lead to dangling pointers if the original string is freed.

Practical Example: Creating a Custom Array Function

Let’s illustrate by creating a simplified C function that mimics PHP’s array_keys but only returns string keys.

#include "php.h" // Essential for PHP extension development
#include "php_ini.h"
#include "ext/standard/info.h" // For php_info_print_table
#include "Zend/zend_API.h"
#include "Zend/zend_hash.h"
#include "Zend/zend_interfaces.h" // For zend_class_entry

// Function declaration
PHP_FUNCTION(my_string_keys);

// Function entry structure
const zend_function_entry my_extension_functions[] = {
    PHP_FE(my_string_keys, NULL) // NULL for arguments, as we don't expect any
    PHP_FE_END
};

// Module entry structure
zend_module_entry my_extension_module_entry = {
    STANDARD_MODULE_HEADER,
    "my_extension", // Extension name
    my_extension_functions,
    NULL, // MINIT
    NULL, // MSHUTDOWN
    NULL, // RINIT
    NULL, //Таким образом, RSHUTDOWN
    PHP_MINFO(my_extension), // PHP_MINFO callback
    "1.0.0", // Version
    STANDARD_MODULE_PROPERTIES
};

// PHP_MINFO macro definition
PHP_MINFO_FUNCTION(my_extension) {
    php_info_print_table_start();
    php_info_print_table_row(2, "my_extension support", "enabled");
    php_info_print_table_end();
}

// Implement the function
PHP_FUNCTION(my_string_keys) {
    zval *input_array;
    zval result_array;
    zend_string *current_key;
    long index;
    zval *current_zval;

    // Parse arguments: Expecting one argument, which must be an array.
    if (zend_parse_parameters(ZEND_NUM_ARGS(), "a", &input_array) == FAILURE) {
        return; // Error message printed by zend_parse_parameters
    }

    // Initialize the result array
    array_init(&result_array);

    // Iterate through the input array
    zend_hash_internal_pointer_reset(Z_ARRVAL_P(input_array));
    while (zend_hash_get_current_data(Z_ARRVAL_P(input_array), ¤t_zval) == SUCCESS) {
        // Get the current key
        if (zend_hash_get_current_key(Z_ARRVAL_P(input_array), ¤t_key, &index, 0) == HASH_KEY_IS_STRING) {
            // It's a string key, add it to our result array
            zval string_key_zval;
            ZVAL_STR(&string_key_zval, zend_string_copy(current_key)); // Copy the string key

            // Add the string key to the result array.
            // Using add_next_index_zval is convenient for creating numerically indexed arrays.
            // Here, we want to add the string key itself as a value.
            // Let's add the string key as a value to the result array.
            add_next_index_zval(&result_array, &string_key_zval);

        } else if (zend_hash_get_current_key(Z_ARRVAL_P(input_array), ¤t_key, &index, 0) == HASH_KEY_IS_LONG) {
            // It's an integer key, ignore it for this function.
        }
        zend_hash_move_forward(Z_ARRVAL_P(input_array));
    }

    // Return the result array to PHP
    RETURN_ZVAL(&result_array, 0, 0); // 0, 0 means don't copy, don't move
}

// Boilerplate for module initialization (usually in a separate .c file)
ZEND_GET_MODULE(my_extension)

This example demonstrates:

• Argument parsing with zend_parse_parameters.
• Initializing a result array with array_init.
• Iterating through a hash table using zend_hash_internal_pointer_reset, zend_hash_get_current_data, zend_hash_get_current_key, and zend_hash_move_forward.
• Distinguishing between string and long keys.
• Copying string keys using zend_string_copy.
• Adding elements to the result array using add_next_index_zval.
• Returning the result zval to PHP using RETURN_ZVAL.

Conclusion

Directly manipulating zvals and HashTables in C offers unparalleled control over PHP’s data structures. This power comes with the responsibility of meticulous memory management and adherence to the Zend Engine’s conventions. By mastering these low-level APIs, developers can build highly performant extensions, optimize critical code paths, and gain a profound understanding of PHP’s internal workings.