A.4. Codestijl

A.4.1. PHP Code Afbakening

PHP code moet altijd worden afgebakend met de volledige standaard PHP markeringen:

<?php

?>

Korte markeringen zijn nooit toegelaten

A.4.2. Strings

A.4.2.1. String Literals

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';

A.4.2.2. Letterlijke strings die apostrofen bevatten

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.

A.4.2.3. Variabelvervanging

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!";

A.4.2.4. String samenvoeging

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 ";

A.4.3. Arrays

A.4.3.1. Numeriek Geïndexeerde Arrays

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);

A.4.3.2. Associatieve Arrays

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');

A.4.4. Klassen

A.4.4.1. Klasse Verklaring

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
}

A.4.4.2. Klasse lidvariabelen

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).

A.4.5. Functies en Methodes

A.4.5.1. Functie en Methode Verklaring

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;
}

A.4.5.2. Functie- en Methodegebruik

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);

A.4.6. Control Statements

A.4.6.1. If / Else / Elseif

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.

A.4.6.2. Switch

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.

A.4.7. Inline Documentatie

A.4.7.1. Documentatie Formaat

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.

A.4.7.2. Bestanden

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
*/

A.4.7.3. Klassen

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
 */

A.4.7.4. Functies

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]