Lekce 3 - Standardy jazyka PHP - PSR-2 část druhá

V minulé lekci, Standardy jazyka PHP - PSR-2 část první, jsme si začali vysvětlovat standard PSR-2, tedy příručku stylem psaní kódu.

Dnes si popíšeme standardy PSR-2, přesněji zápis metod, podmínek, cyklů a uzávěrů.

Metody

Pro metody platí podobná pravidla jako pro vlastnosti.

U všech metod MUSÍ být deklarována viditelnost.

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

Metody NESMÍ být deklarovány s mezerou za názvem metody. Složené závorky MUSÍ být na samostatném řádku. Za levou kulatou závorkou NESMÍ být mezera a stejně tak NESMÍ být mezera ani před pravou.

Deklarace metod vypadá následovně. Všimněte si umístění závorek, čárek a mezer:

<?php
namespace Vendor\Package;

class ClassName
{
    public function fooBarBaz($arg1, &$arg2, $arg3 = [])
    {
        // tělo metody
    }
}

Argumenty metody

V seznamu argumentů metody NESMÍ být před žádnou čárkou mezera a za každou čárkou MUSÍ být mezera.

Argumenty metody s výchozí hodnotou MUSÍ být deklarovány jako poslední.

Deklaraci vidíme na příkladu výše.

Seznam argumentů MŮŽE být rozdělen na více řádek, přičemž je každá jednou odsazena. Pokud tak učiníme, každý argument MUSÍ být na samostatné řádce, včetně prvního.

Argumenty rozdělíme na samostatné řádky pokud by se řádek s deklarací metody nevešel do 80ti znaků.

Při rozdělení deklarace argumentů na více řádek MUSÍ být pravá kulatá závorka a levá složená závorka na jednom řádku a mezi nimi MUSÍ být jedna mezera.

<?php
namespace Vendor\Package;

class ClassName
{
    public function aVeryLongMethodName(
        ClassTypeHint $arg1,
        &$arg2,
        array $arg3 = []
    ) {
        // tělo metody
    }
}

Abstract, final a static

Ukažme si v jakém pořadí zapisovat modifikátory metod.

Pokud použijeme klíčová slova abstract a final, MUSÍ být uvedeny před deklarací viditelnosti.

Pokud použijeme klíčové slovo static, MUSÍ být uvedeno za deklarací viditelnosti.

<?php
namespace Vendor\Package;

abstract class ClassName
{
    protected static $foo;

    abstract protected function zim();

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

Volání metod a funkcí

Při volání metod NESMÍ za názvem metody nebo funkce následovat mezera. Mezera NESMÍ být ani kolem kulatých závorek. V seznamu argumentů NESMÍ být mezera před čárkami a za nimi MUSÍ být jedna mezera.

<?php
bar();
$foo->bar($arg1);
Foo::bar($arg2, $arg3);

S rozdělením argumentů na více řádek je to stejné jako při deklaraci metod:

Seznam argumentů MŮŽE BÝT rozdělen do více řádek, kdy každou řádku jednou odsadíme. Pokud tak učiníme, každý argument MUSÍ být na samostatném řádku včetně prvního.

<?php
$foo->bar(
    $longArgument,
    $longerArgument,
    $muchLongerArgument
);

Řídící struktury

Základní pravidla pro řídící struktury jsou následující:

Za klíčovým slovem řídící struktury MUSÍ následovat mezera.

Za levou kulatou závorkou a před pravou kulatou závorkou NESMÍ být mezera.

Mezi pravou kulatou závorkou a levou složenou závorkou MUSÍ být mezera.

Tělo struktury MUSÍ být jednou odsazeno.

Pravá složená závorka MUSÍ být na samostatném řádku za tělem struktury.

Tělo každé struktury MUSÍ být obsaženo ve složených závorkách.

Zajímavá je poslední poučka. Např. tělo podmínky i s jediným příkazem tedy musíme vkládat do složených závorek:

if ($promenna) {
    echo('Platí');
}

Důvodem je, aby se předešlo chybám při přidání dalších příkazů do těla podmínky.

if, elseif a else

Sekvence if... elseif... else by tedy měla vypadat následovně. Všimněte si umístění závorek a mezer. A také toho, že else a elseif jsou na stejné řádce jako pravá složená závorka.

<?php
if ($expr1) {
    // tělo podmínky
} elseif ($expr2) {
    // tělo elseif
} else {
    // tělo else
}

Místo dvou slov else if bychom MĚLI použít klíčové slovo elseif, aby byla všechna řídící klíčová slova tvořena právě jedním slovem.

switch a case

Uveďme si jak vypadá struktura switch. Opět si všimněte závorek a mezer.

Příkaz case MUSÍ být uvnitř jednou odsazen. Klíčové slovo break (nebo jiné ukončující slovo) MUSÍ být odsazeno stejně, jako tělo case. Pokud mezi case záměrně používáme propadávání (vynecháme break), MUSÍME to zdůraznit komentářem.

<?php
switch ($expr) {
    case 0:
        echo 'První případ s break';
        break;
    case 1:
        echo 'Druhý případ, který propadne';
        // chybí break
    case 2:
    case 3:
    case 4:
        echo 'Třetí případ obsahuje return místo break';
        return;
    default:
        echo 'Výchozí případ';
        break;
}

Opomenutí break je častěji chybou než záměrem a proto bychom do kódu měli uvést, že jsme ho opomenuli záměrně.

while a do while

Cyklus while zapisujeme takto:

<?php
while ($expr) {
    // tělo struktury
}

Podobně vypadá i konstrukce do while:

<?php
do {
    // structure body;
} while ($expr);

for

For cyklus zapíšeme podobně:

<?php
for ($i = 0; $i < 10; $i++) {
    // tělo cyklu
}

foreach

<?php
foreach ($iterable as $key => $value) {
    // tělo cyklu
}

Bloky try a catch

Podoba bloků try a catch je následující:

<?php
try {
    // tělo try
} catch (FirstExceptionType $e) {
    // tělo catch
} catch (OtherExceptionType $e) {
    // tělo catch
}

Uzávěry (closures)

Zbytek specifikace popisuje jak deklarovat tzv. closures (česky uzávěry). Jsou to anonymní funkce, které můžeme deklarovat kdekoli v kódu a uložit je např. do proměnných nebo je předat jako argument metodě.

Uzávěry MUSÍ být deklarované s mezerou za klíčovým slovem function a s mezerou před a za klíčovým slovem use.

Levá složená závorka MUSÍ být na stejném řádku jako deklarace closure. Pravá MUSÍ být na samostatném řádku.

Okolo kulatých závorek s argumenty NESMÍ být mezery.

V seznamu argumentů NESMÍ být mezera před žádnou čárkou a za všemi čárkami MUSÍ být mezery.

Argumenty s výchozí hodnotou MUSÍME zapsat jako poslední.

Deklarace uzávěru vypadá takto:

<?php
$closureWithArgs = function ($arg1, $arg2) {
    // tělo
};

$closureWithArgsAndVars = function ($arg1, $arg2) use ($var1, $var2) {
    // tělo
};

Seznam argumentů a proměnných MŮŽEME rozdělit na několik řádek, kdy každou jednou odsadíme. Pokud tak učiníme, každá položka MUSÍ být na samostatné řádce včetně té první.

Pokud je seznam (argumentů nebo proměnných) rozdělen na více řádek, MUSÍ být pravá kulatá závorka a levá složená závorka na stejném řádku s jednou mezerou mezi nimi.

Následují ukázky uzávěrů s/bez argumentů/pro­měnných a se seznamem rozděleným na více řádek.

<?php
$longArgs_noVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) {
   // tělo
};

$noArgs_longVars = function () use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // tělo
};

$longArgs_longVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // tělo
};

$longArgs_shortVars = function (
    $longArgument,
    $longerArgument,
    $muchLongerArgument
) use ($var1) {
   // tělo
};

$shortArgs_longVars = function ($arg) use (
    $longVar1,
    $longerVar2,
    $muchLongerVar3
) {
   // tělo
};

Pravidel se držíme i v případě, kdy se uzávěr používá přímo ve volání funkce nebo metody jako argument:

<?php
$foo->bar(
    $arg1,
    function ($arg2) use ($var1) {
        // tělo
    },
    $arg3
);

V příští lekci, Standardy jazyka PHP - PSR-3 a specifikace loggeru, se zaměříme na PSR-3, která se věnuje logování.