DarCas Sandbox

Col nuovo object model di PHP, sono arrivate anche le Reflection API: una collezione di funzioni ed oggetti che permettono di esaminare il codice a runtime.

Reflection può essere utile in molte circostanze, con questo articolo vedremo, ad esempio, come usare l’oggetto Reflection per creare un manuale di tutte le funzioni disponibili in uno script.

Per iniziare creiamo uno file PHP e creiamo due funzioni molto semplice, come queste che mostro di seguito.

/** * Converte byte nella unità più grande possibile con precisione arbitraria. * * @param float $byte * @param int $precision * @return string */ function from_byte_to ( $byte, $precision = 2 ) { $measurements = array ('Byte', 'KB', 'MB', 'GB'); while ($byte >= 1024) { $byte = $byte / 1024; $measure++; } $byte = number_format($byte, $precision, ',', '.'); return "{$byte} {$measurements[$measure]}"; } /** * Rimuove una o più chiavi da un'array. * * @param array $array * @param mixed $needle * @return array */ function array_strip_key ( $array, $needle ) { if (!is_array($array)) return false; else { foreach ($array as $key => $value) { switch (true) { case is_array($needle): if (!in_array($key, $needle)) $r_array[$key] = $value; break; default: if ($key != $needle) $r_array[$key] = $value; } } return $r_array; } }

Le due funzioni, la prima fa una conversione da byte all’unità di misura più grande rappresentabile; la seconda rimuove da un array una o più chiavi.

Per individuare l’elenco delle funzioni disponibili in uno script utilizziamo la funzione get_defined_functions().

$funcs = get_defined_functions();

Questa funzione built-in restituisce un array multidimensionale di funzioni organizzate per “internal” e “user”. Le funzioni dell’elenco “internal” sono tutte le funzioni built-in in PHP; le “user” sono quelle che abbiano dichiarato e/o sono disponibili nello script. Ovviamente noi ci riferiamo alle funzioni implementate da noi.

Con una iterazione passiamo, ad ogni iterazione, il nome della funzione alla classe ReflectionFunction() che crea un oggetto che implementa una serie di interfacce utili all’introspezione della funzione. Ad esempio abbiamo una interfaccia che ci restituisce l’elenco di tutti i parametri che la funzione si aspetta. Di queste ci sa dire quali sono quelle obbligatorie e quali quelle opzionali. Possiamo inoltre sapere qual è il valore predefinito impostato per ogni singolo parametro.

Altra interfaccia interessante è quella che ci permette di recuperare il commento associato ad ogni funzione che, se opportunamente scritto, può essere molto utile al fine del mantenimento del codice.

Tuttavia un esempio pratico vale più di mille parole, per cui, a quanto finora abbiamo scritto nel nostro file PHP, aggiungiamo quanto segue:

foreach ($funcs['user'] as $func) { try { $func = new ReflectionFunction($func); } catch (ReflectionException $e) { my::print_r($e); } $prototype = "{$func->name} ( "; $args = array(); foreach ($func->getParameters() as $param) { $arg = ""; if ($param->isPassedByReference()) $arg = '&'; if ($param->isOptional()) $arg = '[ $' . $param->getName() . ' = ' . $param->getDefaultValue() . ' ]'; else $arg = '$' . $param->getName(); $args[] = $arg; } $prototype.= implode(', ', $args) . ' );'; echo '<p style="white-space: pre;">' . $func->getDocComment() . '</p>'; echo "<h2>{$prototype}</h2>"; }

Questo breve codice produce un documento HTML molto semplice, ma è abbastanza evidente il potenziale di tutto quanto descritto finora.

Inoltre, in questo articolo, abbiamo visto all’opera la classe ReflectionFunction() che altro non è che una specializzazione dell’oggetto Reflection. Altra specializzazione molto interessante è la classe ReflectionClass(), che come il nome stesso suggerisce, offre funzioni introspettive per le classi.

Le API Reflection sono molto potenti, in quanto danno la possibilità di analizzare sia le funzionalità definite da noi sviluppatori, sia quelle definite built-in, sia in termini di funzioni che di classi. Tra l’altro, oltre alla sola funzionalità introspettiva, ci permette anche di evocarle a runtime, e questo apre ancora altri scenari di utilizzo.