Il sistema URL di WordPress è una delle sue funzionalità più potenti. URL puliti — /blog/mio-post invece di /?p=123 — migliorano la SEO, l'esperienza utente e l'organizzazione dei contenuti. Dietro le quinte, la Rewrite API di WordPress traduce questi URL puliti nelle query del database che servono il contenuto giusto. Capire come funzionano le regole di rewrite è essenziale per qualsiasi plugin che introduce nuove strutture URL.
Questa guida spiega come funzionano le regole di rewrite e i permalink di WordPress, dalla Rewrite API alle strutture URL personalizzate per i plugin.
Come Funzionano i Permalink
I permalink sono gli URL permanenti dei tuoi singoli post, pagine e altri contenuti. WordPress usa una combinazione di Apache mod_rewrite (o equivalente Nginx) e riscrittura basata su PHP per tradurre gli URL puliti in query WordPress. Il file .htaccess contiene le regole di rewrite di Apache che indirizzano tutte le richieste al file index.php di WordPress.
WordPress poi analizza l'URL richiesto, lo confronta con le regole di rewrite registrate, identifica le variabili di query della regola corrispondente ed esegue la query WordPress appropriata. L'intero processo avviene in millisecondi, ma capirlo è cruciale per il debug dei problemi degli URL.
La Rewrite API
La Rewrite API è l'insieme di funzioni che WordPress fornisce per la gestione delle strutture URL. add_rewrite_rule() registra una nuova regola di rewrite, mappando un pattern URL su variabili di query. add_rewrite_tag() registra una nuova variabile di query che può essere usata nelle regole di rewrite. flush_rewrite_rules() ricostruisce l'array delle regole di rewrite — chiamala solo durante l'attivazione o la disattivazione del plugin, non a ogni caricamento di pagina.
Le regole di rewrite sono memorizzate nel database come array serializzati. Vengono rigenerate quando i permalink vengono salvati o quando un plugin richiede un flush. Il flush delle regole di rewrite è un'operazione costosa, quindi eseguilo con parsimonia.
Aggiungere Regole di Rewrite Personalizzate
Per aggiungere una struttura URL personalizzata per il tuo plugin, usa add_rewrite_rule() con un'espressione regolare che corrisponda al tuo pattern URL e un array di variabili di query. Registra la tua regola presto — durante l'hook init — così è disponibile quando WordPress analizza la richiesta.
Testa accuratamente le tue regole di rewrite. Usa il plugin Rewrite Rules Inspector per vedere tutte le regole registrate e verifica che la tua sia nell'elenco. Testa gli URL nel tuo browser per assicurarti che siano intercettati dalla tua regola e servano il contenuto atteso.
URL dei Custom Post Type
I custom post type ottengono automaticamente la propria struttura URL in base al parametro rewrite in register_post_type(). Puoi personalizzare lo slug URL, aggiungere un prefisso front e controllare se l'URL include il nome del post. Per i custom post type gerarchici, WordPress supporta URL annidati che rispecchiano la gerarchia delle pagine.
Quando registri un custom post type, chiama flush_rewrite_rules() durante l'attivazione del plugin per registrare le nuove regole di rewrite. Chiamala di nuovo durante la disattivazione per fare pulizia.
Problemi Comuni di Rewrite
Il problema di riscrittura più comune è l'errore 404 sulle strutture URL personalizzate. Di solito significa che le regole di riscrittura non sono state svuotate dopo averne registrate di nuove — vai su Impostazioni > Permalink e clicca su Salva per attivare lo svuotamento. Un altro problema comune è la priorità delle regole — le regole più specifiche dovrebbero essere registrate prima di quelle meno specifiche. Le regole di riscrittura vengono valutate dall'alto verso il basso e vince la prima corrispondenza.
Anche le collisioni delle variabili di query possono causare problemi. Se due plugin usano lo stesso nome di variabile di query, entreranno in conflitto. Prefissa sempre le tue variabili di query con un identificatore univoco.
Il punto fondamentale
Le regole di rewrite di WordPress trasformano gli URL brutti con query string in permalink puliti e SEO-friendly. La Rewrite API ti permette di aggiungere strutture URL personalizzate per i contenuti del tuo plugin. Registra le regole durante l'hook init, fai il flush delle regole di rewrite durante attivazione e disattivazione e testa accuratamente le tue regole. Gli URL puliti sono un segno distintivo dello sviluppo WordPress professionale.
