Standard di codifica

Questa pagina descrive le convenzioni che un contributo al plugin dovrebbe seguire, a un livello sicuro per la pubblicazione. I nomi delle classi interne, le costanti interne, gli identificatori delle capability e le convenzioni sulle chiavi delle opzioni sono dettagli di implementazione e non vengono pubblicati qui.

Quando utilizzare questo documento

Utilizza questo documento quando:

• Stai per aggiungere PHP, JavaScript, CSS, template o stringhe traducibili a un contributo.
• Stai revisionando una pull request e hai bisogno di un riferimento per capire cosa significa "coerente con la codebase".
• Stai estendendo il plugin da un plugin separato o da un tema e desideri che il tuo codice sembri nativo.

PHP

• Livello del linguaggio. Punta alla versione PHP dichiarata nell'header del plugin come minima. Evita funzionalità che non sono disponibili in tale versione.
• Dichiarazioni di tipo. Usa le dichiarazioni di tipo scalare e di ritorno sui nuovi metodi, in linea con il codice circostante.
• Stile WordPress. Segui gli standard di codifica PHP di WordPress (tabulazioni per l'identazione, spazi all'interno delle parentesi, condizioni Yoda dove la codebase già le utilizza, snakecase per funzioni e metodi, TitleCaseWithUnderscores per i nomi delle classi).
• Una singola classe per file. Ogni file PHP contiene una sola classe. I nomi dei file corrispondono ai nomi delle classi in formato minuscolo e con trattini, in linea con le convenzioni già presenti nella codebase.
• Nessuna nuova variabile globale. Preferisci le costanti di classe e la dependency injection rispetto alle variabili globali sparse.

Integrazione con WordPress

• Prima i controlli sulle capability. Ogni azione privilegiata deve verificare la capability appropriata prima di eseguire qualsiasi operazione.
• Controlli dei nonce per i moduli e l'AJAX di amministrazione. Utilizza le API standard dei nonce di WordPress (check_admin_referer, check_ajax_referer, wp_verify_nonce) per qualsiasi endpoint che modifica lo stato.
• Sanitizzazione ed escaping. Sanitizza in input ed esegui l'escaping in output utilizzando le API di WordPress appropriate per il tipo e il contesto di output. Vedi Sanitizzazione ed escaping.
• i18n. Racchiudi le stringhe visibili all'utente con il text domain del plugin. Vedi Internazionalizzazione per gli sviluppatori.
• Registrazione dei log. Utilizza il logger condiviso del plugin anziché chiamare direttamente error_log di PHP dal codice delle nuove funzionalità.

JavaScript e CSS

• Il plugin non utilizza una pipeline di compilazione JavaScript; gli asset vengono distribuiti come file semplici.
• Mantieni il JavaScript del front-end privo di dipendenze e progressivo; il plugin deve continuare a funzionare nei browser che bloccano gli script di terze parti.
• Prefissa le nuove classi CSS in modo coerente con le convenzioni esistenti del front-end e dell'amministrazione per evitare collisioni con i temi.

Test

• Le modifiche ai nuovi comportamenti dovrebbero essere coperte da test laddove possano essere ragionevolmente verificate tramite unit test.
• Nomina le nuove classi di test in base alla classe o al comportamento sotto test con un suffisso Test, in linea con i test esistenti.
• Vedi la Guida ai test per il flusso di lavoro dei test di alto livello.

Documentazione

• Aggiorna le pagine pertinenti sotto docs/en/ ogni volta che un contributo modifica un comportamento visibile pubblicamente.
• Mantieni la documentazione sicura per il pubblico; non aggiungere nomi di classi interne, chiavi di opzioni, nomi di rotte REST/AJAX o identificatori di capability/nonce al set di documentazione pubblica.

Avviso sulla documentazione pubblica. Questa pagina fornisce solo una panoramica di integrazione di alto livello. I dettagli di implementazione interna, le API private, i dettagli di archiviazione e l'infrastruttura di rilascio sensibile dal punto di vista della sicurezza sono gestiti separatamente e non fanno parte della documentazione pubblica.