Lekce 2 - Standardy jazyka PHP - PSR-2 část první

V minulé lekci, Standardy jazyka PHP - Úvod a PSR-1, jsme si uvedli standard PSR-1, který definoval jak vytvářet PHP soubory a jak pojmenovávat třídní prvky.

V dnešním tutoriálu se zaměříme na standard PSR-2.

PSR-2 rozšiřuje PSR-1 a předepisuje další konvence pro psaní PHP kódu. Tento standard nese název Příručka stylu psaní kódu (Coding Style Guide). Stejně jako minulý standard vznikl shodou autorů několika velkých (opravdu velkých) PHP projektů.

Standard PSR-2 byl v roce 2019 označen jako zastaralý. Jeho místo zaujímá standard PSR-12 a také ho rozšiřuje.

Obecné

Standard popisuje styl psaní kódu. Třída by měla vypadat 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í standard

Kód MUSÍ splňovat základní standard PSR-1.

Soubory

Všechny soubory MUSÍ zakončovat řádky znakem Unix LF.

Různé konce řádků mohou na serveru vyvolat obrovské problémy. A to zejména když je server nastavený na jiné konce řádků, než soubory na něm uložené. Pokud se např. rozbije odřádkování za komentářem //, zakomentuje hned několik řádku po sobě. Sofistikované nástroje pro upload souborů na FTP konce řádků převádějí podle serveru (např. ITnetwork běží na MACu). Protože je většina serverů Linuxových, přikazuje standard používat všude jednotný znak (LF je \n, ASCII kód 10).

Všechny PHP soubory MUSÍ končit prázdným řádkem.

Zakončit každý řádek znakem LF (i ten poslední) je dobrá praktika nejen u zdrojových souborů, vyhneme se tak např. problémům při jejich spojování.

Ukončovací tag ?> MUSÍ být vypuštěn u souborů, které obsahují pouze PHP kód.

Pokud deklarujeme třídu, vypadá její soubor pouze takto:

<?php
namespace Vendor\Foo;

class Foo
{

}

Pokud PHP direktivu neukončíme, platí do konce souboru. Ukončovat ji u souborů s deklarací je špatná praktika, jelikož se nám mezi ?> a konec souboru mohou vloudit další znaky a ty by potom mohly při načtení (require/include) vyvolat HTML výstup a odeslání hlaviček. To by zamezilo např. použití funkce header().

Řádky

Na délku řádku NESMÍ být žádný pevný limit.

Na délku řádku MUSÍ být volný limit (soft limit) 120 znaků.

Volný limit je délka řádku, jejíž překročení vyvolá upozornění, ale nijak neovlivní běh aplikace.

Řádky by NEMĚLY být delší než 80 znaků. Delší řádky by MĚLY být rozdělené do více řádek, kratších než 80 znaků.

Pozn. 80 znaků je šířka obrazovky ve výchozím textovém režimu.

Na konci neprázdných řádku NESMÍ být mezera.

Za účelem zvýšení čitelnosti MOHOU být přidány prázdné řádky.

Na řádce NESMÍ být více než jeden příkaz.

Odsazování

Kód MUSÍ používat pro odsazení 4 mezery a NESMÍ používat tabulátory.

Mezery jsou na rozdíl od tabulátorů univerzální a nezáleží na nastavení editoru. Tabulátory často matou verzovací nástroje, diffy a další podobné aplikace.

Klíčová slova a true/ false, null

Klíčová slova PHP MUSÍ být malými písmeny.

Konstanty true, false a null MUSÍ být malými písmeny.

Jmenné prostory a deklarace use

Pokud je uveden jmenný prostor, MUSÍ být za namespace prázdná řádka.

Všechny use deklarace MUSÍ následovat za deklarací namespace.

Každá deklarace MUSÍ obsahovat právě jedno klíčové slovo use.

Za blokem use MUSÍ být prázdná řádka.

Příklad ze standardu:

<?php
namespace Vendor\Package;

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

// další PHP kód

Třídy, vlastnosti a metody

Termín třída bude opět referovat nejen na třídy, ale i na rozhraní a traits.

Extends a Implements

Klíčová slova extends a implements MUSÍ být deklarovaná na stejné řádce, jako třída.

Levá složená závorka za class MUSÍ být na samostatném řádku. Pravá složená závorka MUSÍ být také na samostatném řádku po těle třídy.

<?php
namespace Vendor\Package;

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

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

Seznam rozhraní k implementaci MŮŽE být rozdělen na více řádek, řádky poté jednou odsadíme. Pokud tak učiníme, každé rozhraní MUSÍ být na samostatném řádku včetně první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šech vlastností MUSÍ být deklarována viditelnost (modifikátor přístupu).

Každý jazyk má jako výchozí jiný modifikátor. Vlastnost bez modifikátoru je např. v Javě private, ale v PHP public, kvůli zpětné kompatibilitě s PHP 4. Je vždy jistější explicitně uvést kdy má být metoda přístupná.

K deklaraci vlastností NESMÍTE použít klíčové slovo var.

Var je pozůstatek z PHP 4 a i když se bohužel objevuje v některých "moderních" učebnicích programování, měli bychom na něj zapomenout.

Jeden příkaz NESMÍ deklarovat více než jednu vlastnost.

Ačkoli teoreticky můžeme deklarovat několik vlastností tímto stylem:

public $a, $b, $c;

Znemožníme tím dokumentaci vlastností.

Názvy privátních a chráněných vlastností by NEMĚLY být předsazeny podtržítkem.

Za dob starých a dávných, kdy jazyky ještě neuměly modifikátory přístupu, se používala konvence _vlastnost. Tato vlastnost byla chápána jako privátní. Tyto tendence občas spatříme u některých autorů i u moderních jazyků, kde však nemají žádný smysl.

Deklarace vlastností by tedy měla vypadat následujícím způsobem:

<?php
namespace Vendor\Package;

class ClassName
{
    public $foo = null;
}

Příště budeme v lekci Standardy jazyka PHP - PSR-2 část druhá se budeme zabývat zápisem metod, kontrolních struktur a uzávěrů.