PHP code moet altijd worden afgebakend met de volledige standaard PHP markeringen:
<?php ?>
Korte markeringen zijn nooit toegelaten
Wanneer een string letterlijk is (hij bevat geen variabelvervanging), moet altijd de apostroof of "enkele quote" gebruikt worden om de string af te bakenen:
$a = 'Voorbeeld String';
Wanneer een letterlijke string zelf apostrofen bevat is het toegelaten de string af te bakenen met aanhalingstekens ("double quotes"). Dit is dringend aangeraden voor SQL verklaringen:
$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
De bovenstaande syntax is verkozen boven het "escapen" van de apostrofen.
Variabelvervanging is toegestaan met respect voor de volgende vormen:
$greeting = "Hello $name, welcome back!"; $greeting = "Hello {$name}, welcome back!";
Om uniformiteit te respecteren is deze vorm niet toegestaan:
$greeting = "Hello ${name}, welcome back!";
Strings kunnen samengevoegd worden met de "." operator. Er moet steeds een spatie vòòr en na de "." operator worden ingevoegd om de leesbaarheid te verbeteren:
$company = 'Zend' . 'Technologies';
Wanneer men strings samenvoegt met de "." operator is het toegelaten de verklaring in meerdere regels op te breken om de leesbaarheid te vergroten. In dat geval moet elke opeenvolgende regel met spaties worden opgevuld zodat de "." operator uitgelijnd is onder de "=" operator:
$sql = "SELECT `id`, `name` FROM `people` " . "WHERE `name` = 'Susan' " . "ORDER BY `name` ASC ";
Negatieve nummers zijn verboden voor indexen.
Een geïndexeerde array mag starten met eender welk niet negatief nummer. Dit wordt evenwel afgeraden. Het is aangeraden dat alle arrays een basisindex van 0 hebben.
Wanneer men een geïndexeerde array definieert met het array
concept moet er een spatie worden ingevoegd na elke komma afbakening om
de leesbaarheid te verbeteren:
$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
Het is ook toegelaten om een geïndexeerde array op meerdere regels te definieren. In dat geval moet elke opeenvolgende regel met spaties worden opgevuld zodanig dat het begin van elke regel als volgt is uitgelijnd:
$sampleArray = array(1, 2, 3, 'Zend', 'Studio', $a, $b, $c, 56.44, $d, 500);
Wanneer men associatieve arrays met het array
concept definieert is het aangeraden de verklaring in meerdere regels op te
breken. In dat geval moet elke opeenvolgende regel met spaties worden
opgevuld zodat de indexen (keys) en waarden (values) uitgelijnd zijn:
$sampleArray = array('firstKey' => 'firstValue', 'secondKey' => 'secondValue');
Klassebenaming moet de volgende overeenkomsten volgen.
De accolade wordt steeds op de regel onder de klassenaam geschreven ("one true brace" vorm).
Elke klasse moet een documentatieblok hebben dat de PHPDocumentor standaard volgt.
Code in een klasse moet geïndenteerd zijn met vier spaties.
Eén klasse, éen bestand.
Bijkomende code schrijven in een klassebestand is toegelaten maar wordt afgeraden. Indien men het toch doet moet de bijkomende code met twee lege regels worden gescheiden van de klassecode.
Dit is een voorbeeld van een aanvaardbare klasseverklaring:
/** * Documentatie Blok Hier */ class SampleClass { // de gehele inhoud van de klasse // moet geindenteerd worden met vier spaties }
Lidvariabelen moeten benaamd worden volgens de variabele benamingsovereenkomst.
Variabelen die in de klasse worden verklaard moeten bovenaan in de klasse worden opgesomd, vòòrdat functies worden verklaard.
Het concept var
is niet toegestaan. Lidvariabelen
moeten steeds hun zichtbaarheid verklaren door één van de private
,
protected
, of public
concepten te gebruiken.
Toegang verlenen aan lidvariabelen door hen publiek te maken is toegestaan
maar wordt afgeraden ten voordele van de databenaderingsmethodes (set/get).
Functiebenaming moet de benamingsovereenkomsten volgen.
Functies binnen klasses moeten steeds hun zichtbaarheid verklaren
door één van de private
, protected
, of
public
concepten te gebruiken.
Net zoals klassen, moet de accolade steeds op de regel onder de functienaam worden geschreven ("one true brace" vorm). Er is geen spatie tussen de functienaam en de haakjes voor de argumenten. Er is één spatie tussen de sluitende haakjes en de accolade.
Functies in het globale bereik zijn zeer sterk afgeraden.
Dit is een voorbeeld van een aanvaardbare verklaring van een functie in een klasse:
/* * Documentatie blok hier */ function sampleMethod($a) { // de gehele inhoud van de functie // moet geindenteerd worden met vier spaties }
NOTA: Doorgeven per verwijzing (pass by reference) is alleen toegestaan in de functieverklaring:
function sampleMethod(&$a) {}
Call-time pass by reference is verboden.
De terugkeerwaarde mag niet tussen haakjes worden ingesloten. Dat kan de leesbaarheid hinderen en kan ook de code breken indien een methode later wordt veranderd om per verwijzing terug te sturen.
function foo() { // FOUT return($this->bar); // GOED return $this->bar; }
Functie-argumenten worden gescheiden door één enkele spatie na de komma afbakening. Dit is een voorbeeld van een aanvaardbare functie-aanroep voor een functie die drie argumenten heeft:
threeArguments(1, 2, 3);
Call-time pass by reference is verboden. Zie de sectie over functieverklaringen voor de juiste wijze om argumenten per verwijzing door te sturen.
Voor functies welke arrays als argument aanvaardden mag de functieaanroep het "array" concept bevatten en kan deze in meerdere regels worden opgesplitst om de leesbaarheid te vergroten. In deze gevallen blijven de regels voor het schrijven van arrays van kracht:
threeArguments(array(1, 2, 3), 2, 3); threeArguments(array(1, 2, 3, 'Zend', 'Studio', $a, $b, $c, 56.44, $d, 500), 2, 3);
Control statements gebaseerd op if
en
elseif
concepten moeten een enkele spatie voor de openende
haakjes van de conditie, en een enkele spatie na de sluitende haakjes.
In de voorwaardeverklaringen tussen de haakjes moeten operators gescheiden worden met spaties om de leesbaarheid te bevorderen. Binnenhaakjes zijn aangeraden voor het groeperen van meer complexe voorwaarden.
De openingsaccolade wordt op dezelfde regel als de voorwaardeverklaring geschreven. De sluitende accolade wordt altijd op een alleenstaande regel geschreven. Alle inhoud binnenin de accolades moet steeds met vier spaties geïndenteerd worden.
if ($a != 2) { $a = 2; }
Voor "if" verklaringen die "else if" of "else" inhouden moet de vorm zoals in de volgende voorbeelden zijn:
if ($a != 2) { $a = 2; } else { $a = 7; } if ($a != 2) { $a = 2; } else if ($a == 3) { $a = 4; } else { $a = 7; }
PHP laat het toe om in bepaalde gevallen deze verklaringen zonder accolades te schrijven. De codestandaard maakt geen verschil en alle "if", "else if" of "else" verklaringen moeten accolades gebruiken.
Het gebruik van "elseif" is toegestaan maar "else if" wordt sterk aanbevolen.
Control statements geschreven met "switch" moeten een enkele spatie voor de openende haakjes van de voorwaardeverklaring hebben, en een enkele spatie na de sluitende haakjes.
Alle inhoud binnen een "switch" verklaring moet met vier spaties geïndenteerd worden. Inhoud onder elke "case" moet geïndenteerd worden met vier extra spaties.
switch ($numPeople) { case 1: break; case 2: break; default: break; }
default
mag nooit weggelaten worden van een
switch
verklaring.
NOTA: Het is soms handig een case
verklaring te hebben die doorvalt naar de volgende case
verklaring door het weglaten van break
of return
in de verklaring. Om deze gevallen van bugs te onderscheiden moet elk
van de gevallen waarin een break
of return
wordt weggelaten een commentaar "// break intentionally omitted"
bevatten.
Alle documentatieblokken ("docblocks") moeten compatibel zijn met het phpDocumentor formaat. Een beschrijving van het phpDocumentor formaat is buiten het bereik van dit document. Voor meer informatie kunt u terecht op: http://phpdoc.org"
Alle broncodebestanden geschreven voor het Zend Framework of dat ermee samenwerkt moet een "file-level" docblock bevatten aan het begin van elk bestand en een "class-level" docblock onmiddellijk boven elke klasse. Hierna enkele voorbeelden van zulke docblocks.
Elk bestand dat PHP code bevat moet een hoofdblok aan het begin van het bestand bevatten dat minstens de volgende phpDocumentor gegevens bevat:
/** * Korte beschrijving van het bestand * * Lange beschrijving van het bestand (indien aanwzeig)... * * LICENSE: Licentie informatie * * @copyright 2005 Zend Technologies * @license http://www.zend.com/license/3_0.txt PHP License 3.0 * @version CVS: $Id:$ * @link http://dev.zend.com/package/PackageName * @since File available since Release 1.2.0 */
Elke klasse moet een docblock bevatten dat minstens de volgende phpDocumentor gegevens bevat:
/** * Korte beschrijving van de klasse * * Lange beschrijving van de klasse (indien aanwezig)... * * @copyright 2005 Zend Technologies * @license http://www.zend.com/license/3_0.txt PHP License 3.0 * @version Release: @package_version@ * @link http://dev.zend.com/package/PackageName * @since Class available since Release 1.2.0 * @deprecated Class deprecated in Release 2.0.0 */
Elke functie, methodes inbegrepen, moet een docblock hebben dat minstens het volgende bevat:
Een beschrijving van de functie
Alle argumenten
Alle mogelijke terugwaarden
Het is niet nodig om de "@access" tags te gebruiken want de zichtbaarheid is reeds bekend via het gebruik van "public", "private", of "protected" bij het verklaren van de functie.
Indien een functie of methode een exception mag teruggeven, gebruik @throws:
@throws exceptionClass [beschrijving]