In PHP4 il concetto di array è molto importante: il cuore stesso dello zend engine sfrutta gli array di PHP per salvare alcune informazioni molto importanti, quali tabelle dei simboli e delle funzioni. In questa sezione ci occuperemo di trattare il sistema con cui gli array possono essere creati, gestiti e restituiti.
Prima di addentrarmi nella discussione delle API fornite dallo Zend Engine per la gestione degli array, vi mostro un esempio. La funzione definita si occupa semplicemente di restituire un array:
PHP_FUNCTION(test_array)
{
zval* sub_array;
zval* indexed_array;
zval* assoc;
if(ZEND_NUM_ARGS() != 0)
{
WRONG_PARAM_COUNT;
}
MAKE_STD_ZVAL(sub_array);
MAKE_STD_ZVAL(indexed_array);
MAKE_STD_ZVAL(assoc);
array_init(return_value);
array_init(sub_array);
array_init(indexed_array);
array_init(assoc);
add_next_index_bool(return_value, 1);
add_next_index_long(return_value, 2);
add_next_index_double(return_value, 2.523532);
add_next_index_string(return_value, "Ciao, da HTML.it", 1);
add_next_index_bool(sub_array, 0);
add_next_index_string(sub_array, "Sotto elemento ... ", 1);
add_index_long( indexed_array, 5, 10);
add_next_index_long( indexed_array, 11);
add_index_string( indexed_array, 10, "Alla posizione 10", 1);
add_assoc_long( assoc, "Uno", 1);
add_assoc_long( assoc, "Due", 2);
add_assoc_long( assoc, "Dieci", 10);
add_assoc_string( assoc, "Quattro", "Quattro", 1);
add_next_index_zval(return_value, sub_array);
add_next_index_zval(return_value, indexed_array);
add_next_index_zval(return_value, assoc);
}
L'esempio precedente restituisce l'array seguente (stampato con print_r):
Array
(
[0] => 1
[1] => 2
[2] => 2.523532
[3] => Ciao, da HTML.it
[4] => Array
(
[0] => 0
[1] => Sotto elemento ...
)
[5] => Array
(
[5] => 10
[6] => 11
[10] => Alla posizione 10
)
[6] => Array
(
[Uno] => 1
[Due] => 2
[Dieci] => 10
[Quattro] => Quattro
)
)
La funzione test_array restituisce un elemento di tipo zval rappresentante un array. Lo Zend Engine restituisce a PHP il valore contenuto nella variabile return_value, occupandosi di apportare le dovute trasformazioni. Questa variabile viene passata come argomento alla funzione da noi definita, anche se la macro PHP_FUNCTION ci nasconde i dettagli sull'implementazione, e non deve essere inizializzata. Essendo un normale zval, possiamo sfruttare tutte le funzioni che lavorano su questo tipo di dato. La funzione array_init è fondamentale affinché l'area di memoria associata al valore di tipo array dello zval sia correttamente allocata ed inizializzata, quindi prima di eseguire qualsiasi altra operazione di inserimento, eliminazione o ricerca, è necessario richiamarla sul valore che su cui si intende agire.
Le funzioni che permettono di aggiungere elementi ad un array sono ben documentate, anche se qualche appunto è comunque necessario:
- tutte le funzioni che iniziano per add_next incrementano il contatore interno dell'indice dell'array ed aggiungono nella nuova posizione il valore passato come argomento;
- le funzioni che iniziano per add_index accettano come parametro aggiuntivo un intero, che indica la posizione dell'array nella quale inserire il valore;
- infine le funzioni che iniziano con add_assoc permettono di trasformare l'array in un'array associativo, ed accettano come parametro aggiuntivo una stringa;
- tutte le funzioni che operano aggiungendo degli elementi di tipo stringa all'array accettano un ulteriore parametro intero che specifica se effettuare o meno la copia della stringa.
Come abbiamo già visto in qualche esempio precedente, è possibile utilizzare queste funzioni per operare sullo scope locale e globale.