PHP 8.6 vyšlo. DressCode na něj váš kód přepíše. Přechod na novější PHP →

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říkazu use, use function strlen; a pak strlen(),
  • 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; and DateTime
  • backslashed: 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, Order relative to the namespace
  • backslashed: 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; and Order
  • backslashed: 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 it
  • backslashed: 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 time
  • imported: imported, use function ucfirst; and ucfirst()
  • 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 it
  • backslashed: with the leading backslash, \strlen(), so that the compiler optimizes it
  • bare: 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 namespace
  • 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.function.otherNamespace

A function of a namespace other than that of the file.

  • imported: imported, use function Acme\Text\normalize; and normalize()
  • 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_EOL without an import or a backslash, reached by the fallback at run time
  • imported: imported, use const PHP_EOL; and PHP_EOL
  • backslashed: 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 it
  • backslashed: with the leading backslash, \PHP_VERSION_ID, so that the compiler computes with it
  • bare: 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_PAID relative to the namespace
  • backslashed: 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; and STATUS_PAID
  • backslashed: 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 there
  • keep: 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 named self inside itself
  • keep: 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 there
  • keep: 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

Zobrazit na GitHubu · Nahlásit problém se stránkou na GitHubu · 7. 11. 2026