In questo articolo forniremo un’introduzione alle API, ai filtri ed agli hook di WordPress. Più che offrire una trattazione esaustiva, ci concentreremo sui modi in cui possiamo apprendere ed usare velocemente queste caratteristiche di WordPress.
API
Le API di WordPress si suddividono in diverse sezioni. Ogni sezione comprende in genere due tipi di argomenti associati:
- Classi
- Funzioni
Le classi sono una scelta obbligatoria solo in alcuni casi, perché il principio chiave di WordPress è quello di permettere agli autori di temi e plugin di utilizzare le funzioni.
Tutte le funzioni di WordPress fanno riferimento ad una classe del Core. Di fatto le funzioni nascondono la logica della classe secondo il principio della modularità.
Quando si usa una funzione bisogna leggere nella documentazione tre parti fondamentali:
- parametri
- valori di ritorno
- casi d’uso
WordPress in genere usa gli array associativi per assegnare alle funzioni dei parametri predefiniti. A differenza del tradizionale modo con cui i parametri predefiniti vengono passati alle funzioni in PHP, in questo caso l’ordine dei parametri non è rilevante.
Al contrario, se la funzione utilizza il modo tradizionale di passare gli argomenti, in questo caso invece l’ordine dei parametri è rilevante.
Quello a cui bisogna prestare un’attenzione particolare sono i valori di ritorno.
I valori di ritorno si differenziano a seconda che la funzione restituisca il valore sperato o no. Se la funzione ha successo, WordPress restituirà un valore (ad esempio un array di oggetti), altrimenti può restituire un tipo di dati PHP (false, null ecc.) oppure un’istanza della classe WP_Error. Ad esempio, prendiamo la funzione wp_remote_get():
$remote_file = wp_remote_get( 'http://sito/file.txt' );
if( !is_wp_error( $remote_file ) ) {
// Successo!
}
Invece, per la funzione wp_get_attachment_image_src() avremo:
$attachment_id = 8;
$image = wp_get_attachment_image_src( $attachment_id );
if( $image ) {
// Successo!
}
Questa funzione restituisce un array, quindi in questo caso la verifica da effettuare è diversa.
Leggete sempre con attenzione gli esempi forniti nella documentazione. Si tratta di codice che illustra perfettamente i casi d’uso delle funzioni o delle classi trattate.
Filtri e hook
Due sono i tipi di hook che di solito useremo:
- action
- filtri
Le action vengono invocate durante un evento di WordPress, mentre i filtri servono a modificare l’output restituito dai componenti di WordPress.
Questi hook hanno bisogno di una funzione o di un metodo di una classe che andremo a definire per poter operare.
La differenza tra i due sta nel fatto che un filtro ha bisogno di un input da modificare, mentre una action no.
Ad esempio, se dovessimo applicare un nofollow a tutti i link di un post, dovremmo modificare l’output della funzione the_content(). Il filtro corrispondente si chiama appunto the_content, quindi scriveremo:
function add_nofollow( $content ) {
$content = str_replace( '<a ', '<a rel="nofollow" ', $content );
return $content;
}
add_filter( 'the_content', 'add_nofollow' );
Il nostro codice dovrà sempre restituire un valore: questa è la caratteristica dei filtri. Non è possibile fare altrimenti: se la nostra funzione non avesse restituito il contenuto del post (modificato in questo caso), WordPress non avrebbe mostrato più il contenuto dei post. Ovviamente possiamo usare la logica condizionale per filtrare l’input solo quando è necessario.
La nostra funzione in questo caso accetta un solo parametro, ossia il contenuto del post. Bisogna sempre leggere sulla documentazione delle API quali parametri sono richiesti dalla funzione usata come filtro.
Attenzione: se non usiamo i parametri nel modo e nell’ordine corretto verrà restituito un errore. E molto spesso è solo un parametro quello che andremo a modificare.
Le action, al contrario dei filtri, eseguono semplicemente del codice durante un evento di WordPress.
Ad esempio se volessimo inserire il codice di Google Analytics nella sezione dei nostri documenti, dovremo usare l’action wp_head che è direttamente collegata alla funzione wp_head().
Quindi scriveremo:
function add_ga() {
$ga_code = 'codice Analytics';
echo $ga_code;
}
add_action( 'wp_head', 'add_ga' );
WordPress aggiunge il nostro codice alla serie di routine da eseguire in modo seriale e semplicemente lo esegue.
Quello che i filtri e le action hanno in comune, oltre al modo di associarli, è che possiamo spostare il nostro codice avanti o indietro nella coda di esecuzione di WordPress.
Leggiamo la documentazione:
Il terzo parametro di entrambe le funzioni indica la priorità, ossia:
Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added(…).
I numeri con un basso valore vengono eseguiti prima e le funzioni con la stessa priorità vengono eseguiti nell’ordine in cui sono state aggiunte.
Quindi tornando al nostro filtro sul contenuto dei post possiamo coordinare più routine in sequenza. La funzione che avevamo definito viene eseguita con priorità 10, quindi se volessimo eseguire un’altra routine prima di questa:
function my_previous_filter( $content ) {
// Routine
return $content;
}
add_filter( 'the_content', 'my_previous_filter', 5, 1 );
In questo caso la priorità è 5, quindi questa routine viene eseguita prima dell’altra.
Come si può notare, leggere la documentazione è il modo migliore di lavorare con WordPress.
Conclusione
API, filtri ed hook sono utilizzabili facilmente a patto di studiare con attenzione la documentazione ufficiale di riferimento. WordPress ha una documentazione eccellente che fornisce numerosi esempi pratici per poter imparare rapidamente.