Zápis jmen
Jedno jméno, tři zápisy: holé, importované příkazem use, nebo s úvodním lomítkem. Sekce
qualification rozhoduje, který z nich se píše pro třídy jiného jmenného prostoru, pro globální třídy,
funkce a konstanty a zvlášť pro funkce a konstanty, které umí optimalizovat kompilátor PHP.
Každý zápis má své slovo a klíče sekce je berou jako hodnotu:
bare: holé jméno,strlen(), které ve jmenném prostoru dosáhne na globální funkci až za běhu,imported: jméno z příkazuuse,use function strlen;a pakstrlen(),backslashed: jméno s úvodním lomítkem,\strlen().
Kde snesete víc zápisů, napíšete seznam: projde každý z nich a jméno, které neodpovídá žádnému, se napíše
podle prvního. Přesně tak to chce standard symfony: globální třídu s lomítkem; globální funkci a konstantu
s lomítkem nebo holou, jen nikdy importovanou; a totéž u funkcí a konstant, které umí optimalizovat kompilátor. Ve
standardu je to pět řádků této sekce a ukázka k nim přidává jen imports.unused:
qualification:
class:
global: backslashed
function:
global: [backslashed, bare]
optimized: [backslashed, bare]
constant:
global: [backslashed, bare]
optimized: [backslashed, bare]
imports:
unused: forbidden
namespace App\Report;
use App\Shop\Order;
use DateTimeImmutable; // The import of `DateTimeImmutable` is unused.
use function sprintf; // Global function `sprintf()` must not be imported.
function stamp(Order $order): string
{
$date = new DateTimeImmutable; // Global class `DateTimeImmutable` must be written with the leading backslash.
return sprintf('%s: %d', $date->format('Y-m-d'), \count($order->items)) . PHP_EOL; // Global function `sprintf()` must be written with the leading backslash.
}
namespace App\Report;
use App\Shop\Order;
function stamp(Order $order): string
{
$date = new \DateTimeImmutable;
return \sprintf('%s: %d', $date->format('Y-m-d'), \count($order->items)) . PHP_EOL;
}
\count() s lomítkem i holé PHP_EOL zůstaly, protože oba zápisy seznam dovoluje. Importované
sprintf() a DateTimeImmutable dostaly lomítko a importy, které tím přestaly být potřeba, zmizely.
Import třídy Order z jiného jmenného prostoru zůstal, protože o něm rozhoduje
class.otherNamespace.
Třídy se přitom chovají jinak než globální funkce a konstanty. Holé jméno třídy, třeba Exception,
znamená ve jmenném prostoru App vždy App\Exception, takže globální třídu holou napsat nejde, jen
importovat nebo kvalifikovat. Holá funkce nebo konstanta naopak dosáhne na globální, když jmenný prostor žádnou stejného
jména nedeklaruje; proč je to pro nástroj nejisté a jak tu nejistotu odstranit, vysvětluje stránka Funkce a konstanty ve jmenných prostorech.
qualification:
class:
otherNamespace: imported
global: backslashed
function:
global: bare
optimized: imported
imports:
unused: forbidden
S touhle konfigurací se třída jiného jmenného prostoru importuje, globální třída dostane lomítko, globální funkce
zůstanou holé a jen ty, které umí optimalizovat kompilátor PHP, se importují. Import, který tím přestane být potřeba,
odebere imports.unused:
namespace App\Model;
use Exception; // The import of `Exception` is unused.
class Cart
{
public function add(array $items, string $name): int
{
if (count($items) > 10 || strlen($name) === 0) { // Global function `count()` must be imported. // Global function `strlen()` must be imported.
throw new Exception('Too many items'); // Global class `Exception` must be written with the leading backslash.
}
$clock = new \App\Util\Clock; // The fully qualified name `\App\Util\Clock` must be imported.
return \array_sum($items); // Global function `array_sum()` must be written without the leading backslash.
}
}
namespace App\Model;
use App\Util\Clock;
use function count;
use function strlen;
class Cart
{
public function add(array $items, string $name): int
{
if (count($items) > 10 || strlen($name) === 0) {
throw new \Exception('Too many items');
}
$clock = new Clock;
return array_sum($items);
}
}
Lomítko, které nic nemění, odstraní qualification.leadingBackslash: v souboru bez jmenného prostoru a
kdekoli před true, false a null. Lomítko na začátku importu má na starosti
imports.leadingBackslash.
Optimalizace kompilátoru
Kompilátor PHP umí volání asi tří desítek funkcí jako strlen(), count() nebo
is_array() nahradit jedinou instrukcí a s hodnotami konstant jako PHP_VERSION_ID počítat dopředu.
Musí ale už při překladu vědět, že jde o globální funkci, tedy jméno importované nebo s lomítkem. Právě o těchto
jménech rozhodují klíče function.optimized a constant.optimized; function.global a
constant.global se jich netýkají. U funkcí rozhodují i argumenty: in_array() kompilátor
optimalizuje jen s polem zapsaným přímo ve volání. Funkce patří klíči function.optimized v celém jmenném
prostoru, když ji tam kód aspoň jednou takhle volá; jinak o ní rozhoduje function.global, protože import,
který nic nezrychlí, je zbytečný. U konstant rozhoduje místo: PHP_VERSION_ID kompilátoru pomůže
v podmínce, ne jako argument funkce. Co přesně PHP dělá a kolik to přinese, popisuje stránka Optimalizace funkcí a konstant.
Každé jméno tak patří právě jednomu klíči. Kde má function.optimized hodnotu keep,
zůstanou optimalizované funkce, jak jsou: samotné function.global: bare vezme lomítko funkci
\array_map(), ale \strlen() a \count() nechá. Kdo chce mít všechny funkce stejně,
napíše hodnotu pro celý druh, function: bare, a ta dopadne na každé místo, které ji bere: global,
optimized i currentNamespace. Totéž platí pro konstanty.
Zápis optimalizovaného volání má ještě jeden důsledek: pojmenované a rozbalené argumenty optimalizaci vypnou. Kde
function.optimized píše funkci importovanou nebo s lomítkem, přepíše DressCode v jejích voláních
pojmenované argumenty na poziční a rozbalený argument ohlásí.
Rizikové opravy
Přepnout holou funkci na importovanou nebo naopak je bezpečné jen tehdy, když jmenný prostor žádnou funkci stejného
jména nedeklaruje. Z jednoho souboru to vidět není, a tak je taková oprava riziková (risky fix) a čeká na svolení, dokud
konfigurace neřekne nameResolution: certain.
S tímto nastavením DressCode ví, co ve vašich jmenných prostorech je, a opravy dělá rovnou.
qualification.class.global
A class of the global namespace referenced in a namespace, DateTime, which a bare name there does not reach.
imported: imported,use DateTime;andDateTimebackslashed: with the leading backslash,\DateTime- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony backslashed, laravel keep · pokrývá
global_namespace_import, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.class.currentNamespace
A class, interface, trait or enum of the namespace of the file, Order in namespace Acme\Shop.
bare: bare,Orderrelative to the namespacebackslashed: with the leading backslash,\Acme\Shop\Order- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
bare, symfony keep, laravel bare · pokrývá
fully_qualified_strict_types, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.class.otherNamespace
A class, interface, trait or enum of a namespace other than that of the file.
A name relative to an import or to the namespace, Shop\Order, stays as it is.
imported: imported,use Acme\Shop\Order;andOrderbackslashed: with the leading backslash,\Acme\Shop\Order- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
imported, symfony keep, laravel imported · pokrývá
fully_qualified_strict_types, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.class.phpdoc
A class, interface, trait or enum a doc comment names in a type, a class constant or the target of a tag.
A name relative to an import or to the namespace, Shop\Order, stays as it is, and so does a bare one no import
reaches, which a doc comment cannot tell from a type of its own such as list.
imported: imported,use Acme\Shop\Order;and@param Order $order, a class of the namespace of the file bare, a global one where the file imports itbackslashed: with the leading backslash,@param \Acme\Shop\Order $order, a name an import reaches- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
imported, symfony keep, laravel imported ·
pokrývá fully_qualified_strict_types
qualification.function.global
A global function called in a namespace, ucfirst(), but one PHP optimizes a call of there, which
function.optimized decides.
Not a function of the namespace of the file, nor a name in a file without a namespace, which
qualification.leadingBackslash decides.
bare: bare,ucfirst()without an import or a backslash, reached by the fallback at run timeimported: imported,use function ucfirst;anducfirst()backslashed: with the leading backslash,\ucfirst()- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony [backslashed, bare], laravel keep · pokrývá
global_namespace_import, native_function_invocation,
SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.function.optimized
A global function whose call PHP compiles to one opcode once it knows the function is global, count(),
strlen(), is_int() and the others; a call of it written imported or with the backslash has its arguments
passed positionally and an unpacked one reported.
A function is optimized in a namespace where one of its calls there is, an unpacked or named argument aside,
in_array() only with a constant array, and every reference to it in that namespace is then written so; one none of
whose calls is optimized is decided by function.global.
imported: imported,use function strlen;, so that the compiler optimizes itbackslashed: with the leading backslash,\strlen(), so that the compiler optimizes itbare: bare,strlen(), forgoing the optimization- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony [backslashed, bare], laravel keep · pokrývá
global_namespace_import, native_function_invocation,
SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalFunctions,
SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly, SlevomatCodingStandard.PHP.OptimizedFunctionsWithoutUnpacking
qualification.function.currentNamespace
A function of the namespace of the file, normalize() in namespace Acme\Text.
bare: bare,normalize()relative to the namespacebackslashed: with the leading backslash,\Acme\Text\normalize()- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony keep, laravel keep ·
pokrývá SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.function.otherNamespace
A function of a namespace other than that of the file.
imported: imported,use function Acme\Text\normalize;andnormalize()backslashed: with the leading backslash,\Acme\Text\normalize()- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony keep, laravel keep ·
pokrývá SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.constant.global
A global constant in a namespace, PHP_EOL, but where the compiler computes with it, which
constant.optimized decides.
bare: bare,PHP_EOLwithout an import or a backslash, reached by the fallback at run timeimported: imported,use const PHP_EOL;andPHP_EOLbackslashed: with the leading backslash,\PHP_EOL- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony [backslashed, bare], laravel keep · pokrývá
global_namespace_import, native_constant_invocation,
SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalConstants, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.constant.optimized
A constant of PHP the compiler computes with once it knows the constant is global, PHP_VERSION_ID in a condition,
PHP_INT_MAX in a constant expression.
A constant merely passed to a call is not one the compiler computes with.
imported: imported,use const PHP_VERSION_ID;, so that the compiler computes with itbackslashed: with the leading backslash,\PHP_VERSION_ID, so that the compiler computes with itbare: bare,PHP_VERSION_ID, forgoing the optimization- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony [backslashed, bare], laravel keep · pokrývá
global_namespace_import, native_constant_invocation,
SlevomatCodingStandard.Namespaces.FullyQualifiedGlobalConstants, SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.constant.currentNamespace
A constant of the namespace of the file, STATUS_PAID in namespace Acme\Shop.
bare: bare,STATUS_PAIDrelative to the namespacebackslashed: with the leading backslash,\Acme\Shop\STATUS_PAID- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony keep, laravel keep ·
pokrývá SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.constant.otherNamespace
A constant of a namespace other than that of the file.
imported: imported,use const Acme\Shop\STATUS_PAID;andSTATUS_PAIDbackslashed: with the leading backslash,\Acme\Shop\STATUS_PAID- seznam těchto slov, kde projde každé a kód, který neodpovídá žádnému, se napíše podle prvního
keep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony keep, laravel keep ·
pokrývá SlevomatCodingStandard.Namespaces.ReferenceUsedNamesOnly
qualification.leadingBackslash
The leading backslash of a name where it changes nothing, in a file without a namespace, \strlen() and
new \DateTime, and before true, false and null anywhere.
forbidden: never therekeep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
forbidden, symfony keep, laravel keep ·
pokrývá PhpCsFixerCustomFixers/no_leading_slash_in_global_namespace
qualification.currentClass
How a class refers to itself in an expression: a static access, an instantiation, an instanceof.
self: the class namedselfinside itselfkeep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
self, symfony keep, laravel keep · pokrývá self_accessor,
SlevomatCodingStandard.Classes.UselessLateStaticBinding, Squiz.Classes.SelfMemberReference
qualification.staticInFinalClass
self for static in a class no subclass can extend, a final class, an anonymous class, an enum:
self::create(), new self.
The return type static stays, saying what a subclass would return.
required: always therekeep: nic se nevynucuje, kód zůstane, jak je
Výchozí keep · standardy: perCs keep, psr12 keep, nette
keep, symfony keep, laravel required · pokrývá
self_static_accessor, SlevomatCodingStandard.Classes.UselessLateStaticBinding