API, filtri e hook per la creazione dei plugin di WordPress

In questa sezione 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 dell'applicazione.

API

Le API (Application Programming Interface) di WordPress si suddividono in diverse sezioni. Ogni sezione comprende in genere due tipi di argomenti associati:

1. classi
2. 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:

1. parametri
2. valori di ritorno
3. 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.

Ciò a cui bisogna prestare un'attenzione particolare sono i valori di ritorno. Questi ultimi si differenziano a seconda che la funzione restituisca il valore atteso o meno. 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. Si consiglia quindi di leggere 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:

1. action
2. filtri

Le action vengono invocate durante un evento di WordPress, mentre i filtri servono a modificare l'output restituito dai componenti dell'applicazione.

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 non presenta questa necessità.

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à restituire sempre 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 sorgente avanti o indietro nella coda di esecuzione di WordPress.

La documentazione:

• add_filter()
• add_action()

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 eseguite 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, motivo per il quale 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 );

avremo che in questo caso la priorità è 5, quindi tale routine viene eseguita prima dell'altra. Come si può notare, leggere la documentazione è il modo migliore di lavorare con WordPress.