Manual:Coding conventions/PHP/cs

Tato stránka popisuje konvenci která se používá při psaní u PHP skriptů u. Nezapomeňte se podívat také na stránku která je platná pro všechny programovací jazyky s nimiž se tu můžete setkat, včetně PHP. Pokud vás zajímá pouze stručné resumé, co by vám pomohlo překontrolovat váš commit, zkuste použít.

Aby mohli vývojáři snadno odhalit kód, který není v souladu s touto konvencí, existuje nástroj stylize, který kontroluje syntaxi a doplní mezery na příslušná místa. Tento nástroj je dostupný přes webové rozhraní. Je doporučeno ho použít ke kontrole souborů dřív, než je uložen commit, který se bude odesílat do Gitu.

Pravidla pro PHP_CodeSniffer jsou také k dispozici. Na stránce se dozvíte více. Git repozitář  obsahuje konfigurační nastavení pro PHP CodeSniffer, optimalizované pro kód MediaWiki.

Mezery
Pro MediaWiki je prvořadým úkolem srozumitelnost a přehlednost kódu, proto se při psaní hojně využívají mezery.

Odsazení s tabulátory, nikoli mezerami. Omezte řádky na 120 znaků (vzhledem k šířce karty 4 znaky).

U binárních operátorů, přidejte z každé strany jednu mezeru, tak aby byly naprosto jasně odděleny. Viz příklad:

Také obsah závorek oddělujte mezerami. Výjimkou je pouze situace, kdy závorky nemají žádný obsah. Naopak mezi jméno funkce a otevírací závorku pro její obsah mezeru nedávejte.

Mezeru do závorek vložte jen pokud chcete deklarovat pole, které nemá být prázdné. Mezery také nepoužívejte při adresování jednotlivých prvků pole.

Za řídící prvky, jako je, , , , , nebo klíčové slovo , naopak mezeru vložte vždy:

U deklarování typu proměnné mezery nepoužívejte nikdy. Ani v závorkách, ani za nimi:

U komentářů přidejte mezeru za, resp. , a teprve pak napište svůj komentář.

Jako vývojářskou pomůcku, která se postará o správné umístění mezer, lze použít nástroj stylize, který přidává mezery automaticky podle konvence PHP. Nástroj je dostupný přes webové rozhraní.

Ternární operátor
může být velice užitečný, pokud jsou výrazy velmi krátké a zřejmé:

Pokud však uvažujete o víceřádkovém výrazu s ternárním operátorem, zvažte místo toho použití bloku. Pamatujte, že místo na disku je levné a čitelnost kódu je nadevše, „pokud“ je angličtina a  není. Pokud používáte víceřádkový ternární výraz, otazník a dvojtečka by měly být na začátku druhého a třetího řádku a nikoli na konci prvního a druhého řádku (na rozdíl od konvence JavaScriptu MediaWiki).

Protože MediaWiki vyžaduje PHP (MW stabilní php požadavek) nebo novější, je použití shorthand ternárního operátora  známého také jako elvis operator, zavedeného v PHP 5.3, povoleno.

Od PHP 7.0 je k dispozici null coalescing operator a v některých případech může nahradit ternárního operátora. Například místo

místo toho můžete napsat následující:

Literální řetězce
Jednotlivé uvozovky jsou preferovány ve všech případech, kdy jsou rovnocenné dvojitým uvozovkám. Kód používající jednoduché uvozovky je méně náchylný k chybám a snadněji se kontroluje, protože nemůže náhodně obsahovat escape sequences nebo variables. Například regulární výraz vyžaduje zvláštní zpětné lomítko, takže je o něco více matoucí a náchylnější k chybám než. Také pro lidi, kteří používají americké a britské qwerty klávesnice, je snadnější psát, protože nemusí stisknout klávesu shift.

Nebojte se však používat dvojitě citovanou funkci interpolace řetězců PHP:

To má o něco lepší výkonové vlastnosti než ekvivalent pomocí operátoru zřetězení (tečka) a vypadá to také hezčí.

Řetězce ve stylu heredoc jsou někdy užitečné:

Někteří autoři rádi používají END jako koncový token, který je také názvem funkce PHP. To vede k IRC konverzacím, jako jsou následující:

Funkce a jejich parametry
Vyhněte se předávání obrovského počtu parametrů funkcím nebo konstrukcím:

Je nemožné rychle si zapamatovat pořadí parametrů a nevyhnutelně skončíte s nutností zakódovat všechna výchozí nastavení u volajících, abyste si přizpůsobili parametr na konci seznamu. Pokud jste v pokušení kódovat funkci jako je tato, zvažte raději předání asociativní sady pojmenovaných parametrů.

Obecně se nedoporučuje ve funkcích používání booleovských parametrů. V příkladu, aniž bychom hledali dokumentaci , není možné vědět, co tyto parametry znamenají. Mnohem lepší je použít konstanty třídy a vytvořit obecný parametr příznaku:



Nebo, aby vaše funkce akceptovala řadu pojmenovaných parametrů:



Zkuste nepřepočítávat proměnné v průběhu funkce a vyhýbejte se úpravám parametrů předávaných funkci (pokud nejsou předány odkazem a to je samozřejmě celý bod funkce).

Výrazy přiřazení
Použití přiřazení jako výrazu je pro čtenáře překvapivé a vypadá to jako chyba. Nepište kód takto:

Prostor je levný a vy jste rychlý psací stroj. Místo toho použijte:

Použití přiřazení v klauzuli bývalo pro iteraci legitimní:

V novém kódu to není nutné. Místo toho použijte:

Výpůjčky z jazyka C
PHP je programovací jazyk, který byl navržen lidmi, kteří milovali programování v C a proto chtěli do PHP implementovat takovou syntaxi, na jakou byli zvyklí. Ovšem PHP se v několika významných detailech od jazyka C liší.

U jazyka C se konstanty implementují jako makra pro preprocesor a tím pádem se zpracovávají velmi rychle. U PHP, se ale vyhledává jméno konstanty v indexované tabulce což je mnohem pomalejší, než když se použije řetězcový literál. Ve většině případů, tam, kde byste použili v jazyce C množinu maker, je u PHP výhodnější použít řetězcové literály.

PHP má tři speciální literály, pro které je velká / malá / smíšená velikost písma v jazyce nevýznamná (od PHP 5.1.3), ale pro kterou je naše konvence vždy malá:, a.

Použijte, nikoli. Mají jemně odlišný význam:

Ovšem z hlediska výkonu na tom bude druhá varianta hůř.

Alternativní syntaxe pro řídící struktury
PHP umožňuje pro řídicí struktury, jako,  , atp., používat alternativní syntaxi, při které se místo složených závorek použije dvojtečka:

Takové syntaxi byste se však měli vyhnout širokým obloukem, protože řada textových editorů by se zobrazením takového kódu mohla mít problém. Takže použijte raději složené závorky:

Závorky
Více o závorkách viz část věnovanou odsazování a zarovnání kódu na stránce věnované všeobecné konvenci pro psaní zdrojového kódu.

Deklarování typů v parametrech funkce
Používejte vstupní deklaraci typu (podívejte se na naznačení typu – type hinting) a deklarujte i typ návratové hodnoty, všude kde to jen lze.

Upozorňuji, že u starších verzí PHP (před 7.4), nelze obsloužit naznačování typu (ať již restriktivní, či volné) v rámci podtřídy.

Scalar typehints are allowed as of MediaWiki 1.35, following the switch to PHP 7.2 (T231710).

Use PHP 7.1 syntax for nullable parameters: choose

instead of

The former conveys precisely the nullability of a parameter, without risking any ambiguity with optional parameters. IDEs and static analysis tools will also recognize it as such, and will not complain if a non-nullable parameter follows a nullable one.

Konvence pro jména
Pro názvy funkcí a proměnných používejte lower-CamelCase notaci. Jak demonstruje ukázkový příklad: Pro názvy tříd používejte naopak Upper-CamelCase:. Použijte velká písmena s podtržítky pro globální a třídní konstanty:,. Jiné proměnné jsou obvykle malá nebo nižšíCamelCase; nepoužívejte podtržítka v názvech proměnných.

Používejte také zavedené prefixy. I ty v kódu napovídají oč jde:

Funkce

 * (wiki funkce) – funkce, dostupné na té nejvyšší úrovni, např.
 * (funkce rozšíření) = jsou globální funkce, napsané v rámci rozšíření. I když většina skriptů napsaných v moderním stylu vkládá do svých tříd funkce, které se registrují jako háčky, jako statické metody třídy, aby na té nejvyšší úrovni do budoucna zbylo jen minimum, takto pojmenovaného kódu. (-- brion in Manual_talk:Coding_conventions)

V tomto případě se preferují slovesa, která jasně naznačí co má funkce udělat: takže místo použijte.

Proměnné

 * – globální proměnné, např. . Toto vždy používejte pro nové globály, abyste mohli snadno najít chybějící prohlášení „". V rozšířeních by měl být název přípony použit jako oddělovač oboru názvů. For example,, not.
 * Global declarations should be at the beginning of a function so dependencies can be determined without having to read the whole function.

It is common to work with an instance of the  class; we have a naming convention for these which helps keep track of the nature of the server to which we are connected. This is of particular importance in replicated environments, such as Wikimedia and other large wikis; in development environments, there is usually no difference between the two types, which can conceal subtle errors.


 * – a  object for writing (a master connection)
 * – a  object for non-concurrency-sensitive reading (this may be a read-only replica, slightly behind master state, so don't ever try to write to the database with it, or get an "authoritative" answer to important queries like permissions and block status)

The following may be seen in old code but are discouraged in new code:


 * – Session variables, e.g.
 * – Cookie variables, e.g.
 * – Post variables (submitted via form fields), e.g.
 * – object member variables: . This is discouraged in new code, but try to stay consistent within a class.

The function should only be used when you want to suppress errors. Otherwise just use  (boolean conversion).

Common use case: Optional boolean configuration keys that default to false.
 * essentially does.


 * Beware of boolean conversion pitfalls.
 * It suppresses errors about undefined properties and variables. If only intending to test for undefined, use . If only intending to test for "empty" values (e.g. false, zero, empty array, etc.), use.

Do not use to test for. Using in this situation could introduce errors by hiding misspelled variable names. Instead, use.

Boolean conversion

 * Do not use  or  to test if a string or array is empty, because PHP considers    to be falsy – but   is a valid title and valid user name in MediaWiki. Use   or   instead.
 * Study the rules for conversion to boolean. Be careful when converting strings to boolean.

Ostatní

 * Array plus does not renumber the keys of numerically-indexed arrays, so . If you want keys to be renumbered, use :
 * Make sure you have set to  . This will notify you of undefined variables and other subtle gotchas that stock PHP will ignore. See also.
 * When working in a pure PHP file (e.g. not an HTML template), omit any trailing  tags. These tags often cause issues with trailing white-space and "headers already sent" error messages (cf. 17642 and http://news.php.net/php.general/280796). It is conventional in version control for files to have a new line at end-of-file (which editors may add automatically), which would then trigger this error.
 * Do not use the syntax introduced in 5.3. PHP may have introduced the feature, but that does not mean we should use it.
 * Do not pass by reference when traversing an array unless you have to. Even then, be aware of the consequences. (See http://www.king-foo.be/2010/10/php-quirks-passing-an-array-by-reference/)
 * PHP lets you declare static variables even within a non-static method of a class. This has led to subtle bugs in some cases, as the variables are shared between instances. Where you would not use a  property, do not use a static variable either.

Equality operators
Be careful with double-equals comparison operators. Triple-equals is generally more intuitive and should be preferred unless you have a reason to use double-equals.


 * is true (!)
 * is true (!)
 * is false
 * To check if two scalars that are supposed to be numeric are equal, use, e.g.  is true.
 * To check if two variables are both of type 'string' and are the same sequence of characters, use, e.g.  is false.

JSON number precision
JSON uses JavaScript's type system, so all numbers are represented as 64bit IEEE floating point numbers. This means that numbers lose precision when getting bigger, to the point where some whole numbers become indistinguishable: Numbers beyond 2^52 will have a precision worse than ±0.5, so a large integer may end up changing to a different integer. To avoid this issue, represent potentially large integers as strings in JSON.

Don't use built in serialization
PHP's built in serialization mechanism (the  and   functions) should not be used for data stored (or read from) outside of the current process. Use JSON based serialization instead (however, beware the pitfalls). This is policy established by RFC T161647.

The reason is twofold: (1) data serialized with this mechanism cannot reliably be unserialized with a later version of the same class. And (2) crafted serialized data can be used to execute malicious code, posing a serious security risk.

Sometimes, your code will not control the serialization mechanism, but will be using some library or driver that uses it internally. In such cases, steps should be taken to mitigate risk. The first issue mentioned above can be mitigated by converting any data to arrays or plain anonymous objects before serialization. The second issue can perhaps be mitigated using the whitelisting feature PHP 7 introduces for unserialization.

Komentáře a dokumentace
Je nezbytné, aby váš kód byl dobře zdokumentován, aby ostatní vývojáři a opraváři chyb mohli snadno pochopit logiku vašeho kódu. New classes, methods, and member variables should include comments providing brief descriptions of their functionality (unless it is obvious), even if private. In addition, all new methods should document their parameters and return values.

Při dokumentaci využíváme značky a styl, podobný jako když se používá Doxygen (ostatně PHPDoc z něj vychází, takže se jejich styl navzájem moc neliší). Díky tomu lze dokumentaci automaticky generovat rovnou z komentářů v kódu (viz Manual:mwdocgen.php). Begin a block of Doxygen comments with, instead of the Qt-style formatting. Doxygen structural commands start with. (Use  rather than   as the escape character – both styles work in Doxygen, but for backwards and future compatibility MediaWiki has chosen the   style.) They organize the generated documentation (using ) and identify authors (using   tags).

Používají se při popisu parametrů, které se předávají funkci (metodě), a i toho co funkce vrací. Při popisu parametrů to vypadá takto: @param type $paramName Description of parameter Pokud parametr akceptuje různé typy, použijte k jejich oddělení znak roury, neboli svislítka '|' (pipe), podobně jako u následujícího příkladu:

V popisu pokračujte na dalším řádku, odsazeném o jednu mezeru navíc.

For every public interface (method, class, variable, whatever) you add or change, provide a  tag, so people extending the code via this interface know they are breaking compatibility with older versions of the code.

FIXME usually means something is bad or broken. TODO means that improvements are needed; it does not necessarily mean that the person adding the comment is going to do it. HACK means that a quick but inelegant, awkward or otherwise suboptimal solution to an immediate problem was made, and that eventually a more thorough rewrite of the code should be done.

Záhlaví zdrojáků
In order to be compliant with most licenses you should have something similar to the following (specific to GPLv2 applications) at the top of every source file.

Značky pro Doxygen
V našich zdrojácích používáme při vkládání poznámek následující značky, s nimiž pracuje Doxygen. Aby byla zajištěna konzistence vašeho souboru, zachovejte prosím při jejich použití i vy stejné pořadí, v jakém jsou uvedeny zde:

Poznámky k souboru:
 * @file
 * @ingroup
 * @author

Třídy a jejich vlastnosti:


 * @todo
 * @var
 * @deprecated
 * @class
 * @see
 * @since
 * @param
 * @return
 * @throws
 * @private

Poznámky k testům
U testů používáme, mimo jiné, i následující poznámky. V tomto případě se nejedná o dokumentaci, protože mají význam pouze pro PHPUnit a svůj význam mají pouze při testování.


 * @depends
 * @group
 * @covers
 * @dataProvider
 * @expectedException
 * @expectedExceptionMessage

Integrace kódu
V kódu MediaWiki najdete i kódy, které jsou na ní zcela nezávislé a tím pádem je lze snadno implementovat do jiných aplikací. While some of these now exist as separate libraries, others remain within the MediaWiki source tree (e.g. the files in ). Apart from these, code should be integrated into the rest of the MediaWiki environment, and should allow other areas of the codebase to integrate with it in return.

Viditelnost
Svoje metody (funkce) si nastavte jako public/protected/private (podle toho jak uznáte za vhodné). Ale není důvod k tomu, aby byly veřejné (public) všechny!

Globální objekty
Nepřistupujte k superglobálním proměnným PHP jako, , atp. přímo. Použijte získávejte jejich hodnotu raději přes volání metody. Většinou jsou k dispozici různé metody, které vám umožní získat požadovanou hodnotu ve formě typu, jaký zrovna potřebujete. Takže hodnotu pro aktuální můžete zjistit z nejbližšího objektu, takže není vůbec nutné kvůli tomu volat. Stejně tak kvůli tomu nemusíte sahat přímo do. Pokud chcete získat IP adresu aktuálního uživatele, stačí použít.

Statické metody a jejich vlastnosti
Ve svém PHP statické metody a vlastnosti klidně používejte, jenom mějte neustále na paměti, jaký je rozdíl mezi  a. bude vždy odkazovat na funkce a proměnné v rámci třídy, zatímco  bude odkazovat na konkrétní podtřídu, která ji zavolá. Pro víc podrobnosti si přečtěte v dokumentaci k PHP o dědičnosti a pozdních statických vazbách.

Třídy
Zapouzdřete svůj kód do objektově orientované třídy, nebo ho přidejte jako novou funkci do třídy již existující; nepřidávejte nové globální funkce či proměnné, pokud to není nezbytné. Snažte se mít neustále na paměti rozdíl mezi třídami, které patří k backendu, jakou jsou například entity které pracují s databází, jako,  ,  , aj. A třídami co obsluhují frontend, jako,  ,   a jiné, co zastupují stránky a rozhraní co se vrací uživateli. A i pokud není váš kód zrovna objektově orientovaný, je lepší ho umístit alespoň do statické třídy, jako jsou např. třídy  nebo.

As a holdover from PHP 4's lack of private class members and methods, older code will be marked with comments such as to indicate the intention; respect this as if it were enforced by the interpreter.

Mark new code with proper visibility modifiers, including if appropriate, but do not add visibility to existing code without first checking, testing and refactoring as required. It's generally a good idea to avoid visibility changes unless you're making changes to the function which would break old uses of it anyway.

Jak ošetřit chyby
Don't suppress errors with PHP's operator, for any reason ever. It's broken when  is enabled and it causes an unlogged, unexplained error if there is a fatal, which is hard to support.

The proper method of handling errors is to actually handle the errors. For example, if you are thinking of using an error suppression operator to suppress an invalid array index warning, you should instead perform an check on the array index before trying to access it. When possible, always prevent PHP errors rather than catching and handling them afterwards. It makes the code more understandable and avoids dealing with slow error suppression methods.

If and only if there is a situation where you are expecting an unavoidable PHP warning, you may use  and   from the at-ease library instead of the   operator. This is for cases where:


 * 1) It is impossible to anticipate the error that is about to occur; and
 * 2) You are planning on handling the error in an appropriate manner after it occurs.

An example of this is opening a file with. You can anticipate the error by calling  and , but it is possible the file will have been deleted in between the check and the actual   call. In this case, your code should be ready to handle the case that the file will fail to open, and you can use  to prevent PHP from being noisy. Note that using  and   are slow. They are much slower than using the  operator, since it involves at least four function calls and reference counting, rather than just an opcode.

When your code encounters a sudden error, you should throw an exception rather than using PHP's. The exception handler will display this as nicely as possible to the end user and wiki administrator, and also provides a stack trace to developers. Don't throw an instance of Exception itself, but instead a subclass of it. Exceptions that indicate programming errors should be one of the exceptions that ship with PHP or a more specific subclass, while exceptions that indicate errors that are relevant to the end user should be an ErrorPageError or one of its subclasses.