Jelenlegi hely

PHP_CodeSniffer használata PhpStorm-ban

WITTMANN Balázs Ádám képe

A PHP_CodeSniffer egy olyan PHP5 szkript, ami a PHP, JavaScript és CSS típusú programszövegek 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ével egyúttal telepítésre kerül néhány kódolási szabvány könyvtár is, úgy mint például PEAR, PSR1, PSR2, Squiz vagy Zend, de a listát lehetőségünk van olyan további elemekkel is bővíteni mint a Drupal coding standards.

A Drupal specifikus kódolási szabványokat a Coder modul tartalmazza. Amennyiben csak a phpcs-hez szeretnénk beszerezni a megfelelő verziójú szabvány könyvtárat, nem szükséges magának a Coder modulnak a telepítése, mivel csak a szabvánnyal kapcsolatos alkönyvtárára lesz szükségünk. 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

Alapvetően háromféle módon telepíthetjük és használhatjuk a phpcs-t és az egyes kódolási szabvány könyvtárakat. A telepítési módok között csupán kényelmi és logikai különbségek vannak, tehát bármelyiket is válasszuk az a funkcionális működést nem fogja befolyásolni.

1. Projekt szintű telepítés

Ebben az esetben a phpcs szkript és a használt kódolási szabvány könyvtár is a projekt könyvtáron belül foglal helyet. Ennek a megoldásnak az az 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 a phpcs-vel kapcsolatos fájlok és könyvtárak 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

A rendszer szintű telepítés azt jelenti, hogy a phpcs szkript és a kódolási szabványt tartalmazó könyvtár is valahol az „operációs rendszer szintjén”, azaz a projekt könyvtáron kívül foglal helyet. Ebben az esetben, ha 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 azok rendszer szinten lettek telepítve ezért egyszerre több projektben is használhatóak. További előny, hogy nem kell foglalkozzunk az imént említett fájlok verziókezelésével, mivel azok a projekt könyvtáron kívül helyezkednek el. A rendszer szintű telepítés hátránya, hogy ebben az esetben nem olyan kényelmes a különböző verziójú phpcs szkriptek és szabvány könyvtárak 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. Azok a phpcs szkriptek és szabvány könyvtárak amik a legsűrűbben lesznek használva telepíthetőek rendszer szinten, egyedi esetekben pedig továbbra is lehetőségünk van projekt szintű telepítésre.

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, amik a csomag telepítésénél automatikusan ellenőrzésre és telepítésre kerülnek. 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 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 a következők:

$ curl -sS https://getcomposer.org/installer | php
$ 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 telepítés után inicializálnunk kell a Composert. Ehhez 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. A phpcs telepítéséhez kattintsunk a Tools > Composer > Add dependency… menüponton, a csomagkezelő ablakban pedig 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 kódolási szabvány könyvtár kompatibilis kell hogy legyen egymással. Amennyiben erre nem figyelünk oda, később 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 célszerű a lehető legújabb és legstabilabb 2.x verziójú phpcs telepítése Drupal 8.x-es projekthez, és hasonlóképpen valamilyen 1.x verziójú phpcs telepítése Drupal 7.x-es projekthez.

Mivel példaképpen egy Drupal 8.0 alapú projekttel dolgozunk, ezért válasszuk a 2.0.0a2 phpcs verziót vagy egy ennél újabbat. A phpcs csomag telepítése után keressünk rá a drupal/coder csomagra és azt is telepítsük fel hasonlóan.

Az egyes csomagokat akár manuálisan terminálból is telepíthetjük a $ composer require <csomagnév>:<verzió> parancs kiadásával (ahol a <csomagnév> és a <verzió> értelemszerűen helyettesítendő a pontos csomagnévvel és verzióval). Tulajdonképpen ez a parancs kerül futtatásra, amikor a csomag kezelő ablakban a telepítés gombra kattintunk.

A phpcs konfigurálása

A phpcs használata előtt konfigurálnunk kell a beállításait, amit a PhpStormban a File > Settings > [Project Settings] > PHP > Code Sniffer menüpont alatt tudunk elvégezni.

Először is meg kell mondanunk a PhpStormnak, hogy merre található a phpcs futtatásához szükséges fájl. Mivel a telepítéshez Composert használtunk és egy Drupal 8.0 alapú projekttel dolgozunk, ezért a keresett fájl alapértelmezetten a projekt könyvtáron belül a /core/vendor/bin/phpcs útvonalon található. Amennyiben egy Drupal 7.x alapú projekttel dolgozunk, ez az útvonal /vendor/bin/phpcs. Miután megadtuk a futtatható fájl elérési útvonalát kattintsunk 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 lehetséges phpcs üzenetek számát, továbbá egy maximális várakozási időt is beállíthatunk a PhpStorm számára hogy 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 állítani.

Az előbbi beállítások alatt egy (kezdetben üres) lista látható, ahol azok a fájlok kerülnek felsorolásra, amiket a phpcs figyelmen kívül fog hagyni és nem fog ellenőrizni. Ebbe a listába akkor kerülhetnek be fájlok, amikor egy fájl ellenőrzés során valamilyen fajta phpcs hiba történik, és az “Exclude from PHP Code Sniffer analysis.” című linkre kattintunk az eseménynapló ablakban, vagy a hibüzenettel kapcsolatos felugró üzenetben.

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 PhpStormban a File > Settings > [Project Settings] > Inspections > PHP > PHP Code Sniffer validation útvonalon található opcióval tudunk megtenni. Ez az opció elméletileg minden projekt fájlra bekapcsolja az ellenőrzést (habár a gyakorlatban ez nem mindig működik megfelelően), 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 az általános fájl vizsgálat nem felel meg az igényeinknek, esetleg spórolni akarunk némi CPU időt, lehetőségünk van konkrét fájl típusok és könyvtárak megadására is, de erről majd a későbbiekben a fájl scope-ok keretein belül lesz szó.

Amikor bekapcsoljuk a phpcs fájl vizsgálatot, meg kell adjuk hogy a phpcs miképpen jelenítse meg az üzeneteit, és ki kell választanunk a kódolási szabványt amit használni akarunk. A "Severity" opcióval a fájl vizsgálat szigorúságát szabályozhatjuk. Ennek az opciónak az alapértelmezett értéke "Weak Warning", de érdemes "Warning"-ra állítani. A "Show warnings as" opció arra van hatással, hogy a phpcs üzenetek miképpen jelenjenek meg. A legfontosabb beállítási lehetőség a "Coding standard", mert ez az ahol kiválaszthatjuk hogy milyen kódolási szabványt akarunk használni a fájl ellenőrzésekhez. Mint ahogy arról korábban már szó esett, néhány kódolási szabvány alapértelmezetten is elérhető, viszont a Drupal nincs köztük ezért a “Custom” opciót választva manuálisan kell megadjuk a szabvány könyvtár elérési útvonalát. Mivel a Drupal specifikus kódolási szabványokat Composerrel telepítettük és egy Drupal 8.0 alapú projekttel dolgozunk, a szabvány könyvtárat a projekten belül a /core/vendor/drupal/coder/coder_sniffer/Drupal útvonalon találhatjuk. Egy Drupal 7.x alapú projekt esetében ez az útvonal a /vendor/drupal/coder/coder_sniffer/Drupal.

Miután minden beállítást elmentettünk, a phpcs automatikusan ellenőrizni fogja a projekt fájlokat a kiválasztott kódolási szabványnak megfelelően. A PhpStormban a phpcs-től származó üzenetek "phpcs:" kezdettel fognak megjelenni, ezáltal könnyen megkülönböztethetőek 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, aztán le kell töltenünk, majd a megfelelő helyre kell másoljuk vagy linkeljük a kódolási szabvány könyvtárat. A phpcs telepítése megint csak történhet többféle módon is, de ha egy konkrét verziót szeretnénk telepíteni, akkor a PEAR segítségével ezt könnyen megtehetjük. Ahogy arról a projekt szintű telepítés esetében már szó volt, telepítés előtt fontos a megfelelő phpcs verzió kiválasztása.

A phpcs PEAR segítségével történő telepítéséhez a következő 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 a telepítés sikerességét.

A második lépés a Drupal specifikus kódolási szabványok letöltése, melyek a Coder modul részét képezik. A modul letöltése előtt bizonyosodjunk meg arról, hogy a megfelelő verziót töltjük le. Magának a modulnak a telepítése és bekapcsolása nem szükséges, mert csak a benne található szabvány könyvtárra lesz szükségünk, ami a modulon belül a coder_sniffer/Drupal útvonalon található. Ezt az egész könyvtárat kell bemásolnunk vagy belinkelnünk a phpcs kódolási szabványokat tartalmazó könyvtárába, ami Ubuntu esetében 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 tartalmaz néhány alapértelmezetten használható szabvány könyvtárat, úgy mint PEAR, PSR1, PSR2, Squiz vagy Zend.

Feltételezve, hogy a Coder modul a /home/[username]/Downloads mappába lett letöltve (és kicsomagolva), a kódolási szabvány könyvtár megfelelő helyre történő má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 konfigurálás folyamata közel azonos a projekt szintű telepítés esetében leírtakkal, de van néhány apró különbség. Az első, hogy ebben az esetben a phpcs futtatásához szükséges fájl a projekt könyvtáron kívül foglal helyet, még specifikusabban a /usr/bin/phpcs útvonalon ha Ubuntut használunk, ezért ezt az útvonalat kell megadnunk a phpcs konfigurációs beállításainál (File > Settings > [Project Settings] > PHP > Code Sniffer). A másik különbség a fájl vizsgálat bekapcsolásánál található, mert ebben az esetben a kódolási szabvány listában már elérhető a “Drupal” opció is (ha mégsem akkor kattintsunk a frissítés gombon) tehát egyszerűen kiválaszthatjuk ahelyett, hogy a “Custom” opcióval meg kéne adunk az elérési útvonalát.

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

Amennyiben a rendszer szintű telepítést preferáljuk, valószínűleg különböző verziókat is használni szeretnénk ugyan abból a kódolási szabvány könyvtárból, továbbá szeretnénk őket egy helyen tudni (pl. a /usr/share/php/PHP/CodeSniffer/Standards könyvtárban). Példaképpen tegyük fel, hogy egy 7.x-es és egy 8.x-es Drupal projekttel is dolgozunk egyszerre, és mind a kettőben szeretnénk phpcs-t használni. Természetesen a 7.x-es és a 8.x-es Drupal kódolási szabvány könyvtárak különbözőek, de ha vetünk egy pillantást a struktúrájukra, akkor láthatjuk hogy a könyvtár és fájl nevek szinte megegyeznek. Talán kézenfekvőnek tűnik, de sajnos nem elegendő ezen könyvtárak egyszerű átnevezése, majd a /usr/share/php/PHP/CodeSniffer/Standards könyvtárba másolása. Az egyetlen tiszta megoldás, hogy a különböző szabvány könyvtárakat különböző könyvtárakban helyezzük el, majd PhpStormban a fájl validációs beállításoknál a “Custom” opciót használva kiválasztjuk a megfelelő szabványt. Esetleg megpróbálhatjuk átnevezni és módosítani a fájlokat a kódolási szabványok könyvtárában, de még ha ez a megoldás működik is, a frissítés problémás lesz amint egy új verzió válik elérhetővé a szabvány könyvtárból.

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 típusú műveletek hajthatóak végre. A fájl vizsgálatoknál (így tehát a phpcs típusú fájl vizsgálat esetében is) lehetőségünk van scope-ok kiválasztására, hogy ha az ellenőrzést csak meghatározott könyvtárakon vagy fájlokon akarjuk végrehajtani. A scope-ok menedzselését a File > Settings > [Project Settings] > Scopes útvonal alatt találhatjuk a PhpStormban.

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.

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. A scope-ok illesztési mintáiban 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 ú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 szabályozni a phpcs típusú fájl vizsgálat hatáskörét. Természetesen ez nem csak a phpcs típusú ellenőrzés 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, egy scope lista jelenik meg a “PHP Code Sniffer validation” checkbox alatt. Ebben a listában ki-be kapcsolhatjuk az egyes scope-okat, továbbá scope-onként menedzselhetjük a phpcs üzeneteket vagy kiválaszthatjuk a használni kívánt kódolási szabványt.

Hibaüzenetek

Előfordulhat, hogy amikor PhpStormban fájlokat akarunk megnyitni vagy szerkeszteni, különböző phpcs-vel kapcsolatos hibaüzeneteket kapunk. Ezekben az esetekben a legvalószínűbb ok, hogy a telepített phpcs verzió nem kompatibilis a használni kívánt kódolási szabvány könyvtárral. Ahogy arról korábban már többször is szó esett, fontos hogy kompatibilis eszközöket használjunk. Egy 8.x-es Drupal projekt (és kódolási szabvány könyvtár) esetében, tanácsos a legújabb és legstabilabb 2.x verziójú phpcs telepítése, egy 7.x-es Drupal projekt esetében pedig hasonlóan valamilyen 1.x verzió telepítése.

A hibaüzenetek egy másik oka lehet, hogy a használt kódolási szabvány könyvtár hibákat tartalmaz például azért, mert még csak alpha verziójú, tehát próbáljunk meg minél stabilabb kiadásokat használni. Abban az esetben hogy ha egy lassabb géppel rendelkezünk, megpróbálhatjuk növelni a “Tool process timeout” beállításnál megadott értéket a File > Settings > [Project Settings] > PHP > Code Sniffer beállításoknál, hogy több időt adjunk a phpcs-nek az egyes fájlok átvizsgálásához.

Elég idegesítő, de (7.1.3-as PhpStormot használva) 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 valószínűleg egy PhpStorm bug és az egyetlen dolog amit tehetünk (azon kívül hogy jelentjük), hogy az éppen nem használt projekteket bezárjuk, vagy a nyitott projektek közül megpróbálunk csak az egyikben phpcs-t használni. Abban az esetben ha valami balul sülne el, végső megoldásképpen töröljük a PhpStorm aktuális projektre vonatkozó beállításait (.idea) majd ezután indítsuk újra a PhpStormot.

Hasznos linkek, források