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

Funkce a konstanty ve jmenných prostorech

Nekvalifikované volání strlen() uvnitř jmenného prostoru (namespace) může v PHP znamenat dvě zcela různé funkce a ze samotného kódu jednoho souboru nelze poznat, o kterou z nich jde. Nástroje pro kontrolu stylu proto u celé řady užitečných oprav pouze hádají. Obvykle přitom stačí jediný řádek v konfiguraci, kterým DressCode řeknete, jaké funkce a konstanty ve jmenných prostorech máte, a opravy rázem přestanou být rizikové. Jistá jména navíc otevírají cestu k rychlejšímu volání funkcí.

Jedno jméno, dva významy

Podívejte se na následující kód:

namespace App;

if (is_null($user)) {
	// ...
}

Která funkce se zde ve skutečnosti volá? Většina vývojářů automaticky předpokládá globální is_null(), kterou zná každý. Jenže PHP o tom rozhoduje až za běhu: nejprve ověří, zda náhodou neexistuje funkce App\is_null(), a teprve když ji nenajde, sáhne po té globální. Bohatě stačí, aby kdekoliv v projektu jiný soubor deklaroval:

namespace App;

function is_null(mixed $value): bool
{
	return $value === null || $value === '';
}

a volání výše najednou provádí něco docela jiného. Na souboru, v němž je volání zapsáno, přitom vůbec nezáleží, rozhoduje výhradně to, zda byl načten i onen druhý soubor.

Naprosto stejně se chovají konstanty: zápis PHP_EOL ve jmenném prostoru App představuje App\PHP_EOL, pokud existuje, a teprve v opačném případě globální PHP_EOL. U tříd tohle PHP nedělá: nekvalifikovaná Exception ve jmenném prostoru App znamená vždy nekompromisně App\Exception a globální třídu musíte zapsat jako \Exception nebo ji importovat přes use.

Proč PHP zachází s funkcemi jinak než s třídami? Když jmenné prostory přišly v PHP 5.3, dostaly třídy a funkce odlišné řešení. U tříd by návrat ke globálnímu jménu ve spojení s autoloadingem znamenal propad výkonu, protože každé new Exception by nejprve zkoušelo načíst soubor pro App\Exception. Funkce a konstanty autoloading nemají, a tak dostaly tichý fallback na globální prostor, aby kód psaný před érou jmenných prostorů mohl do jmenného prostoru přejít bez lomítka před každým strlen(). Byl to pragmatický kompromis své doby; jeho daní je, že o významu nekvalifikovaného volání funkce nerozhoduje obsah souboru, ale stav celého běžícího programu.

Proč to pálí nástroje

Nástroje pro kontrolu stylu pracují s jednotlivými soubory, nikoliv s běžícím procesem. U každého is_null($x) uvnitř jmenného prostoru proto stojí před stejnou hádankou jako vy a odpověď s jistotou neznají. Celá řada užitečných oprav přitom přímo stojí na předpokladu, že jde o známou vestavěnou funkci PHP:

  • přepis is_null($x) na $x === null,
  • intval($x) na přetypování (int) $x,
  • sizeof($a) na count($a),
  • dirname(__FILE__) na konstantu __DIR__,
  • get_class() na self::class,
  • doplnění use function count;, aby kompilátor mohl volání optimalizovat.

Kdyby šlo o vaši vlastní funkci App\is_null(), každá z těchto úprav by skrytě změnila chování programu. Zodpovědný nástroj proto musí takové zásahy klasifikovat jako rizikové opravy (risky fixes) a bez výslovného svolení se do nich nepouštět. PHP CS Fixer má mezi rizikovými pravidly například is_null, no_alias_functions nebo dir_constant, všechna se shodným varováním: jsou riziková, pokud je funkce předefinovaná.

A nejde o pouhou teoretickou hrozbu. Přesně na tomto mechanismu stojí osvědčený trik v unit testech: testovací knihovny typu php-mock deklarují přímo v testu funkci App\time() nebo App\file_get_contents(), aby testovaný kód ve jmenném prostoru App namísto skutečné funkce použil podvrženou mock funkci.

Buďme pragmatičtí

Kolik vlastních funkcí a konstant ve jmenných prostorech reálně máte? Téměř jistě jen naprosté minimum, v mnoha projektech dokonce čistou nulu. Funkce se v PHP totiž neautoloadují: aby bylo možné funkci zavolat, musí někdo její soubor předem načíst přes require nebo záznamem files v composer.json. Z toho důvodu se kód před lety definitivně přesunul do tříd a funkce ve jmenných prostorech zůstaly okrajovou záležitostí. Autoloading funkcí byl v komunitě PHP navrhován opakovaně, součástí jazyka se však dosud nestal.

To je současně skvělý důvod, proč na nekvalifikované volání funkcí z vlastního jmenného prostoru raději vůbec nespoléhat: když se soubor s funkcí shodou okolností nenačte, PHP neohlásí chybu, ale potichu zavolá globální funkci stejného jména (pokud existuje). Explicitní import use function App\is_null; soubor sice také nenačte, ale volání v takovém případě okamžitě a srozumitelně selže na Call to undefined function App\is_null().

Situace je tedy přehledná: teoretická nejistota komplikuje život všem, ale skutečné funkce ve jmenných prostorech jsou vzácností. Stačí je jen vyjmenovat.

Řekněte DressCode, co je co

Nejčastěji žádné vlastní funkce ani konstanty ve jmenných prostorech nedeklarujete. Pak vám v konfiguraci stačí jediný řádek:

nameResolution: certain

Tímto zápisem DressCode potvrdíte, že každé nekvalifikované jméno funkce či konstanty, které daný soubor neimportuje ani sám nedeklaruje, je zaručeně globální. Nikoli „s velkou pravděpodobností“, ale naprosto jistě.

Pokud nějaké vlastní funkce či konstanty ve jmenných prostorech přece jen máte, jednoduše je vyjmenujete v klíči namespaces: funkce pod functions a konstanty pod constants. Zápis je shodný se syntaxí příkazu use, včetně skupinových závorek. Položku se složenou závorkou uveďte v uvozovkách, aby ji parser NEONu nepovažoval za mapu:

nameResolution: certain

namespaces:
	functions:
		- 'App\Utils\{format, parse}'
		- App\Legacy\helper
	constants:
		- 'App\{VERSION, DEBUG}'

Funkci uvedenou v tomto seznamu pak DressCode považuje za funkci daného jmenného prostoru všude tam, kde se v něm volá bez importu. U funkcí nezáleží na velikosti písmen vůbec, u konstant záleží na velikosti písmen pouze v jejich vlastním názvu (v názvu jmenného prostoru nikoliv), přesně podle chování samotného PHP.

Seznamy a nameResolution představují dvě odlišné věci, a proto má každá vlastní klíč. Seznam deklaruje fakt: tato funkce v projektu existuje. nameResolution představuje rozhodnutí: ve jmenných prostorech neexistuje nic dalšího.

nameResolution co znamená
certain uvedené seznamy jsou úplné; cokoliv v nich nefiguruje, je zaručeně globální
uncertain seznamy nemusí být kompletní; chová se stejně, jako když klíč v konfiguraci chybí

Při nastavení uncertain postupuje DressCode velmi opatrně: nekvalifikované jméno sice vnímá jako globální, ale jakoukoliv navazující opravu považuje za rizikovou. Oznámí ji jako varování s přesným odůvodněním na řádku pod porušením (například the namespace may declare `is_null()`) a kód reálně upraví teprve tehdy, když rozhodnutí povolíte v fixRisky nebo spustíte fix --fix-risky. Proto je uncertain výchozí hodnotou: samotná přítomnost rozhodnutí v konfiguraci ještě neznamená automatický souhlas se zásahy do logiky. Jakmile však nastavíte certain, tyto opravy okamžitě přestanou být rizikové.

Každé pravidlo z toho těží

Zásadní je, kde se tato informace uplatňuje. DressCode ji nepředává jednotlivým pravidlům izolovaně, ale poskytuje ji centrální analýze NameResolver, která překládá názvy napříč celým nástrojem. Ptají se jí vestavěná pravidla a stejně tak se jí dotazuje vaše vlastní pravidlo. Znalost leží na jediném místě a žádné pravidlo si nemusí vést vlastní seznam výjimek.

Funguje to spolehlivě i v opačném směru, kdy pravidlo samo vkládá název funkce do kódu. Rozhodnutí hygiene.aliasFunctions přepisuje sizeof() na count() a nový název zapíše ve stejném tvaru jako původní: \sizeof() převede na \count(), holé sizeof() na holé count(). Pokud však daný soubor importuje či deklaruje vlastní funkci count, nebo pokud její deklaraci ve jmenném prostoru uvádí konfigurace, zapíše raději \count(), aby opravený kód zaručeně volal stejnou funkci jako předtím.

Všechna pravidla tak čtou jména naprosto shodně a výsledek nezávisí na tom, které pravidlo se ptá.

Nová funkce neproklouzne

Statický seznam by byl k ničemu, kdyby v čase zastaral. Proto jej hlídá samotný DressCode: jakmile konfigurace obsahuje nameResolution: certain, aktivuje se interní kontrola pod cestou namespaces.functions a namespaces.constants. Pokud v kontrolovaném kódu objeví novou funkci deklarovanou ve jmenném prostoru, která v seznamu chybí, okamžitě na ni upozorní (totéž platí pro const i pro volání define('App\X', ...)). Počítá přitom i s deklaracemi uvnitř podmínek, třeba s polyfillem v if (!function_exists(...)). Jakmile kdokoliv do projektu přidá například funkci App\Utils\slugify(), příkaz dresscode check vás ihned vyzve k jejímu doplnění do konfigurace:

src/Utils/helpers.php
  error  12:10  Function `App\Utils\slugify()` must be listed in `namespaces.functions`.  namespaces.functions

Tento mechanismus stačí, protože deklaraci lze na rozdíl od volání odhalit přímo: nachází se v souborech, které DressCode prochází. Pozor si dejte pouze na cesty vyloučené z kontroly. Pokud funkci deklarujete například ve složce testů, kterou DressCode nekontroluje, a kód ji volá bez importu, zapište ji do seznamu ručně. Při nastavení uncertain je tento hlídač neaktivní, protože není co ověřovat. S certain jej nevypne ani přepínač --only: opravy závisející na úplnosti seznamu nesmí přijít o kontrolu, která tuto úplnost garantuje.

Ani úvodní seznam nemusíte sepisovat ručně. Příkaz dresscode init automaticky projde všechny soubory v cestách projektu, detekuje všechny funkce i konstanty deklarované ve jmenných prostorech a zapíše jejich seznamy rovnou s nameResolution: certain. Pokud by některý soubor nešlo naparsovat (takže by nebylo jisté, co deklaruje), init nameResolution: certain nezapíše a v komentáři problematický soubor výslovně jmenuje. Jména jednoho jmenného prostoru zapíše jako skupinu, každý jmenný prostor na jeden řádek ('Acme\Shop\{formatPrice, parsePrice}'), a nové jméno pak dopíšete do kterékoli skupiny, nebo jako samostatnou položku celým jménem.

Pomocné funkce v testech

Testy si často deklarují pomocné funkce přímo ve svém testovacím jmenném prostoru, například App\Tests\createUser(). Zapisovat je do globální konfigurace a hlídat jejich seznam by bylo zbytečně otravné. Pro testovací složku proto stačí vytvořit lokální přepis konfigurace, který určí, že v této části projektu seznamy kompletní nejsou:

nameResolution: certain

overrides:
	- paths: [tests]
	  nameResolution: uncertain

Soubory ve složce tests pak DressCode posuzuje obezřetně: opravy vyžadující globální funkci se v nich pouze nahlásí jako riziková varování a hlídač nevyjmenovaných deklarací zde mlčí. Produkční kód v src přitom dál naplno těží z jistoty. Funguje to spolehlivě proto, že kód v src pomocné funkce z testů nikdy nevolá, takže na význam jmen v produkčním kódu nemají žádný vliv.

Jedna výjimka však stojí za pozornost: zmíněný trik s mockováním funkcí v testech (viz výše). Pokud test deklaruje funkci App\time(), aby produkční kód ve jmenném prostoru App zavolal mock, týká se tato změna chování volání v src, nikoliv v testech. Taková funkce proto do projektového seznamu namespaces.functions rozhodně patří, aby ji pravidla v src nechala netknutou.

Funkce, které deklaruje framework

Někdy píšete kód přímo do jmenného prostoru frameworku, protože vás k tomu jeho architektura přímo vybízí. Typickým příkladem je Symfony, které konfiguraci služeb směřuje do souborů začínajících namespace Symfony\Component\DependencyInjection\Loader\Configurator;, a to právě proto, abyste mohli volat pomocné funkce service(), param() nebo env() přímo bez otravných importů. Tyto funkce však deklaruje samotné Symfony uvnitř složky vendor, kam DressCode běžně nenahlíží.

O těchto specifických funkcích DressCode ví automaticky: jakmile má projekt nainstalovaný balíček symfony/dependency-injection, přidá tyto funkce do seznamu namespaces.functions zcela sám, bez jediného řádku konfigurace a při použití libovolného standardu. Ve výpisu dresscode config je najdete pod řádkem Names, každou s označením původu DressCode for symfony/dependency-injection.

Jiné balíčky mohou vlastní seznamy dodat prostřednictvím klíče namespaces ve svých souborech dat, které se přirozeně sloučí s vaší konfigurací. Samotný klíč nameResolution však žádný balíček ani preset nastavit nemůže: znají totiž framework, ale neznají váš vlastní kód.

Jak se píšou globální jména

Způsob zápisu globálních funkcí a konstant řídí konfigurační sekce qualification. Každé jméno lze zapsat třemi způsoby a hodnotou každého klíče je název jednoho z nich: bare představuje holé jméno spoléhající na runtime fallback PHP, imported vyžaduje import přes use function či use const a backslashed vynucuje zápis s úvodním zpětným lomítkem.

qualification:
	function:
		global: bare
		optimized: imported
	constant:
		global: bare
		optimized: imported

S touto konfigurací zůstanou běžné globální funkce a konstanty holé a pouze ty, které kompilátor PHP dokáže reálně zrychlit, získají import:

namespace App;

use function count;
use function in_array;

Na první pohled by se to mohlo zdát zbytečné, vždyť count() funguje i bez importu. Důvodem je však čistý výkon: díky importu kompilátor okamžitě ví, že volá globální funkci, a použije svou optimalizovanou instrukci (jak rozebírá stránka Rychlejší volání funkcí v PHP).

S hodnotou optimized: imported se hlavička souboru může snadno natáhnout do dlouhého sloupce řádků use function. Elegantně ji zkrátí rozhodnutí imports.grouping.function: combined, které sloučí importy funkcí do jediného příkazu: use function count, in_array, strlen;. Méně řádků znamená i méně tokenů: AI agent, který čte začátek souboru, se dříve dostane k podstatnému kódu a nemusí se prokousávat hradbou importů. Standard nette je zapisuje přesně tímto způsobem.

Jednotlivé klíče postupují od obecných ke konkrétním:

klíč o jakých jménech rozhoduje
function.global, constant.global o běžných globálních funkcích a konstantách ve jmenném prostoru (mimo ty, které spadají pod klíče optimized)
function.optimized o funkcích, se kterými kompilátor zachází zvlášť, a to na místech, kde volání s danými argumenty skutečně zrychlí
constant.optimized o konstantách, s nimiž kompilátor aktivně počítá: v podmínkách či konstantních výrazech
function.currentNamespace, constant.currentNamespace o funkcích a konstantách vlastního jmenného prostoru daného souboru

Rozhodnutí function.optimized se u části funkcí řídí konkrétními argumenty: strlen() optimalizuje PHP vždy, ale dirname(), defined() či function_exists() pouze s konstantním argumentem; sprintf() jen s konstantním formátem obsahujícím výhradně %s a %d v počtu odpovídajícím předaným hodnotám; a in_array() pouze s polem zapsaným přímo v kódu. Funkce se kvalifikuje ve chvíli, kdy ji daný jmenný prostor alespoň jednou zavolá tímto optimalizovatelným způsobem a od té chvíle se tak v daném jmenném prostoru zapisuje každé její použití. O funkci, která není takto volána nikde, rozhoduje obecný klíč function.global, protože import bez výkonnostního přínosu by byl v kódu zbytečným vizuálním šumem. Klíč constant.optimized se zase neřídí názvem konstanty, ale kontextem jejího použití. Hodnota bare u těchto klíčů znamená, že projekt dává přednost čistotě holého zápisu před kompilátorovou optimalizací. Každé jméno spadá pod jediný klíč: pokud je function.optimized nastaveno na keep, zůstanou optimalizované funkce beze změny, a samotné function.global: bare odstraní lomítko z \array_map(), ale volání \strlen() a \count() nechá na pokoji.

Import zapíše DressCode přesně v tom stylu, jakým soubor importy už zapisuje: začlení jej do vícepoložkového příkazu, do existujícího skupinového importu pro daný jmenný prostor a na přesné abecední místo, takže navazující rozhodnutí ze sekce imports nemají důvod cokoliv namítat. Pokud soubor funkci už importuje pod aliasem, použije tento alias. Kde import přidat nelze (například proto, že je název v souboru kolizní), zapíše úvodní lomítko. Holé jméno naopak zapíše pouze tam, kde skutečně odkazuje na globální funkci, a nepoužívané importy automaticky odstraní.

A tím se vracíme ke jmenným prostorům. Import use function strlen; volání pevně sváže s globální funkcí. Kdyby projekt obsahoval vlastní App\strlen(), import by změnil chování programu. Při nastavení uncertain proto DressCode každý přechod mezi holým jménem a importem či lomítkem považuje za rizikový. S certain naopak s jistotou ví, že App\strlen() neexistuje, a import bezpečně doplní. Funkci uvedenou v seznamu namespaces.functions samozřejmě nikdy neimportuje.

Třídy těmito starostmi netrpí: u holého jména třídy ve jmenném prostoru se PHP ke globálnímu prostoru nikdy nevrací. Klíče class.otherNamespace a class.global tedy u tříd volí pouze mezi importem a lomítkem a žádná jejich úprava není riziková. Název bez úvodního lomítka (např. Model\User při existujícím use App\Model;) se ponechává, protože se vyhodnocuje relativně k importu nebo k jmennému prostoru souboru. V souboru bez jmenného prostoru je úvodní lomítko vždy zbytečné a rozhodnutí qualification.leadingBackslash jej spolehlivě odstraní.

Shrnutí

  • Nekvalifikovaná funkce či konstanta ve jmenném prostoru znamená v PHP buď prvek z daného jmenného prostoru, nebo globální prvek a z jediného souboru to nelze spolehlivě určit.
  • Nastavte v konfiguraci nameResolution: certain (a případně doplňte seznamy v klíči namespaces). Chování všech pravidel bude rázem jednoznačné a opravy dříve závislé na odhadu přestanou být rizikové.
  • Části projektu s lokálními pomocnými funkcemi (např. testy) nastavte v přepisu nameResolution: uncertain.
  • Bez tohoto nastavení postupuje DressCode maximálně opatrně a úpravy provádí pouze s vaším výslovným svolením v fixRisky nebo s přepínačem --fix-risky.
  • Nové deklarace ve jmenných prostorech DressCode automaticky pohlídá pod cestou namespaces.functions; výchozí seznamy za vás sestaví dresscode init.
  • Funkce z vlastního jmenného prostoru vždy volejte přes explicitní use function. Pokud by se soubor s funkcí náhodou nenačetl, dozvíte se to okamžitě díky chybové hlášce.
  • Jistota o jménech dovoluje PHP volání funkcí výrazně zrychlit, viz Rychlejší volání funkcí v PHP.

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