Mistä tiedän, että koodini noudattaa parhaita käytäntöjä ja on turvallista käyttää? Hyvä ja tarpeellinen kysymys, jonka selvittämisessä voi käyttää apuna erilaisia koodin analysointiin, validointiin ja formatointiin tarkoitettuja apuvälineitä. Parhaiden ja yhtenäisten koodauskäytäntöjen noudattaminen on enemmän kuin suotavaa, ja tätä helpottamaan WordPress-yhteisö on kehittänyt oman WordPress Coding standards -sääntökokoelman PHP_CodeSniffer-työkalulle, jota voi käyttää suoraan komentoriviltä tai PHP Sniffer -lisäosan kanssa esimerkiksi VS Code -editorissa.
Asennetaanpa siis koodausstandardit WP-kehityksen tueksi. Tässä kohtaa oletan, että tietokoneella on asennettuna PHP, Composer ja VS Code.
Koodausstandardin asennus Composerilla
Koodausstandardin tiedostojen, PHP_Codesnifferin ja tarvittavien riippuvuuksien asentaminen Composerilla globaalisti onnistuu seuraavilla komentorivikomennoilla:
composer config allow-plugins.dealerdirect/phpcodesniffer-composer-installer true
composer require --dev wp-coding-standards/wpcs:"^3.0"Lisätietoa: https://github.com/WordPress/WordPress-Coding-Standards
Useita sääntökokonaisuuksia
WordPressin koodausstandardikokoelma pitää sisällään (ali)säännöstöt WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra. Windowsissa ainakin itselläni koodausstandardin tiedostot asentuvat hakemistoon: C:\Users\ExampleUser\AppData\Roaming\Composer\vendor\wp-coding-standards\wpcs\
PHP Sniffer -lisäosa VS Codeen
PHP Sniffer != PHP_Codesniffer
WP:n koodaussääntöjä voi käyttää VS Codessa PHP Sniffer -lisäosan avulla. Lisäosan asentamisen jälkeen sen asetuksiin voi syöttää tiedot PHP_Codesnifferin ja WP:n koodausstandardien sijainnista, jolloin lisäosa osaa käyttää haluttuja sääntöjä validointiin ja formatointiin. Käytän Windowsia, ja omat käyttäjäkohtaiset snifferiin liittyvät asetukseni VS Coden settings.json -tiedostossa ovat seuraavanlaiset (huomaa Windowsin polun kenoviivoista johtuva ’esceippaaminen’ toisilla kenoviivoilla):
"[php]": {
"editor.defaultFormatter": "wongjn.php-sniffer",
"editor.formatOnSave": true,
},
"phpSniffer.autoDetect": true,
"phpSniffer.snippetExcludeSniffs": [],
"phpSniffer.standard": "C:\\Users\\ExampleUser\\AppData\\Roaming\\Composer\\vendor\\wp-coding-standards\\wpcs\\phpcs.xml"Polku phpcs.xml-tiedostoon
Edellä olen määrittänyt ”phpSniffer.standard”-kohtaan polun, joka osoittaa kokoelman juuren phpcs.xml -tiedostoon, joka taasen sisältää viittaukset edellä mainittuihin (ali)säännöstöihin, jolloin myös ne otetaan käyttöön. Voi olla, että kyseisen xml-tiedoston joutuu itse kopioimaan/uudelleennimeämään kansiossa olevasta .sample-mallitiedostosta, tai sen voi kopioida verkosta täältä. PHP Snifferin asetuksiin voi asettaa myös yksittäisen säännöstön suoraan sen nimellä, kuten ”WordPress”, tällöin muut kokoelman säännöstöt jäävät oletuksasetuksilla huomiotta.
PATH-ympäristömuuttuja tai PHP Snifferin executablesFolder-asetus
VS Coden asetusten lisäksi olen määrittänyt Windowsin Path-ympäristömuuttujaan tiedon PHP_Codesnifferin suoritettavien tiedostojen kansiosta: C:\Users\ExampleUser\AppData\Roaming\Composer\vendor\bin. Tämän polkutiedon voi syöttää myös VS Coden settings.json-tiedostossa seuraavaan tapaan, ainakin jos sääntöjä aikoo käyttää vain VS Codessa:
"phpSniffer.executablesFolder": "C:\\Users\\ExampleUser\\AppData\\Roaming\\Composer\\vendor\\bin"Projektikohtaiset asetukset
WordPress-lisäosaa tai teemaa kehittäessä on hyödyllistä pystyä määrittämään tiettyjä projektikohtaisia sääntöjä ja ominaisuuksia, kuten käännösfuktioiden käyttämä ”text_domain” ja funktioiden ja luokkien nimeämistä ohjaava ”prefixes”.
PHP Sniffer -lisäosa osaa etsiä xml-sääntötiedostoa projektin hakemistosta, jos ”phpSniffer.standard”-asetus on tyhjä (””). Jos käytämme useimmiten projektikohtaista xml-tiedostoa, kyseisen määrityksen arvon voi jättää VS Coden käyttäjäkohtaisiin asetuksiin tyhjäksi. Jos kuitenkin olemme määrittäneet käyttäjäkotaisen ”phpSniffer.standard”-tiedon, kuten minä edellä, ja haluamme käyttää projektihakemistokohtaista sääntötiedostoa, meidän pitää lisätä projektiin .vscode-kansio ja sinne projektikohtainen settings.json, jossa minimissään tieto:
{
"phpSniffer.standard": ""
}Projektin juureen voimme sitten luoda oman phpcs.xml-tiedoston (.phpcs.xml, phpcs.xml, .phpcs.xml.dist tai phpcs.xml.dist) ja kopioida siihen sisällön aiemmin asentamastamme globaalin wpcs-hakemiston xml-tiedostosta tai WP:n mallitiedostosta Githubista. Itse muokkaan mallitiedostoa projektikohtaiseksi yleensä vain sääntöjen ”WordPress.WP.I18n” ja ”WordPress.NamingConventions.PrefixAllGlobals” osalta.
Ei muuta kuin iloista standarinmukaista koodailua 🙂
