2. diel - Štandardy jazyka PHP - PSR-2 časť prvá

V minulej lekcii, Štandardy jazyka PHP - Úvod a PSR-1 , sme si uviedli štandard PSR-1, ktorý definoval ako vytvárať PHP súbory a ako pomenovávať triedny prvky. V dnešnom tutoriálu sa zameriame na štandard PSR-2.

PSR-2 rozširuje PSR-1 a predpisuje ďalšie konvencie pre písanie PHP kódu. Tento štandard nesie názov Príručka štýlu písania kódu (Coding Style Guide). Rovnako ako minulý štandard vznikol zhodou autorov niekoľkých veľkých (naozaj veľkých) PHP projektov.

Všeobecné

Štandard popisuje štýl písania kódu. Trieda by mala vyzerať asi takto:

<?php
namespace Vendor\Package;

use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class Foo extends Bar implements FooInterface
{
    public function sampleFunction($a, $b = null)
    {
        if ($a === $b) {
            bar();
        } elseif ($a > $b) {
            $foo->bar($arg1);
        } else {
            BazClass::bar($arg2, $arg3);
        }
    }

    final public static function bar()
    {
        // tělo metody
    }
}

Základný štandard

Kód MUSÍ spĺňať základný štandard PSR-1.

Súbory

Všetky súbory MUSÍ zakončovať riadky znakom Unix LF.

Rôzne konce riadkov môžu na serveri vyvolať obrovské problémy. A to najmä keď je server nastavený na iné konce riadkov, než súbory na ňom uložené. Ak sa napr. Rozbije odriadkovanie za komentárom //, zakomentuje hneď niekoľko riadku po sebe. Sofistikované nástroje pre upload súborov na FTP konce riadkov prevádzajú podľa serveru (napr. ITnetwork beží na MACu). Pretože je väčšina serverov Linuxových, prikazuje štandard používať všade jednotný znak (LF je \ n, ASCII kód 10).

Všetky PHP súbory MUSÍ končiť prázdnym riadkom.

Zakončiť každý riadok znakom LF (aj ten posledný) je dobrá praktika nielen u zdrojových súborov, vyhneme sa tak napr. Problémom pri ich spájaní.

Ukončovacie tag?> MUSÍ byť vypustený u súborov, ktoré obsahujú iba PHP kód.

Ak deklarujeme triedu, vyzerá jej súbor iba takto:

<?php
namespace Vendor\Foo;

class Foo
{

}

Ak PHP direktívu neukončíme, platí do konca súboru. Ukončovať ju pri súboroch s deklaráciou je zlá praktika, keďže sa nám medzi?> A koniec súboru môžu votrieť ďalšie znaky a tie by potom mohli pri načítaní (require / include) vyvolať HTML výstup a odoslanie hlavičiek. To by zamedzilo napr. Použitie funkcie header ().

Riadky

Na dĺžku riadku NESMIE byť žiadny pevný limit.

Na dĺžku riadku MUSÍ byť voľný limit (soft limit) 120 znakov.

Voľný limit je dĺžka riadku, ktorej prekročenie vyvolá upozornenie, ale nijako neovplyvní beh aplikácie.

Riadky by NEMALI byť dlhšie ako 80 znakov. Dlhšie riadky by MALI byť rozdelené do viacerých riadkov, kratších ako 80 znakov.

Pozn. 80 znakov je šírka obrazovky v predvolenom textovom režime.

Na konci neprázdnych riadka NESMIE byť medzera.

Za účelom zvýšenia čitateľnosti MÔŽU byť pridané prázdne riadky.

Na riadku NESMIE byť viac ako jeden príkaz.

Odsadzovanie

Kód MUSÍ používať pre odsadenie 4 medzery a NESMIE používať tabulátory.

Medzery sú na rozdiel od tabulátorov univerzálne a nezáleží na nastavenie editora. Tabulátory často mätú verzovacie nástroje, Diff a ďalšie podobné aplikácie.

Kľúčové slová a true / false, null

Kľúčové slová PHP MUSÍ byť malými písmenami.

Konštanty true, false a null MUSÍ byť malými písmenami.

Menné priestory a deklarácie use

Ak je uvedený menný priestor, MUSÍ byť za namespace prázdna riadok.

Všetky use deklarácia MUSÍ nasledovať za deklaráciou namespace.

Každá deklarácia MUSÍ obsahovať práve jedno kľúčové slovo use.

Za blokom use MUSÍ byť prázdna riadok.

Príklad zo štandardu:

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

// další PHP kód

Triedy, vlastnosti a metódy

Termín trieda bude opäť referovať nielen na triedy, ale aj na rozhraní a Traits.

Extends a Implements

Kľúčové slová Extends a Implements MUSÍ byť deklarovaná na rovnakom riadku, ako trieda.

Ľavá zložená zátvorka za class MUSÍ byť na samostatnom riadku. Pravá zložená zátvorka MUSÍ byť tiež na samostatnom riadku po tele triedy.

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements \ArrayAccess, \Countable
{
    // konstanty, vlastnosti, metody
}

Zoznam rozhranie k implementácii MÔŽE byť rozdelený na viac riadkov, riadky potom raz odsadíme. Ak tak urobíme, každé rozhranie MUSÍ byť na samostatnom riadku vrátane prvého.

<?php
namespace Vendor\Package;

use FooClass;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;

class ClassName extends ParentClass implements
    \ArrayAccess,
    \Countable,
    \Serializable
{
    // konstanty, vlastnosti, metody
}

Vlastnosti

U všetkých vlastností MUSÍ byť deklarovaná viditeľnosť (modifikátor prístupu).

Každý jazyk má ako predvolený iný modifikátor. Vlastnosť bez modifikátora je napr. V Jave private, ale v PHP public, kvôli spätnej kompatibilite s PHP 4. Je vždy istejšie explicitne uviesť kedy má byť metóda prístupná.

K deklarácii vlastností NESMIETE použiť kľúčové slovo var.

Var je pozostatok z PHP 4 a aj keď sa bohužiaľ objavuje v niektorých "moderných" učebniciach programovania, mali by sme na neho zabudnúť.

Jeden príkaz NESMIE deklarovať viac ako jednu vlastnosť.

Hoci teoreticky môžeme deklarovať niekoľko vlastností týmto štýlom:

public $a, $b, $c;

Znemožníme tým dokumentáciu vlastností.

Názvy privátnych a chránených vlastností by NEMALI byť predsadené podčiarknikom.

Za čias starých a dávnych, kedy jazyky ešte nevedeli modifikátory prístupu, sa používala konvencie _vlastnost. Táto vlastnosť bola chápaná ako privátne. Tieto tendencie občas zbadáme u niektorých autorov aj u moderných jazykov, kde však nemajú žiadny zmysel.

Deklarácia vlastností by teda mala vyzerať nasledovne:

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

Nabudúce budeme v lekcii Štandardy jazyka PHP - PSR-2 časť druhá pokračovať so zápisom metód, kontrolných štruktúr a uzáverov.