L’architettura a plugin di WordPress

Alcune cose che puoi leggere prima (o dopo) di questo post:

• Documentazione per gli Sviluppatori in Italiano.
• Developer Documentation #Plugin Development in Inglese.
• Anatomia di un plugin per WordPress, un esempio, passo a passo, della creazione di un plugin.

Pseudo Type Callback

Alcune funzioni di PHP accettano come argomento il callback di una funzione.

Il callback (richiamo) di una funzione, che puÃ?² essere una stringa (per semplici funzioni) o un array (per metodi di oggetti o di classi), è usato appunto per richiamare la funzione a cui si riferisce. Potete far riferimento al manuale PHP per approfondire l’argomento: pseudo type callback.

call_user_func_array

Una funzione che accetta come argomento un callback è, tra le altre, la funzione call_user_func_array. Prendiamo come esempio la seguente funzione somma, il cui callback è la stringa “somma”, ovvero il suo nome:

function somma($a, $b){
   echo $a + $b;
}

Con call_user_func_array( 'somma', array(7, 9) ) otteniamo lo stesso output che otterremmo con somma(7, 9), cioè 16.

In effetti scrivere somma(7, 9) è decisamente più elegante che scrivere call_user_func_array( 'somma', array(7, 9) ), ma in certi contesti l’uso di questa funzione potrebbe essere utile, credo.

Ad esempio possiamo immaginare che in una parte di un programma (un plugin) decidiamo quali funzioni eseguire ed in quale punto, cos�¬ che nel cuore del programma quelle funzioni siano eseguite. Ma mantenendo i plugin ed il programma principale separati.

L’architettura a plugin di WordPress è basta su questo sistema. Sparse un po’ ovunque ci sono funzioni che eseguono callback.

Hello World.

Semplificando leggermente, immaginiamo che questo sia il codice sorgente di WordPress:

$string = 'Hello World !!'
$string = apply_filters('hello', $string);

La funzione apply_filters non fa altro che eseguire le funzioni agganciate al tag hello, passandogli come argomento $string, e ritornando il valore di $string eventualmente modificato.

CosÃ?¬, se vogliamo modificare $string, basta definire una funzione ed agganciarla al tag hello:

function hello_fra($string){
   return str_replace('World', 'Fra', $string);
}

add_filter('hello', 'hello_fra')

Ok, forse abbiamo semplificato troppo, ma il principio è questo :)

add_filter, add_action e $wp_filter.

Tutti gli agganci tra tag e callback sono gestiti tramite l’array multidimensionale $wp_filter. Se non altro per curiositÃ? , potete scrivere in un plugin print_r($wp_filter), tanto per sapere di cosa stiamo parlando :)

Per aggiungere un item a $wp_filter si puÃ?² usare la funzione add_filter o il suo alias add_action:

add_filter('tag', 'callback', 'priorit� ', 'argomenti passati nel callback')

Gli argomenti tag e callback li abbiamo giÃ?  visti, la prioritÃ?  è opzionale, di default è 10, indica con quale prioritÃ?  deve essere eseguito il callback (ad esempio una funzione che permette di eseguire il codice PHP in un post, dovrebbe essere eseguita prima di quella che si occupa della formattazione).

Il numero di argomenti accettati nel callback, anche questo opzionale, di default è 1: indica quanti argomenti passare alla funzione richiamata. Se nel codice di WordPress trovassimo un:

$something = appy_filters('wp_tag', $something, $someother);

Per poter utilizzare la variabile $someother in una funzione, dovremmo specificare che gli argomenti aspettati sono 2 e non 1, quindi:

add_filter('wp_tag', 'valid_callback', 10, 2);

La funzione appy_filters non ha un numero massimo di argomenti (in teoria): prende tutti gli argomenti passati e valuta quanti passarne ad ogni funzione agganciata al tag specificato.

A caccia di Hooks.

Oltre a sbirciare il codice di altri plugin o conoscere a memoria tutti gli agganci di WordPress (improbabile) e non tutti documentati, avete un’altra via per capire quale hook usare per… “fare qualcosa”: cercare direttamente nel codice sorgente i richiami a tre funzioni:

1. apply_filters('aggancio', $var[, $var,...])
2. do_action('aggancio'[, $var, $var,...])
3. do_action_ref_array('aggancio', array)

Quando vedete una di queste tre funzioni, significa che in quel punto potete agganciare una qualche funzione con le stesse modalit�  sopra descritte.

Filtri e azioni.

La prima (apply_filters), come abbiamo visto, permette di filtrare il valore di una variabile eseguendo i callback agganciati ad un tag.

La seconda e la terza (do_action e do_action_ref_array) sono molto simili alla prima, ma non servono per filtrare, servono invece per creare un’azione. In pratica la differenza è che la prima ritorna un risultato, la seconda e la terza no.

Quindi probabilmente, nel codice sorgente di WordPress, troveremo qualcosa di simile per un filtro:

$var = apply_filters('filtro', $var);

Mentre per una azione direttamente:

do_action('azione');

Per lo stesso principio, generalmente, una funzione agganciata ad un filtro dovrÃ?  ritornare un risultato, mentre una funzione agganciata ad un’azione dovrÃ?  produrre output.

Rendere disponibili API.

Naturalmente creare nuovi tag a cui agganciare funzioni non è prerogativa unica di WordPress e, anzi, nel caso di plugin complicati, sarebbe opportuno mettere a disposizione API per il plugin stesso. Ad esempio, per permettere di filtrare una variabile di un plugin, basta:

// Codice del mio complicatissimo plugin
$var = apply_filters('fra_t_complicato_plugin_filtri_per_var', $var)

E cosÃ?¬ facendo ogni altro plugin, utilizzando il tag “fra_t_complicato_plugin_filtri_per_var”, potrÃ?  modificare il valore di $var del mio plugin.

Il tag speciale ‘all’.

Se volessimo agganciare un callback a tutti i filtri e le azioni, potremmo usare il tag “all”.

Non mi viene in mente niente di particolarmente utile da farci, ma ad esempio, con un plugin come il seguente, possiamo ottenere alcune statistiche su i vari agganci richiamati nelle diverse parti del codice:

// Aggancio la funzione che conter�  il numero di tag chiamati.
add_filter('all', 'count_tags_called');

function count_tags_called($arg, $return_counter = false){
	static $a = 0;

	if($return_counter) return $a;

	$a++;
	return $arg;
}

// Ritorna il numero di tag chiamati
function tags_called(){
	return count_tags_called('', true);
}
function num_actions(){
	global $wp_actions;
	return count($wp_actions);
}
// Quanti dei tag chiamati sono usati come filtro (totale - numero di azioni)
function num_filters(){
	return tags_called() - num_actions();
}

// Stampa statistiche sull'uso di filtri e azioni
function api_stats(){
	_e('Here we have '.tags_called().' hooks: '.num_filters().' filters and '.num_actions().' actions');
}

Con api_stats() sapremo quante volte è stata utilizzata una delle tre funzioni apply_filters, do_action o do_action_ref_array. Il totale è diviso in filtri ed in azioni. L’output sarebbe qualcosa de genere: Here we have 1168 hooks: 1152 filters and 16 actions.

Questo codice è da usare solo a scopo di test, in quanto usare il tag ‘all’ attualmente “sballa” tutte le prioritÃ?  in $wp_filter ed alcuni plugin potrebbero non funzionare correttamente.

Altre funzioni

Altre funzioni utili sono:

• remove_filter e l’alias remove_action, permettono di rimuovere filtri ed azioni. Accettano gli stessi argomenti di add_action e add_filter.
• register_activation_hook e register_deactivation_hook, permettono di eseguire una funzione all’attivazione ed alla disattivazione di un plugin. Si usano cosÃ?¬:

  function alla_attivazione(){
     return;
  }
  register_activation_hook(__file__, 'alla_attivazione');

Approfondimenti.

Le funzioni trattate in questo post sono prese dal file di WordPress (ad oggi, la versione 2.1) wp-includes/plugin.php. Per approfondire potete far riferimento a quello.

post<li>

tag: API, PHP, plugin, WordPress, wp hacks, wp hooks.

post correlati:

• Eliminare i rel="nofollow" dai link nei commenti di Wordpress
• Plugin per Wordpress più usabili usando l'hook activate_
• Feed completi con il tag more in WordPress
• GT Post Approval [WordPress Plugin]
• Spleender Up: per terminare l'importazione di Spleender
• Migrare da Splinder/Motime a Wordpress.com
• Importare i post di Splinder/Motime in Wordpress