Šta je PSR-12?

Ako programirate u PHP-u, sigurno ste do sada čuli za pojam PSR-12. U pitanju je jedan od najšire prihvaćenih standarda kodiranja u PHP zajednici, koji služi kao vodič za pisanje doslednog, čitljivog i održivog koda. 

Bilo da radite samostalno na malom projektu, kao deo nekog većeg tima ili jednostavno samo doprinosite open-source zajednici, PSR-12 je tu da svima nama olakša svakodnevni posao.

Zato ćemo u ovom tekstu objasniti šta je PSR-12, zašto je važan, koja su osnovna pravila koja uvodi i kako ga najlakše možete primeniti u svojim PHP projektima.

Šta je PSR-12?

PSR-12 je specifikacija za stil kodiranja u PHP-u, koju je kreirala organizacija PHP-FIG (PHP Framework Interop Group). Cilj joj je da unapredi prethodni PSR-2 standard i bolje uskladi smernice sa savremenim mogućnostima PHP-a (posebno verzija 7 i 8).

U pitanju je dogovoreni skup pravila koji određuje kako bi PHP kod trebalo da izgleda, od načina pisanja klasa i funkcija, preko uvlačenja redova i razmaka, do dužine linija i organizacije use deklaracija.

Možete je zamisliti kao gramatička pravila za PHP kod. Nije obavezna, ali ako je poštujete, svi koji čitaju vaš kod znaće odmah gde se šta nalazi, šta koja linija radi i kako da se nadovežu na ono što ste vi već napisali.

Zašto je PSR-12 važan?

Možda vam se čini da nije presudno kako vaš kod izgleda, sve dok on radi kako treba. I to je donekle tačno, ali samo ako radite sami na nekom kratkom projektu i ne planirate da ga ikada više otvarate. U svim drugim slučajevima, vaš stil pisanja koda ima veliki uticaj na kvalitet i dugovečnost projekta.

PSR-12 standard donosi nekoliko ključnih prednosti:

• Čitljivost. Dosledno napisan kod je lakši za razumevanje, kako vama nakon izvesnog vremena, tako i vašim kolegama koji prvi put ulaze u projekat. Jasna struktura i ujednačen raspored elemenata omogućavaju brže snalaženje, bez gubljenja vremena na dešifrovanje tuđih navika u pisanju.
• Saradnja. Kada svi članovi tima slede isti stil, zajednički rad postaje efikasniji. Pregledi izmena su pregledniji, konflikti pri spajanju koda ređi, a svi naknadni dodaci se lakše integrišu bez nepotrebnih korekcija stila.
• Održavanje. Vremenom, svaki projekat raste i postaje složeniji. Ako je kod od početka strukturiran jasno i predvidljivo, lakše je debagovati ili refaktorisati kod, bez straha da ćete nešto slučajno pokvariti.
• Kompatibilnost. Korišćenjem ujednačenog stila, posebno kada se držite šire prihvaćenih standarda kao što je PSR-12, olakšavate integraciju spoljašnjih biblioteka i modula. To se naročito odnosi na open-source projekte, gde je izuzetno važno da različiti delovi koda budu usklađeni.

Drugim rečima, poštovanje PSR-12 standarda nije formalnost, već alat koji pomaže da vaš kod bude čitljiv, stabilan i spreman za timski rad, a kasnije i za održavanje.

Ključna pravila PSR-12 standarda

Struktura fajlova

PHP fajlovi moraju da počinju sa <?php oznakom. Korišćenje short tagova kao <? je zabranjeno.

Loš primer:

<?

echo "Nije ispravno!";

?>

Ispravno:

<?php

echo "Ispravno!";

?>

Fajlovi moraju da budu enkodirani kao UTF-8 bez BOM-a (Byte Order Mark).

Maksimalna dužina linije je 120 karaktera, a preporuka je da bude ispod 80 karaktera zbog preglednosti.

Nema praznih linija nakon otvarajuće linije (ako se koristi).

Pre return izraza, kao i između metoda u klasama, mora da postoji jedna prazna linija radi bolje preglednosti.

namespace i use deklaracije

Organizacija prostora imena i uvoza mora da bude precizna i dosledna.

<?php

namespace App\Controllers;

use App\Models\User;

use App\Repositories\UserRepository;

class UserController {

    // telo klase

}

namespace ide odmah posle <?php, nakon čega sledi prazna linija.

Sve use deklaracije grupisane su zajedno, bez komentara između. Posle poslednjeg use, obavezna je još jedna prazna linija.

Loš primer:

<?php

use App\Repositories\UserRepository;

namespace App\Controllers;

Ispravno:

<?php

namespace App\Controllers;

use App\Repositories\UserRepository;

Još jedan loš primer (neabecedni redosled, komentari među importima):

use App\Z;

use App\A; // komentar

use App\K;

Ispravno:

use App\A;

use App\K;

use App\Z;

Klase i metode

Zagrada { mora da bude u istoj liniji kao class ili function deklaracija.

Svojstva (atributi) moraju da imaju eksplicitno definisanu vidljivost (public, protected, private).

Isto važi i za metode – svaka funkcija mora da ima deklarisanu vidljivost.

class UserController {

    private $userRepository;

    public function __construct(UserRepository $userRepository) {

        $this->userRepository = $userRepository;

    }

}

Loš primer:

class Book {

var $title;

function getTitle( ) {

return $this->title; }}

Ispravno:

class Book

{

    private string $title;

    public function getTitle(): string

    {

        return $this->title;

    }

}

Kontrolne strukture

Mora da postoji jedan razmak između ključne reči i otvarajuće zagrade: if ( umesto if(.

Uvek koristite {} za telo uslova, čak i kada se radi o jednoj liniji.

Indentacija mora biti četiri razmaka, ne tab.

if ($user->isAdmin()) {

    echo "Korisnik je admin.";

} else {

    echo "Korisnik nije admin.";

}

Loš primer:

if($x)

echo "Greška!";

Ispravno:

if ($x) {

    echo "U redu!";

}

Primer mešanja tabova i razmaka (loše):

if ($user) {

→→echo "tabovi nisu dozvoljeni";

}

Ispravno:

if ($user) {

    echo "koristite 4 razmaka";

}

Komentari i dokumentacija

Komentari treba da daju smisleni kontekst, a ne da prepričavaju šta kod radi. Fokus je na objašnjenju zašto nešto postoji.

// Pokušaj pronalaženja korisnika u repozitorijumu

$user = $userRepository->find($id);

/*

 * Ako korisnik ne postoji, bacamo izuzetak

 * jer se radi o nevažećem ID-ju.

 */

if (!$user) {

    throw new NotFoundException();

}

Loš primer:

// Petlja

foreach ($items as $item) {

    echo $item;

}

Ispravno:

// Prikaz svih stavki iz korpe korisnika

foreach ($items as $item) {

    echo $item;

}

Još jedan primer dobrog komentara:

// Proveravamo token jer se sesija resetuje nakon 30 minuta neaktivnosti

if ($token->isExpired()) {

    $session->invalidate();

}

Kako primeniti PSR-12 u PHP projektima

Možete i ručno da pazite na svako pravilo, ali je mnogo efikasnije rešenje je da koristite neke od alata koji automatski proveravaju i formatiraju kod.

U međuvremenu, trudite se da:

• Uvek koristite 4 razmaka za uvlaku.
• Linije neka budu ispod 120 karaktera (idealno do 80).
• Kod neka bude dosledan, organizovan i logično razdvojen praznim linijama.

Alati za pomoć u pridržavanju PSR-12

PHP_CodeSniffer

U pitanju je statički analizator koji proverava vaš PHP kod i prijavljuje odstupanja od PSR-12.
Instalaciju radite pomoću sledećeg koda:

composer require --dev squizlabs/php_codesniffer

Proveru koda radite na sledeći način:

./vendor/bin/phpcs --standard=PSR12 src/

PHP CS Fixer

Alat koji automatski ispravlja stil pisanja tako da bude u skladu sa PSR-12.

Instalacija:

composer require --dev friendsofphp/php-cs-fixer

Automatska korekcija:

./vendor/bin/php-cs-fixer fix src/

PHPStorm

Ako koristite PHPStorm, lako možete podesiti editor da automatski prati PSR-12:
Settings → Editor → Code Style → PHP → Set to PSR-12

Odatle, možete automatski formatirati fajlove po pravilima iz standarda.

Zaključak

Kao što ste videli, PSR-12 nije samo skup pravila o razmacima i zagradama, već standard koji vam pomaže da pišete čitljiviji i održiviji kod. Kada se svi pridržavaju istih pravila, čitanje, testiranje i refaktorisanje koda postaje jednostavnije i brže.

Bez obzira na to da li radite samostalno ili u nekom većem timu, ovaj standard vam omogućava da pišete kod koji je jasan i drugim ljudima, čak i mnogo godina nakon što ste ga napisali.

Zato, ukoliko tek počinjete karijeru PHP programera, naša je preporuka da se od sada pa na dalje, uvek pridržavate PSR-12 standarda.