Dopo aver introdotto brevemente un esempio di implementazione, passiamo a trattare in modo più approfondito le diverse parti che compongono un'estensione e le API che possono essere utilizzate per lavorare correttamente. Come prima cosa analizzeremo gli strumenti che PHP mette a disposizione per accettare e gestire gli argomenti.
Affinché si possano gestire correttamente gli argomenti passati alla funzione da PHP è necessario che questi siano convertiti e trasformati in tipi di dato corretti. La funzione zend_parse_parameters viene utilizzata per questa finalità. Il suo prototipo è il seguente:
int zend_parse_parameters(int argc TSRMLS_DC, char* type_spec, ...);
Il primo parametro è il numero di argomenti di cui la funzione dovrà eseguire il parsing. La macro TSRMLS_DC viene utilizzata al fine di aggiungere il supporto threaqd safe a PHP, che non verrà discusso in questa sezione. Il secondo parametro è una stringa, che fornisce alla funzione informazioni sulla struttura degli argomenti accettati dalla funzione. È possibile specificare una stringa di dimensioni variabili, ed ogni singolo carattere di questa stringa avrà un preciso significato:
| d | Double |
| l | Long |
| s | String |
| r | Resource |
| b | Boolean |
| a | Array |
| o | Oggetto di una classe qualsiasi |
| O | Oggetto di una classe specifica |
| Z | Lo zval corrente |
| | | Indica che i parametri successivi saranno opzionali. In caso non vengano forniti al momento della chiamata dei valori, alle variabili in cui dovrebbe essere salvato il loro valore verranno assegnati dei valori di default. |
| / | Verrà chiamata la macro SEPARATE_ZVAL_IF_NOT_REF sul parametro che segue, che si occuperà di creare una copia del parametro a meno che questo non sia un riferimento. |
| ! | Il parametro che segue può essere di un tipo specifico o NULL. |
Il restante numero di parametri rappresentano dei riferimenti a variabili nei quali verranno salvati i valori relativi agli argomenti estratti. Va specificato che al formato 's' devono corrispondere due parametri: il primo di tipo char* che conterrà un puntatore alla stringa estratta, ed il secondo di tipo int, contenente la lunghezza di quest ultima.
Questa funzione risulta molto comoda, e permette anche di recuperare un numero parziale di argomenti lasciando al programmatore il compito di recuperare manualmente i valori degli altri parametri sfruttando altre api.
La funzione restituisce un valore identificato dalla costante FAILURE in caso di fallimento, altrimenti SUCCESS.
Lo zend engine fornisce altri strumenti utili per la gestione dei parametri:
- ZEND_NUM_ARGS() è una macro che restituisce il numero di argomenti con cui la funzione è stata chiamata;
- WRONG_PARAM_COUNT genera un messaggio di errore php che informa l'utente del fatto che la funzione è stata chiamata con un numero di argomenti errato;
- zend_parse_parameters_ex funziona come zend_parse_parameters, ma accetta un primo argomento aggiuntivo. Questo parametro ha attualmente un unico valore utile, rappresentato dalla macro ZEND_PARSE_PARAMS_QUIET, che assicura che nessun messaggio di errore venga generato durante il parsing;
- PZVAL_IS_REF(zval*) la quale controlla che un oggetto zval (vedi sotto) sia un riferimento o meno.
È necessario fare una nota particolare per la funzione zend_get_parameters_array_ex: questa funzione accetta come primo parametro un intero rappresentante il numero di parametri che si desidera salvare nel secondo argomento, un array di zval**.
zval **parameters[4];
argc = ZEND_NUM_ARGS();
if(arc < 4)
{
WRONG_PARAM_COUNT;
}
if(zend_get_parameters_array_ex(argc, parameters) != SUCCESS)
{
WRONG_PARAM_COUNT;
}
// faccio qualcosa con l'array parameters
Il tipo zval rappresenta un oggetto generico PHP, e viene utilizzato in tutti i casi nei quali è necessario lavorare a basso livello con argomenti e valori; normalmente viene utilizzato in PHP come puntatore di puntatore, e può essere interrogato direttamente per recuperare svariate informazioni su un oggetto. Le API di PHP forniscono un insieme di funzioni convert_to_*_ex dove l'asterisco è uno tra boolean, long, double, string, array, object e null, che convertono lo zval nel tipo specificato.