Pubblicazione dei plugin di WordPress: guida passo passo

Tutti coloro che hanno familiarità con WordPress utilizzano i plugin dal suo repository. È un modo molto semplice e facile per estendere le funzionalità predefinite. Se state sviluppando o personalizzando un tema, quante volte avete copiato lo stesso codice da un sito precedente a uno nuovo? Quante volte vi è venuta l'idea che la vostra funzione attuale sarebbe stata utile ad altri? Se avete avuto pensieri simili, in questo articolo vi mostreremo, con un esempio reale, come pubblicare il vostro plugin per WordPress. Speriamo che dopo la lettura non lo consideriate un compito troppo complesso.

Coloro che sono già a conoscenza della pubblicazione di plugin, possono utilizzare l'articolo come promemoria per le pubblicazioni future. Inoltre, condivideremo un paio di cose complicate a cui dovrete prestare attenzione.

Nota: se avete già esperienza nella creazione di plugin, potete saltare questa sezione.

In questo articolo, utilizzeremo un esempio con il nostro plugin per mostrarvi come pubblicare i plugin di WordPress nella pratica. Utilizzeremo il nostro plugin Advanced Views. Il plugin consente di visualizzare i campi ACF o i post selezionati in qualsiasi punto utilizzando gli shortcode; il markup HTML viene creato automaticamente dal plugin. È possibile leggere i vantaggi dell'approccio shortcode qui.

In seguito, non dimenticate di sostituire questo nome con quello del vostro plugin.

Per coloro che sono completamente inesperti nella creazione di un proprio plugin, di seguito una breve panoramica.
I plugin di WordPress per il vostro sito web si trovano nella cartella /wp-content/plugins. Ogni plugin ha una propria cartella.

Fortunatamente, quando si crea un plugin non ci sono tanti passaggi come quando si crea un tema. È sufficiente creare una nuova cartella nella directory /wp-content/plugins e un singolo file al suo interno. Di solito, il file ha lo stesso nome della cartella.

Nel nostro esempio, sarà /wp-content/plugins/acf-views/acf-views.php.

Nel file, aggiungere il seguente commento 'header'. È necessario includerlo in qualsiasi plugin, in quanto fa capire a WordPress che c'è un plugin.

<?php
/*
Plugin Name: Advanced Views
Description: Display ACF fields and Posts using shortcodes.
Version: 1.0.0
Author: WPLake
*/

Ogni riga ha un formato: "Nome: Valore". Se avete copiato la nostra intestazione, cambiate semplicemente i valori con i vostri. Vedere tutti i requisiti dell'intestazione .

Questo è tutto. Il plugin è stato creato. Ora è possibile visitare la pagina dei plugin dell'amministrazione per vedere il nuovo plugin nell'elenco e attivarlo. Ovviamente, il plugin non fa ancora nulla, quindi dopo il commento dell'intestazione è necessario aggiungere il codice e tutte le funzionalità. (Cordiali saluti, il vostro capitano)

Il file principale del plugin può avere (includere/richiedere) altri file che devono essere inseriti nella stessa cartella. Maggiori dettagli sulla creazione di un plugin si trovano qui.

A questo punto, il plugin che desiderate condividere con il mondo è già stato creato e testato da voi stessi.
Ora prepariamo il plugin per la pubblicazione:

Innanzitutto, è necessario scegliere un nome unico che non sia utilizzato da altri plugin. Per verificare se un nome è disponibile, copiate https://wordpress.org/plugins/search/my-plugin/ e inserite il nome del vostro plugin al posto di 'my-plugin'. Incollatelo nella barra del browser e se vedete una pagina con i risultati della ricerca, proprio come nel caso my-plugin, è una buona notizia: il nome è disponibile. Se si vede la pagina del plugin, come nel caso di Advanced Views, significa che il nome è già in uso e bisogna sceglierne un altro.

In secondo luogo, riempire le intestazioni del file principale del plugin nel modo più completo possibile. I valori minimi richiesti sono Nome del plugin, Versione e Autore. Vedere l'elenco completo dei requisiti delle intestazioni.

<?php
/*
Plugin Name: Advanced Views
Plugin URI: https://wplake.org/acf-views/
Description: Display ACF fields and Posts using shortcodes.
Version: 1.0.8
Author: WPLake
Author URI: https://wplake.org
*/

Il file readme.txt è la nostra principale opportunità di condividere le informazioni sul plugin con il mondo. WordPress analizza questo file e il contenuto sarà visualizzato esattamente come nella pagina del plugin. WordPress lo analizza automaticamente e non avrete un pannello di amministrazione su Wordpress.org per modificare il contenuto. Si veda la pagina del plugin ACF per un altro esempio.

Di seguito è riportato il nostro readme.txt di esempio, le sezioni richieste sono:
principale (con il nome e i dati del plugin), descrizione (about) e changelog (brevi dati sugli aggiornamenti, all'inizio ci sarà solo una riga)

=== Advanced Views - Display ACF fields and Posts using shortcodes ===
Contributors: wplake
Tags: acf, display custom fields, display posts, acf views, shortcode, custom fields in frontend, show acf fields, get field values, get posts
Requires at least: 5.5
Tested up to: 6.1
Requires PHP: 7.4
Stable tag: 1.7.20
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

The plugin allows to display selected ACF fields or Posts anywhere using shortcodes, HTML markup is created automatically by the plugin.

== Description ==

The plugin allows to display selected ACF fields or Posts anywhere using shortcodes, HTML markup is created automatically by the plugin.

Note: "Advanced Views" plugin requires [Advanced Custom Fields](https://wordpress.org/plugins/advanced-custom-fields/) plugin to be enabled on your website (either Free or Pro version).

== Changelog ==

= 1.0.1 (2022-06-09): =
- Screenshots, plugin's version

Ecco un elenco completo di tutte le opzioni readme disponibili.

A questo punto, siamo riusciti a passare attraverso tutti i passaggi principali. Ora parliamo del codice del plugin.

Ecco l'elenco di tutti i requisiti. Tutti gli autori devono controllare questo elenco prima di decidere di pubblicare un plugin per WordPress, per assicurarsi che il plugin segua gli standard. Complessivamente l'elenco conta una ventina di voci. Ma le più importanti sono molto meno, e sono le seguenti:

Il codice deve essere disponibile sotto licenza GPLv2 o successiva. Ciò significa che permettete ad altri di usare e modificare il vostro codice a condizione che mantengano le informazioni originali sull'autore (voi) e questi diritti (di usare e modificare per altre persone).

In realtà, significa che non si dovrebbero usare parti di codice con una licenza chiusa nel proprio plugin. Ad esempio, se avete scritto una funzione per conto di un cliente o su richiesta di quest'ultimo, chiedetegli il permesso prima di usare quel codice nel plugin.

Il codice deve essere leggibile. Ricordate che il vostro codice sarà probabilmente letto da altre persone. Di solito con l'obiettivo di capire come funziona. A volte per chiarire qualcosa o per estenderlo ulteriormente. Per questo motivo non utilizzate nomi inutili di variabili, classi e funzioni, come $asdre o la funzione werlsdf().

Nel complesso, siate dei bravi persona coder e utilizzate la stessa struttura di codice che vorreste vedere in altri plugin. Leggete cosa deve sapere un buon sviluppatore di WordPress per verificare e migliorare le vostre conoscenze.

Questo è un punto molto importante. Perché WordPress richiede la cancellazione "tardiva" dei dati da parte dei plugin.

Che cosa significa?
Supponiamo di avere la variabile $_GET - email, e di doverla visualizzare da qualche parte in una pagina. Molto probabilmente, si farà qualcosa del genere:

$email = sanitize_text_field($_GET['email']?? '');
// ...
echo "<h3>Hi, {$email}</h3>";

Tuttavia, sarà sbagliato. Dovete sapere che WordPress ha le sue regole di codifica per ridurre il numero di plugin vulnerabili. Perché spesso è una delle ragioni alla base dell'hacking dei siti web WordPress. Quindi, in base alle regole di WordPress per i plugin, indipendentemente dal fatto che abbiate già sanificato una variabile in precedenza o meno, DEVETE sanificare anche qualsiasi variabile in uscita. Quindi usate le funzioni esc_attr, esc_html e in questo caso l'output deve essere:

echo sprintf("<h3>Hi, %s</h3>",esc_html($email)) 

Non siate pigri, cercate 'echo' e controllate tutti gli output. Spesso, durante la creazione del plugin, questo passaggio viene trascurato. Se avete saltato questo passaggio, verrete avvisati. Inoltre, WP metterà in pausa la revisione del vostro plugin fino a quando non lo avrete risolto.

Un'altra regola, da noi personalmente.

Purtroppo, WordPress non fornisce ancora una soluzione per l'uso comune delle dipendenze del compositore tra i plugin. In questo modo, un plugin può utilizzare una versione di una dipendenza e un altro plugin può utilizzare un'altra versione della stessa dipendenza. Credeteci, succede più spesso di quanto possiate immaginare.

Di conseguenza, un utente riscontrerà un errore critico e il sito web sarà interrotto. Se si utilizzano le dipendenze del compositore nel proprio plugin, è necessario evitare conflitti utilizzando PHP-Scoper.

In breve, è uno strumento che aggiungerà il vostro spazio dei nomi a tutti i file delle dipendenze, e invece di namespace Dependency\Folder; sarà namespace YourNamespace\Dependency\Folder;

In questo modo, si evita il conflitto e diversi plugin possono usare la stessa dipendenza anche con versioni diverse. Inoltre, PHP-Scoper lo fa automaticamente e l'installazione e la configurazione sono piuttosto semplici e veloci. Per saperne di più sull'uso dello strumento PHP-Scoper per i plugin di WordPress.

Finalmente siamo giunti al momento più solenne ed emozionante. È il momento di assaltare il repository di WP inviando una richiesta di inserimento del vostro plugin su WordPress.org.

Quindi, per ricevere l'approvazione a pubblicare il vostro plugin di WordPress, inviate una richiesta (con il vostro plugin allegato) e il team di WordPress.org la esamina manualmente. Ma non preoccupatevi, è totalmente gratuito e piuttosto facile.

Prima di tutto, dovete registrarvi su WordPress.org, nel caso non l'abbiate già fatto. Quindi confermate l'e-mail e visitate la pagina di richiesta speciale.

Qui è possibile caricare il proprio archivio con il plugin. In generale, l'archivio è un normale archivio, ma include una cartella del vostro plugin, non solo i file senza la cartella comune del plugin. WordPress analizzerà l'archivio e mostrerà il nome del plugin che sarà presente nel repository di WordPress. Nel nostro caso è acf-views. Inoltre, verrà visualizzato un avviso che il nome del plugin non potrà MAI essere modificato una volta approvato. Quindi, per favore, pensateci due volte prima di premere il pulsante di invio.

Dopo l'invio, il plugin sarà sottoposto a una revisione manuale, che di solito richiede da 1 a 5 giorni lavorativi. Successivamente, vi verrà notificata l'approvazione o il rifiuto della vostra richiesta. In realtà, se il plugin non è dannoso e la qualità del codice è decente, non verrà mai rifiutato.

Se i revisori hanno notato qualche violazione delle regole, vi verrà notificato con i dettagli e vi verrà chiesto di correggere e inviare una copia modificata. Ad esempio, abbiamo ricevuto una notifica per il safe echo, poiché avevamo cancellato le variabili nel tempo di ricezione e non in quello di uscita.

Tuttavia, se avete seguito tutti i punti sulla preparazione dei plugin di questo articolo, i revisori non dovrebbero avere domande da porvi. Inoltre, vorremmo rassicurarvi sul fatto che la comunicazione con i revisori di WordPress è sempre un'esperienza entusiasmante, almeno per noi XD.

Possiamo dire onestamente che raramente abbiamo incontrato un supporto così grande. Anche se il vostro plugin presenta degli inconvenienti, questi verranno segnalati in dettaglio nel feedback del recensore. Così capirete immediatamente cosa avete sbagliato. Non abbiamo mai avuto un caso in cui un plugin non sia stato pubblicato o la revisione sia stata messa in pausa senza una ragione chiaramente definita.

Significa che tutti possono pubblicare il proprio plugin WordPress senza temere di essere rifiutati per motivi sconosciuti. Ecco perché vogliamo dire un grande grazie alla comunità di WordPress

Quindi avete inviato una richiesta e avete aspettato alcuni lunghi giorni lavorativi. Probabilmente saranno stati molto lunghi per voi. Poi, finalmente, avete ricevuto una lettera, un invito a Hogwarts, un messaggio che dice che la vostra richiesta è stata approvata. È emozionante e significa che il team di WordPress vi permette di pubblicare il vostro plugin WordPress.

Congratulations, the plugin hosting request for Advanced Views has been approved.

Within one (1) hour your account (X) will be granted commit access to your Subversion (SVN) repository.

* SVN URL: https://plugins.svn.wordpress.org/acf-views
* Public URL: https://wordpress.org/plugins/acf-views

Once your account access has been activated, you may upload your code using a SVN client of your choice. If you are new to SVN (or the Plugin Directory) make sure to review all the links in this email.

To answer some common questions:

* You must use SVN to upload your code -- we are unable to do that for you
* Your SVN username is X and your password is the same as you use to log in to WordPress.org
* Your username is case sensitive
* SVN will not accept your email address as a username
* Due to the size of the directory, it may take 72 hours before all search results are properly updated

To help you get started, here are some links:

Using Subversion with the WordPress Plugin Directory:
https://developer.wordpress.org/plugins/wordpress-org/how-to-use-subversion/

FAQ about the WordPress Plugin Directory:
https://developer.wordpress.org/plugins/wordpress-org/plugin-developer-faq/

WordPress Plugin Directory readme.txt standard:
https://wordpress.org/plugins/developers/#readme

A readme.txt validator:
https://wordpress.org/plugins/developers/readme-validator/

Plugin Assets (header images, etc):
https://developer.wordpress.org/plugins/wordpress-org/plugin-assets/

WordPress Plugin Directory Guidelines:
https://developer.wordpress.org/plugins/wordpress-org/detailed-plugin-guidelines/

Block Specific Plugin Guidelines:
https://developer.wordpress.org/plugins/wordpress-org/block-specific-plugin-guidelines/

If you have issues or questions, please reply to this email and let us know.

Enjoy!

--
The WordPress Plugin Directory Team
https://make.wordpress.org/plugins

Nella lettera, verrà dichiarato l'indirizzo del repository SVN del plugin. Ma non preoccupatevi di SVN, è simile a Git. Inoltre, la lettera conterrà un link alla pagina del plugin su WordPress.org. È possibile salvare la lettera per la cronologia. Ma non preoccupatevi di perderla, tutti i link su WordPress.org sono identici. È quindi sufficiente ricordare il nome del vostro plugin per ritrovare sempre i vostri link.

Copiate i link qui sotto e sostituite 'PLUGIN-NAME' con il nome del vostro plugin alla fine:

https://plugins.svn.wordpress.org/PLUGIN-NAME 
https://wordpress.org/plugins/PLUGIN-NAME

Crediamo che il nome del vostro primo plugin d'amore non sarà facilmente dimenticato.

È il momento di rilasciare il vostro plugin alla comunità

Questa parte può essere eseguita solo da voi, non dal team di WordPress.org, il che significa che il vostro plugin sarà disponibile solo dopo il primo commit.

Create una cartella e clonate il repository (svn dovrebbe essere installato sul vostro computer):

svn co http://plugins.svn.wordpress.org/YOUR_PLUGIN_NAME_HERE

allora

Copiate tutti i file dei plugin (senza la cartella comune) nella cartella trunk.

Dopodiché creare una cartella con la propria versione (probabilmente 1.0.0) nella cartella tags e aggiungervi anche i file dei plugin.

Quindi è il momento di pensare a un banner, che appaia in cima alla pagina del plugin su WordPress.org. Inoltre, è necessario pensare a un'icona del plugin, che appare nella pagina dei risultati di ricerca di WordPress accanto al nome del plugin. Può essere un'immagine qualsiasi, ma sicuramente non indecente xD. Inoltre, è possibile aggiungere il banner in un paio di dimensioni supportate (772x250px larghezza x altezza e 1544x500px) nella cartella assets con l'etichetta 'banner' nel nome.

Sarà quindi banner-772x250.png e banner-1544x500.png (o jpg). Inoltre, l'icona sarà icon-128x128.png e icon-256x256.png (o jpg).

Quindi aggiungete i file a SVN con i comandi:

svn add trunk/*
svn add tags/YOUR_VERSION_HERE
svn add assets/*

Finalmente il primo commit:

 svn ci -m "v 1.0.0"

Per prima cosa, la console chiederà il nome e la password del vostro account WordPress.org, incollateli per autorizzare. Anche il commit richiederà un po' di tempo, poiché svn non è veloce come git. Aspettate quindi un po' di tempo prima che il comando sia terminato.

Bel lavoro!Ora è possibile visitare la pagina del plugin. Dopo di che, è disponibile per tutti, e si può installare il plugin su qualsiasi sito WordPress direttamente tramite il pannello di amministrazione (con Aggiungi nuovo -> cerca).

Dopo qualche tempo, è probabile che vogliate aggiungere funzionalità o modificare il vostro plugin. A tale scopo, è necessario rilasciare una nuova versione. Fortunatamente, è facile rilasciare nuove versioni. Perché i passaggi sono molto più semplici e veloci rispetto allo schema utilizzato per pubblicare un plugin di WordPress. Per esempio, non ci sarà alcuna revisione manuale.

Per tua informazione: WP usa un versioning ordinario e consiste di 3 cifre, come in npm o composer - Major.Minor.Patch.

Per esempio 1.0.0 - con piccole modifiche aumentiamo solo la terza cifra, 1.0.1, con l'aggiunta di nuove funzionalità o aggiornamenti intermedi cambiamo la seconda cifra, 1.1.0, e con modifiche davvero grandi o 'rivoluzionarie' aggiorniamo la prima cifra, 2.0.0.

Nel caso di npm/composer, lo usano per gestire gli ulteriori aggiornamenti. Ad esempio, se si usa la versione '1.0.0', per impostazione predefinita si ricevono solo gli aggiornamenti Minor e Patch, ma non Major, perché si suppone che Major possa contenere modifiche senza retro compatibilità.

MA WORDPRESS NON CE L'HA. Ciò significa che si DEVE fornire la retrocompatibilità con le versioni precedenti. A questo scopo, ci sono dei ganci speciali che vengono richiamati nel processo di aggiornamento. È possibile utilizzarli per gli aggiornamenti del database o per altre modifiche, per consentire il passaggio dalla versione principale precedente a una nuova. Ma non è necessario conoscerli in questo momento.

È il momento di rilasciare una nuova versione.

Per questo obiettivo è necessario:

Per prima cosa, aggiornare la versione nell'intestazione del file principale del plugin ("Version: X") con quella nuova (ad esempio 1.0.2). E aggiornare "Stable tag: YOUR_VERSION_HERE" alla nuova versione nel file readme.txt.

In secondo luogo, aggiornare i file dei plugin nella cartella trunk e creare una nuova cartella con il nuovo numero di versione come nome nella cartella tags. Copiare quindi i file del plugin anche lì.

Infine, comunichiamo a svn i nuovi file aggiunti e facciamo un commit.

// this command must be executed before updating the trunk folder
svn delete trunk/* --force
// these commands must be executed after updating all files
svn add trunk/*
svn add tags/{YOUR_VERSION_HERE}
svn ci -m "v YOUR_VERSION_HERE"

Anche se la descrizione del commit può essere qualsiasi, si consiglia di usare un numero di versione come descrizione.

Sommario:
È necessario aggiornare la cartella trunk, che conserva sempre l'ultima versione. E aggiungere una nuova cartella, con la nuova versione come nome e con i file del plugin all'interno, alla cartella tags.

Ma nel caso in cui si vogliano solo aggiornare le informazioni sul plugin nella pagina di WordPress.org, è sufficiente aggiornare il file readme.txt nella directory trunk e fare il commit in svn, senza rilasciare una nuova versione.

Come avete notato, usiamo il repository SVN di WordPress SOLO per rilasciare nuove versioni. Perché è un repository di rilascio. Quindi è vietato fare il commit di ogni modifica al repository come con git. Per saperne di più sull'uso di subversion , vedere qui. Altrimenti, il vostro repository diventerà molto lento e utilizzerà molto spazio sul lato WordPress.org. Per questo motivo, per lo sviluppo dei plugin, è necessario creare un proprio repository git e fare il commit lì tutte le volte che è necessario. Utilizzando il repository svn solo per il rilascio di nuove versioni.

Avete imparato a pubblicare il vostro plugin nel repository di WordPress. Questo vi permette di condividere il vostro plugin con persone di tutto il mondo. Inoltre, abbiamo condiviso le conoscenze su un paio di cose difficili che incontrerete in questo modo. Ma potrete risolverli facilmente utilizzando i suggerimenti di questo articolo.

Speriamo che ora il compito di pubblicare il vostro plugin non vi sembri più spaventoso e che un giorno pubblicherete il vostro plugin per rendere migliore l'universo di WordPress.

Ora è il momento di rendere migliore questo mondo e di pubblicare il vostro plugin!