PHP fornisce un set di API apposite (sfortunatamente poco documentate) che si occupano di gestire gli array ricevuti come parametri e di operare sulle variabili superglobali di PHP ($_SESSION, $_SERVER, ...). Questo insieme di funzioni è molto utile, e può essere utilizzato anche per lavorare sui normali array creati manualmente.
Tra le funzioni definite (i cui prototipi sono reperibili in Zend/zend_hash.h all'interno della cartella dei sorgenti PHP), le seguenti risultano molto utili:
int zend_hash_update(HashTable*, char*, uint, void**, uint, void**)
Aggiunge o modifica un valore contenuto in un array associativo. Il primo argomento è l'array sul quale si vuole operare (Z_ARRVAL(*array) oppure una delle hashtable speciali dello Zend Engine). Il secondo argomento è una stringa rappresentate la chiave di riferimento ed il terzo la sua lunghezza. Il quarto e quinto elemento rappresentano il dato che si intende aggiungere e le sue dimensioni, mentre l'ultimo argomento è solitamente settato a NULL, e rappresenta la destinazione del valore associato alla chiave. Di questa funzione esiste anche la versione che opera su un valore indicizzato da un intero, zend_hash_index_update, che accetta l'intero rappresentante l'indice al posto del secondo e terzo parametro. Esiste anche la funzione zend_hash_add, che le stesse operazioni ed accetta gli stessi argomenti.
int zend_hash_find(HashTable*, char*, uint, void**)
Localizza un elemento all'interno di un array associativo. L'elemento, indicato dalla chiave passata come secondo parametro, viene eventualmente salvato nel quarto parametro. Anche per questa funzione esiste la versione che opera su indici interi, zend_has_index_find.
int zend_has_move_forward(Hashtable*), int zend_has_move_backward(Hashtable*)
Muovono rispettivamente il puntatore interno dell'array in modo che punti all'elemento successivo o precedente.
int zend_has_del(HashTable*, char*, uint)
Elimina una chiave e l'elemento ad essa associato. Anche per questa funzione esiste la versione che opera su indici interi, zend_hash_index_del.
int zend_hash_get_current_key(HashTable*, char**, ulong*, zend_bool)
Trova la chiave a cui punta il puntatore interno dell'array ed in caso sia una stringa la assegna al primo parametro, altrimenti al secondo. L'ultimo parametro server per indicare se duplicare o meno la chiave.
int zend_hash_get_current_data(HashTable*, void**)
Salva nel secondo parametro il dato a cui punta il puntatore interno dell'array.
int zend_hash_num_elements(HashTable*)
Restituisce il numero di elementi contenuti nella hashtable.
int zend_hash_internal_pointer_reset(HashTable*), int zend_hash_internal_pointer_end(HashTable*)
Muovono rispettivamente il puntatore interno dell'array in modo che punti al primo o all'ultimo elemento.
Le funzioni qui descritte operano tutte sul tipo di dato HashTable, che è per l'appunto la struttura che lo Zend Engine utilizza per salvare gli array ed alcuni dati interni in formato tabellare.
Il seguente esempio chiarisce l'utilizzo di alcune delle funzioni sopra descritte:
PHP_FUNCTION(test_zend_hash)
{
zval* array;
int argc;
zval* ar_copy;
zval** item;
char buffer[512];
char* key;
int index;
MAKE_STD_ZVAL(ar_copy);
array_init(return_value),
array_init(ar_copy);
argc = ZEND_NUM_ARGS();
if(zend_parse_parameters(argc TSRMLS_CC, "a", &array) == FAILURE)
{
return;
}
int elem_count = zend_hash_num_elements(Z_ARRVAL(*array));
zend_hash_internal_pointer_reset(Z_ARRVAL(*array));
if(elem_count > 0)
{
do
{
zend_hash_get_current_data(Z_ARRVAL(*array), (void**)&item);
convert_to_string_ex(item);
if(zend_hash_get_current_key(Z_ARRVAL(*array), &key, &index, 0) == HASH_KEY_IS_STRING){
sprintf(buffer, "%s => %s", key, Z_STRVAL_PP(item));
}else
{
sprintf(buffer, "%d => %s", index, Z_STRVAL_PP(item));
}
add_next_index_string(ar_copy, buffer, 1);
}while(zend_hash_move_forward(Z_ARRVAL(*array)) == SUCCESS)
}
add_assoc_long(return_value, "elements count", elem_count);
add_assoc_zval(return_value, "informations", ar_copy);
}
Questa semplice funzione accetta un array come parametro, e restituisce una rray avente due elementi: il primo indicato dalla chiave elements count rappresentante il numero di elementi dell'array, il secondo, informations, rappresentante un array contenente la rappresentazione di ogni elemento in formato stringa. Viene effettuato un controllo sul valore restituito da zend_hash_get_current_key per conoscere se la chiave restituita è una stringa o un intero, e successivamente si opera di conseguenza. Ricordo che il suffisso _P alle macro serve per recuperare il valore di un puntatore, ed il suffisso _PP il valore di un puntatore a puntatore.