PHP_CodeSniffer használata PhpStorm-ban

balazswmann képe

CsatolmányMéret

using-php_codesniffer-in-phpstorm-01-composer.png1.2 MB
using-php_codesniffer-in-phpstorm-02-composer.png1.22 MB
using-php_codesniffer-in-phpstorm-03-composer.png1.22 MB
using-php_codesniffer-in-phpstorm-04-phpcs-config.png1.07 MB
using-php_codesniffer-in-phpstorm-05-phpcs-config.png1.73 MB
using-php_codesniffer-in-phpstorm-06-inspection.png1002.96 KB
using-php_codesniffer-in-phpstorm-07-phpcs-config.png1001.92 KB
using-php_codesniffer-in-phpstorm-08-scopes-config.png1010.74 KB
using-php_codesniffer-in-phpstorm-09-scopes-usage.png806.83 KB
using-php_codesniffer-in-phpstorm-10-scopes-usage.png797.97 KB
using-php_codesniffer-in-phpstorm-11-error-messages.png860.62 KB

A PHP_CodeSniffer egy olyan PHP5 szkript, ami a PHP, JavaScript és CSS típusú programok szövegének kódolási szabványok (coding standards) szerinti ellenőrzésére szolgál. Másképpen fogalmazva egy szkript segítségével egyszerűen ellenőrizhetjük a forráskódunk szabványosságát ahelyett, hogy fejben kéne tartanunk minden egyes kódolási szabvánnyal kapcsolatos részletet. A PHP_CodeSniffer (a továbbiakban phpcs) használatához alapvetően szükséges maga a phpcs szkript telepítése, illetve a használni kívánt kódolási szabványt tartalmazó könyvtár vagy fájl csomag. A phpcs-t többféleképpen is használhatjuk, így például futtatható akár egyszerűen parancssorból is, de a PhpStorm beépített támogatásának köszönhetően egy sokkal hatékonyabb eszköz válik belőle.

Fejlesztői környezet

A továbbiakban olvasható instrukciók és példák Ubuntu 14.04 LTS (64bit) operációs rendszer, PhpStorm 7.1.3, illetve egy alpha13 verziójú Drupal 8.0 projekt mellett készültek (esetenként kitérve a Drupal 7.x-es differenciákra). Ezektől eltérő operációs rendszer, PhpStorm vagy Drupal verzió esetében bizonyos dolgok különbözhetnek az itt leírtaktól.

Kódolási szabványok

A phpcs telepítését követően többféle kódolási szabvány is a rendelkezésünkre áll, úgy mint például PEAR, PSR1, PSR2, Squiz vagy Zend, de ezeket lehetőségünk van továbbiakkal is bővíteni, így például a Drupal coding standards is rendelkezésre áll.

A Drupal specifikus kódolási szabványokat a Coder modul tartalmazza. Amennyiben csak a phpcs-hez szeretnénk beszerezni a megfelelő verziójú Drupal coding standards csomagot, nem szükséges a Coder modult telepíteni, elegendő csak a kódolási szabványokat tartalmazó részét felhasználni. Attól függően, hogy milyen módon kívánjuk telepíteni és konfigurálni a phpcs-t, a Coder modul drupal.org-ról történő letöltése sem feltétlenül szükséges (lásd projekt szintű telepítés).

Telepítési módok

A phpcs-t és az egyes coding standards könyvtárakat alapvetően háromféle módon telepíthetjük. A telepítési módok között csupán kényelmi és logikai különbségek vannak, melyek a működést nem befolyásolják.

1. Projekt szintű telepítés

Ebben az esetben maga a phpcs működéséhez szükséges szkript és a használni kívánt kódolási szabványt tartalmazó könyvtár is a projekt könyvtáron belül foglal helyet. Ennek a megoldásnak a nyilvánvaló előnye, hogy a szükséges fájlok a projekttel együtt könnyen hordozhatóvá válnak, továbbá lehetőségünk van projektenként eltérő verziójú phpcs illetve kódolási szabvány könyvtár használatára is. A könnyű hordozhatóság azonban bizonyos szempontból egyben hátrány is, hiszen ha több projekt esetében is használni szeretnénk ugyan azt a phpcs szkriptet vagy kódolási szabványt, akkor minden egyes projektnek külön-külön tartalmaznia kell az ezekkel kapcsolatos fájlokat (ez azért nem teljesen igaz, lásd a kombinált telepítési módot). További hátrány lehet, hogy az imént említett phpcs-vel kapcsolatos fájlok nem képezik szerves részét a projektnek, csupán a kódolási szabvány betartásának az ellenőrzéséhez kellenek, ennél fogva egyáltalán nem biztos hogy verzió kezelés alá kell őket helyezni (.gitignore).

2. Rendszer szintű telepítés

Rendszer szintű telepítés esetén, a phpcs szkript és az egyes kódolási szabványokat tartalmazó könyvtárak is valahol az „operációs rendszer szintjén” foglalnak helyet – ami ebben az esetben lényegében annyit jelent, hogy az egyes projekteken (azaz projekt könyvtárokon) kívül. Ennek a megoldásnak az előnye, hogy amennyiben több projektben is használni szeretnénk ugyanazt a phpcs szkriptet vagy kódolási szabványt, nem kell minden egyes projektnek külön-külön tartalmaznia az ezekkel kapcsolatos fájlokat, hiszen a phpcs szkriptet elég egyszer rendszer szinten telepíteni, a kódolási szabványokat pedig szintén egyetlen helyen gyűjthetjük. További előny, hogy nem kell foglakozzunk az imént említett fájlok verziókezelésével, hiszen ebben az esetben azok nem képezik részét a projektnek. A rendszer szintű telepítés hátránya, hogy így nem olyan kényelmes a különböző verziójú phpcs szkriptek illetve kódolási szabványok kezelése.

3. Kombinált telepítési mód

Ez a telepítési mód (nem túl meglepő módon) az első kettőnek a kombinációja, azaz a több projektben is használni kívánt (vagy a legsűrűbben használt) phpcs szkriptet és szabvány könyvtárakat telepíthetjük rendszer szinten, egyedi esetekben pedig továbbra is lehetőségünk van projekt szintű telepítésekre.

Projekt szintű telepítés

Maga a projekt szintű telepítés több módon is kivitelezhető, de a legkényelmesebb megoldás a Composer használata. A Composer egy olyan eszköz, ami lehetővé teszi hogy úgynevezett csomagok számára függőségeket definiáljunk, amiket aztán a csomag telepítésénél ő majd automatikusan ellenőriz és telepít a projekten belül. A csomag kifejezés az ebben az esetben egy speciális gyűjtőnév különböző projekt komponensek számára (úgy mint pl. egy modul, könyvtár vagy valamilyen szkript), tehát nem tévesztendő össze például a Unix rendszerek hagyományos értelemben vett csomagjaival.

Mivel a Composer csomagokkal és könyvtárakkal dolgozik, ezért egy egyszerű csomagkezelőként is gondolhatnánk rá, viszont fontos, hogy alapértelmezetten sohasem telepít semmit sem globálisan, csupán projekt szinten, ezért is helytelen a csomagkezelő meghatározás. A Composert tehát arra fogjuk használni, hogy a phpcs-t és a szükséges kódolási szabványokat minél egyszerűbben telepíthessük a projekten belül.

A Composer telepítése

A Composert magát is telepíthetjük lokálisan projekt szinten, illetve globálisan is. A különböző telepítési módokról ezen az oldalon találunk bővebb leírást. Globális telepítés esetében Unix rendszereknél mindössze két egyszerű parancsot kell végrehajtanunk, melyek az alábbiak:

$ curl -sS https://getcomposer.org/installer | php<br />
$ sudo mv composer.phar /usr/local/bin/composer

A második parancs ahhoz szükséges, hogy a Composert egyszerűen a composer parancs kiadásával tudjuk futtatni a terminálból, ahelyett hogy a php composer.phar parancsot kéne kiadnunk. Amennyiben a Composer telepítése sikeres volt, a composer parancs kiadása után valami ilyesmit kell látnunk:

A Composer inicializálása

A Composer telepítése után indítsuk el a PhpStormot és a projekt kezelő ablakban jelöljük ki a projekt gyökérkönyvtárát. Erre azért van szükség, hogy a Composer által letöltött fájlok megfelelő helyre kerüljenek. Ezután látogassunk el a Tools > Composer > Init Composer… menüpontra, majd a megjelenő ablakban adjuk meg a composer.phar fájl elérési útvonalát. Amennyiben követtük az eddigieket, tallózzuk ki a /usr/local/bin/composer útvonalat.

A phpcs és coder csomagok telepítése

Miután megtörtént a Composer telepítése és inicializálása, nekiállhatunk letölteni a szükséges csomagokat. Először is a phpcs-t kell telepítenünk, amihez a PhpStormban látogassunk el a Tools > Composer > Add dependency… menüpontra. A megjelenő ablakban keressünk rá a squizlabs/php_codesniffer nevű csomagra.

A telepítendő phpcs verzió kiválasztása némi körültekintést igényel, ugyanis a phpcs szkript és a használni kívánt coding standards könyvtár kompatibilis kell legyen egymással. Amennyiben erre nem figyelünk oda, különféle hibaüzeneteket kaphatunk a phpcs futása közben. A tapasztalat azt mutatja, hogy a megfelelő működés érdekében Drupal 8.x-es projekt (és coding standards könyvtár) esetében célszerű a lehető legstabilabb 2.x verziójú, Drupal 7.x-es projekt esetében pedig hasonló módon egy 1.x verziójú phpcs telepítése.

Mivel példaképpen egy Drupal 8.0 alapú projekttel dolgozunk, ezért a telepítendő phpcs verziónak válasszuk mondjuk a 2.0.0a2 verziót vagy egy ennél újabbat. A phpcs telepítése után, hasonló módon járjunk el a drupal/coder csomaggal is, értelem szerűen valamilyen 8.x-es verziót telepítve.

Az egyes csomagokat akár manuálisan terminálból is telepíthetjük a $ composer require : parancs kiadásával (ahol a és a értelemszerűen helyettesítendő a megfelelő paraméterekkel), sőt gyakorlatilag ez a parancs kerül futtatásra, amikor a csomagkezelőben az Install gombra kattintunk.

A phpcs konfigurálása

A phpcs és a coding standards csomag telepítése után a phpcs konfigurálása következik, amit a PhpStorm-ban a File > Settings > [Project Settings] > PHP > Code Sniffer útvonalon tudunk elvégezni.

Először is meg kell mondanunk a PhpStormnak, hogy merre található a phpcs elindításához szükséges fájl. Composerrel való telepítés és Drupal 8.x alapú projekt esetében ez a projekten belül a /core/vendor/bin/phpcs útvonalon, Drupal 7.x alapú projekt esetében pedig a /vendor/bin/phpcs útvonalon található. Miután kitallóztuk a phpcs launchert, nyomjunk a Validate gombra, amivel ellenőrizhető, hogy a PhpStorm és a phpcs közötti kommunikáció megfelelő-e. A Validate gomb használata egyébként megfelel a $ phpcs --version parancs kiadásának, amivel a phpcs szkript verziója kérdezhető le.

További beállítások keretében megadhatjuk, hogy fájlonként mennyiben szeretnénk maximalizálni a megjelenő phpcs üzenetek számát, továbbá egy maximális várakozási időt is beállíthatunk a phpcs szkripttel kapcsolatban, amivel azt szabhatjuk meg, hogy a PhpStorm mennyi ideig várakozzon a phpcs szkriptre, amikor az éppen elemez egy fájlt. Lassabb gépek esetében tehát célszerű lehet ezt a várakozási időt kicsit nagyobb értékre venni.

Az előbbi beállítások alatt egy (kezdetben üres) lista látható, ahol azok a manuálisan felvett fájlok kerülnek felsorolásra, amiket a phpcs figyelmen kívül fog hagyni és nem fog ellenőrizni, azaz amelyeknél kikapcsoltuk a phpcs vizsgálatot.

A phpcs típusú fájl vizsgálat bekapcsolása

Utolsó lépésként be kell kapcsoljuk a phpcs típusú fájl vizsgálatot, melyet a PhpStorm-ban a File > Settings > [Project Settings] > Inspections > PHP > PHP Code Sniffer validation útvonalon található opcióval tudunk megtenni. Ez az opció elméletileg az aktuális projekten belül minden fájlra bekapcsolja az ellenőrzést (gyakorlatilag előfordulhat, hogy ez valamiért nem megfelelően működik), még akkor is, ha azok nem .php típusú fájlok, ebben az esetben ugyanis egyszerűen figyelmen kívül lesznek hagyva. Amennyiben ez a minden fájlra kiterjedő vizsgálat nem felel meg az igényeinknek, esetleg feleslegesnek tartjuk, lehetőségünk van a megvizsgálandó fájlok és fájltípusok pontos specifikálására is, de erről majd a későbbiekben a fájl scope-ok keretein belül lesz szó.

A fájl vizsgálat bekapcsolása mellett még be kell állítanunk néhány fontos dolgot. A "Severity" opcióval azt szabályozhatjuk, hogy a kódolási szabványok megsértése milyen súlyosságú figyelmeztetésként jelenjen meg a felhasználó számára. Ez az opció alapértelmezetten "Weak Warning" típusúra van állítva, de érdemes "Warning"-ra állítani. A "Show warnings as" opció arra van hatással, hogy a figyelmeztetések miképpen jelenjenek meg. Ezt az opciót is érdemes "Warning" típusúra állítani. A legfontosabb beállítási lehetőség a "Coding standards" megadása, amivel értelemszerűen azt mondhatjuk meg a phpcs-nek, hogy milyen kódolási szabvány szerint ellenőrizze a projektben található fájlokat. Mint ahogy arról már korábban is szó volt, a listában láthatunk néhány alapértelmezetten elérhető coding standards csomagot, nekünk viszont a Drupal coding standards-re lenne szükségünk, tehát válasszuk a Custom opciót, amivel lehetőségünk van kitallózni egyedi coding standards csomagokat is. Composerrel való telepítés és Drupal 8.x alapú projekt esetében a Drupal coding standards szabályokat a projekten belül a /core/vendor/drupal/coder/coder_sniffer/Drupal útvonalon, Drupal 7.x alapú projekt esetében pedig a /vendor/drupal/coder/coder_sniffer/Drupal útvonalon találhatjuk meg.

A beállítások elmentése után az egyes .php típusú fájlok megnyitásakor illetve szerkesztésekor a beállított kódolási szabványnak és figyelmeztetéseknek megfelelően a phpcs automatikusan ellenőrizni fogja a kódunkat. A PhpStorm a phpcs-től származó üzeneteket mindig "phpcs:" kezdettel fogja megjeleníteni, hogy ezáltal is megkülönböztethetőek legyenek az egyéb típusú üzenetektől.

Rendszer szintű telepítés

Rendszer szintű telepítés esetében első lépésként telepítenünk kell a phpcs-t, illetve be kell szerezzük, majd a megfelelő helyre kell másoljuk a Drupal coding standards-et tömörítő fájl csomagot. A phpcs telepítése megint csak történhet többféle módon is, de a különböző verziók miatt talán célszerű PEAR segítségével telepíteni. Ahogy arról a projekt szintű telepítés esetében már szó volt, telepítés előtt nem árt körültekintően kiválasztani a megfelelő phpcs verziót.

A phpcs PEAR segítségével történő telepítéséhez, az alábbi parancs kiadása szükséges.

$ sudo pear install PHP_CodeSniffer-2.0.0a2

A telepítés után a $ phpcs --version parancs kiadásával ellenőrizhetjük, hogy sikerült-e a telepítés.

Miután a telepítéssel megvolnánk, szükségünk lesz még a Drupal coding standards-et tartalmazó szabály könyvtárakra, melyek a Coder modul részét képezik. A Coder modulból értelemszerűen a projektben használt Drupal verziónak megfelelő verziót kell letölteni, és nem szükséges egészében felhasználni, így telepíteni és bekapcsolni se kell, csupán a benne található coder_sniffer/Drupal könyvtárra lesz szükségünk. Ezt a könyvtárat kell bemásolnunk, vagy belinkelnünk a phpcs kódolási szabványokat tartalmazó könyvtárába, ami Ubuntun történő telepítés esetén a /usr/share/php/PHP/CodeSniffer/Standards útvonalon található. Ha megvizsgáljuk ennek a könyvtárnak a tartalmát, akkor láthatjuk, hogy a phpcs-vel együtt egyúttal települt néhány coding standards könyvtár is, úgy mint például PEAR, PSR1, PSR2, Squiz vagy Zend.

Feltételezve, hogy a Coder modult a /home/[username]/Downloads mappába töltöttük le, a Drupal codings standards megfelelő helyre történő átmásolásához a következő parancs kiadása szükséges.

$ sudo cp -Ri /home/whitelikeman/Downloads/coder/coder_sniffer/Drupal /usr/share/php/PHP/CodeSniffer/Standards

A phpcs konfigurálása és a fájl vizsgálat bekapcsolása

A phpcs PhpStormban való konfigurálása és a fájl vizsgálat bekapcsolása néhány különbség kivételével ugyanúgy történik, mint ahogy arról a projekt szintű telepítés esetében korábban már szó volt.

Az egyik eltérés, hogy a phpcs lanucher az most nem a projekt könyvtárában foglal helyet, hanem (Ubuntun történő telepítés esetén) a /usr/bin/phpcs útvonalon található, tehát PhpStormban a File > Settings > [Project Settings] > PHP > Code Sniffer alatt található beállításoknál ezt az útvonalat kell megadnunk.

A másik differencia a fájl vizsgálatok bekapcsolásánál van. A projekt szintű telepítéstől eltérően ebben az esetben most nem a "Custom" opciót választjuk a "Coding standards" beállításnál, hanem a (korábbi másolás vagy linkelés eredményeképpen megjelenő) "Drupal"-t. Amennyiben a "Drupal" opció mégse jelenne meg, nyomjunk a frissítés gombra.

Azonos típusú, de eltérő verziójú kódolási szabványok használata

A projekt szintű telepítéstől eltérően rendszer szintű telepítésnél felmerülhet az az igény, hogy azonos típusú, de eltérő verziójú kódolási szabványokat szeretnénk egy helyen tudni (pl. /usr/share/php/PHP/CodeSniffer/Standards). Példaképpen tegyük fel, hogy egy Drupal 7.x-es és egy Drupal 8.x-es projekttel is dolgozni szeretnénk, melyekre eltérő kódolási szabványok vonatkoznak, viszont a 7.x-es és a 8.x-es Coder modulokat megvizsgálva észrevehetjük, hogy a kódolási szabályok mind a két esetben egy ugyan olyan nevezéktannal ellátott "Drupal" nevű könyvtárban foglalnak helyet. Talán kézenfekvőnek tűnik, de Drupal esetében sajnos nem elegendő ezen könyvtárak szimpla átnevezése, majd a /usr/share/php/PHP/CodeSniffer/Standards könyvtárba másolása.

A legegyszerűbb és „legtisztább” megoldás az, hogy a különböző verziójú szabvány könyvtárakat nem a /usr/share/php/PHP/CodeSniffer/Standards könyvtárba másoljuk, hanem olyan helyekre, ahol különböző könyvtárakban foglalnak helyet, ugyanakkor könnyen megkülönböztethetjük őket. Ezek után PhpStormban a "Coding Standards" beállítási lehetőségnél a "Custom" opciót választva egyszerűen kitallózhatjuk a szükséges könyvtárat.

Ha mindenképpen egy helyen szeretnénk tudni a különböző verziójú Drupal coding standards könyvtárakat, akkor magukat a könyvtárakat és a bennük levő fájlokban található "Drupal" kifejezéseket (pl. a ruleset neve, a különböző szabályokra vonatkozó referencia hivatkozások, névtér hivatkozások, az egyes osztályok nevei) átírhatjuk a konkrét Drupal verziónak megfelelően például "Drupal7"-re, vagy "Drupal8"-ra, majd az így módosított könyvtárakat már elhelyezhetjük a /usr/share/php/PHP/CodeSniffer/Standards könyvtárban. Természetesen ezzel a megoldással (azon túl, hogy módosítottuk az eredeti forráskódot, ami már önmagában sem egy elegáns megoldás) az egyes könyvtárak frissítése is macerás feladat, hiszen az átnevezéseket minden egyes frissítés alkalmával el kéne játszani, tehát már csak ezért sem ajánlott ez a módszer (viszont ettől függetlenül gyakorlati szempontból működőképes). Az egyéb, nem Drupal típusú szabvány könyvtárak esetében természetesen nem biztos, hogy működik az imént említett trükk.

Fájl scope-ok

A PhpStormban lehetőségünk van úgynevezett scope-ok definiálására. Egy scope alatt fájlok olyan csoportja értendő, amiken bizonyos operációk hajthatóak végre. A különböző típusú fájl vizsgálatoknál (így tehát a phpcs esetében is) lehetőségünk van arra, hogy a fájlok ellenőrzését csak meghatározott scope-okon hajtsuk végre, amennyiben erre szükségünk van. A PhpStormban a scope-ok menedzselését a File > Settings > [Project Settings] > Scopes útvonal alatt találhatjuk.

Scope-ok létrehozása

A példa kedvéért hozzunk létre egy olyan scope-ot, ami egy Drupal 8.0-s projekten belül csak a views core modulban található .inc és .php kiterjesztésű fájlokra vonatkozik. A scope neve legyen scope_for_views. A létrehozásához kattintsunk az Add scope című gombra, majd a megjelenő listában válasszuk a Local opciót. Miután megadtuk a scope nevét, meg kell adjuk a fájlok kiválasztásához szükséges illesztési mintát is.

Látható, hogy az illesztési minta szerkesztése közben a PhpStorm folyamatosan listázza és számolja azokat a fájlokat amikre a minta illeszkedik, ezáltal könnyen ellenőrizhetjük annak helyességét. A példában szereplő fájlok kiválasztásához, használjuk a "file:core/modules/views//*.inc||file:core/modules/views//*.php" illesztési mintát, amivel tehát minden .inc és .php kiterjesztésű fájlt kijelölünk a views core modulon belül. A scope-okkal és az illesztési mintákban használható kifejezésekkel kapcsolatban ezen a webcímen találunk bővebb információkat. Miután befejeztük a scope szerkesztését, ne felejtsük el elmenteni.

Scope-ok hozzárendelése a fájl vizsgálatokhoz

Ahogy arról korábban már szó esett, a különböző típusú fájl vizsgálatokat a File > Settings > [Project Settings] > Inspections > PHP > PHP Code Sniffer validation útvonal alatt található beállításokkal tudjuk menedzselni a PhpStormban. Itt a PHP > PHP Code Sniffer validation bejegyzésen jobb egér gombbal kattintva, majd a felugró menüben az Add Scope opciót választva lehetőségünk van scope-okkal szabályozni a phpcs típusú fájl vizsgálatokat. Természetesen ez nem csak a phpcs típusú ellenőrzések esetében működik, hanem az összes többi esetben is.

Miután kiválasztottuk a korábban létrehozott scope_for_views scope-ot, a PHP Code Sniffer validation bejegyzés alatt megjelenik a fájl vizsgálat esetében használt scope-ok listája, ahol amellett, hogy az egyes scope-okat egyenként ki-be kapcsolhatjuk, lehetőségünk van scope-onként kiválasztani a kódolási szabványokat, illetve beállítani a figyelmeztetési módokat.

Hibaüzenetek

Előfordulhat, hogy a fájlok megnyitásakor vagy szerkesztésükkor különböző hibaüzeneteket kapunk a phpcs-től. Ennek a legvalószínűbb oka az lehet, hogy a telepített phpcs verzió nem kompatibilis a használni kívánt coding standards könyvtárral, tehát a telepítés előtt ennek mindenképpen érdemes utánajárni. Ahogy arról a projekt szintű telepítés esetében már szó esett, a megfelelő működés érdekében Drupal 8.x-es projekt (és coding standards könyvtár) esetében, célszerű a lehető legstabilabb 2.x verziójú, Drupal 7.x-es projekt esetében pedig hasonló módon egy 1.x verziójú phpcs telepítése.

Az egymással kompatibilis phpcs szkriptek és coding standards csomagok ellenére az is megeshet, hogy a felhasznált coding standards könyvtár (a nem kellőképpen stabil mivolta miatt) hibákat tartalmaz.

Hibaüzeneteket generálhat több egyszerre megnyitott olyan projekt is, melyek phpcs szempontból különbözőképpen vannak konfigurálva. Ez több mint valószínű hogy egy PhpStorm bug, és azon kívül, hogy jelentjük, sajnos nem sok mindent tudunk vele direktben kezdeni. Amennyiben belefutunk ebbe a hibába, a nyitott projektek közül próbáljunk meg csak az egyikben phpcs-t használni. Esetenként az egyes projektekre vonatkozó beállítások törlése is segíthet (.idea).

Hasznos linkek, források

Technológia: Drupal 7Drupal 8PHP_CodesnifferComposerPhpStorm