B.4. Code Stil

B.4.1. PHP Code Abgrenzung

PHP Code muß immer mit der kompletten Form des Standard-PHP Tags abgegrenzt sein:

<?php

?>
                

Kurze Tags sind nie erlaubt.

B.4.2. Strings

B.4.2.1. String Literale

Wenn ein String ein Literal ist (er also keine Variablenvertreter enthält), muß immer das Apostroph oder "einzelne Anführungszeichen" verwendet werden um den String abzugrenzen:

$a = 'Beispiel String';
                    

B.4.2.2. String Literale die Apostrophe enthalten

Wenn ein literaler String selbst Apostrophe enthält, ist es gestattet den String mit Anführungszeichen oder "doppeltes Anführungszeichen" abzugrenzen. Das ist speziell für SQL Anweisungen zu befürworten:

$sql = "SELECT `id`, `name` from `people` WHERE `name`='Fred' OR `name`='Susan'";
                    

Der obige Syntax ist zu bevorzugen im Gegensatz zum Ausbruch von Apostrophs.

B.4.2.3. Variabler Austausch

Variabler Austausch ist gestatten bei Verwendung einer der zwei Formen:

$greeting = "Halle $name, willkommen zurück!";

$greeting = "Hallo {$name}, willkommen zurück!";
                    

Aus Gründen der Konstistenz ist folgende Form nicht gestattet:

$greeting = "Hallo ${name}, willkommen zurück!";
                    

B.4.2.4. Verbinden von Strings

Strings können verbunden werden indem man den "." Operator verwendet. Ein Leerzeichen muß immer vor und nach dem "." Operator hinzugefügt werden um die Lesbarkeit zu erhöhen:

$company = 'Zend' . 'Technologies';
                    

Wenn Strings mit dem "." Operator verbunden werden, ist es gestattet die Anweisung in mehrere Zeilen umzubrechen um die Lesbarkeit zu erhöhen. In diesen Fällen sollte jede folgende Zeile mit Leerraum aufgefüllt werden so das der "." Operator genau unterhalb des "=" Operators ist:

$sql = "SELECT `id`, `name` FROM `people` "
     . "WHERE `name` = 'Susan' "
     . "ORDER BY `name` ASC ";
                    

B.4.3. Arrays

B.4.3.1. Nummerisch indizierte Arrays

Negative Nummern sind in Indezes nicht gestattet.

Ein indiziertes Array kann mit mit irgendeiner nicht-negativen Nummer beginnen, trotzdem wird davon abgeraten und es wird vorgeschlagen das alle Arrays einen BasisIndex von 0 besitzen.

Wenn indizierte Arrays mit dem array Konstrukt deklariert werden, muß ein folgendes Leerzeichen nach jeder Kommabegrenzung hinzugefügt werden um die Lesbarkeit zu erhöhen:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio');
                    

Es ist auch gestattet mehrzeilige indizierte Arrays zu definieren bei Verwendung des "array" Konstrukts. In diesem Fall, muß jede folgende Zeile mit Leerzeichen aufgefüllt werden so das der Beginn jeder Zeile wie folgt erscheint:

$sampleArray = array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500);
                    

B.4.3.2. Assoziative Arrays

Wenn assoziative Arrays mit dem array Konstrukt deklariert werden, ist es gestattet die Anweisung in mehrere Zeilen zu brechen. In diesem Fall muß jede folgende Linie mit Leerraum aufgefüllt werden so das beide, der Schlüssel und der Wert untereinander stehen:

$sampleArray = array('firstKey'  => 'firstValue',
                     'secondKey' => 'secondValue');
                    

B.4.4. Klassen

B.4.4.1. Klassen Deklarationen

Klassen müssen nach der folgenden Namenskonvention benannt werden.

Die Klammer wird immer in der Zeile unter dem Klassennamen geschrieben ("one true brace" Form).

Jede Klasse muß einen Dokumentationsblock haben der dem PHPDocumentor Standard entspricht.

Jeglicher Code innerhalb der Klasse muß vier Leerzeichen eingerückt sein.

Nur eine Klasse ist pro PHP Datei gestattet.

Das Platzieren von zusätzlichem Code in einer Klassendatei ist gestattet aber es wird davon abgeraten. In diesem Dateien müssen zwei leere Zeilen die Klasse von jedem zusätzlichen PHP Code in der Datei seperieren.

Das ist ein Beispiel einer akzeptierbaren Klassendeklaration:

/**
 * Dokumentations Block hier
 */
class SampleClass
{
    // gesamter Inhalt der Klasse
    // muss mit vier Leerzeichen eingerückt sein
}
                    

B.4.4.2. Klassenvariablen

Klassenvariablen müssen nach den folgenden Variablen-Benennungs-Konventionen benannt werden.

Jede Variable die in der Klasse deklariert wird muß am Beginn der Klasse ausgelistet werden, bevor irgendeine Funktion deklariert wird.

Das var Konstrukt ist nicht gestattet. Klassenvariablen definieren Ihre Sichtbarkeit durch die Verwendung des private, protected, oder public Konstrukts. Der direkte Zugriff auf Klassenvariablen durch das öffentlich machen ist gestattet aber es wird davon abgeraten da hierfür Zugriffsvariablen verwendet werden sollten (set/get).

B.4.5. Funktionen und Methoden

B.4.5.1. Deklaration von Funktionen und Methoden

Funktionen müssen nach der folgenden Namenskonvention benannt werden.

Funktionen innerhalb von Klassen müssen immer Ihre Sichtbarkeit durch Verwendung einer der private, protected, oder public Konstrukte definieren.

Wie bei Klassen, wird die Klassem immer in der Zeile unterhalb des Funktionsnamens geschrieben werden ("one true brace" Form). Es gibt kein Leerzeichen zwischen dem Funktionsnamen und der öffnenden Klammer für die Argumente.

Von Funktionen im globalen Raum wird komplett abgeraten.

Das ist ein Beispiel einer akzeptierbaren Funktionsdeklaration in einer Klasse:

/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * Dokumentations Block hier
     */
    public function bar()
    {
        // gesamter Inhalt der Funktion
        // muss durch view Leerzeichen eingerückt sein
    }
}
                    

NOTIZ: Das Übergeben durch Referenz ist nur in der Deklaration der Funktion gestattet:

/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * Dokumentations Block hier
     */
    public function bar(&$baz)
    {}
}
                    

Der Aufruf durch Referenz ist nicht gestattet.

Der Rückgabewert darf nicht in Klammern stehen. Das kann die Lesbarkeit behindern und auch den Code unterbrechen wenn eine Methode später später auf Rückgabe durch Referenz geändert wird.

/**
 * Dokumentations Block hier
 */
class Foo
{
    /**
     * FALSCH
     */
    public function bar()
    {
        return($this->bar);
    }

    /**
     * RICHTIG
     */
    public function bar()
    {
        return $this->bar;
    }
}
                    

B.4.5.2. Verwendung von Funktionen und Methoden

Funktionsargumente sind durch ein einzelnes trennendes Leerzeichen nach dem Komma Trennzeichen getrennt. Das ist ein Beispiel für einen akzeptierbaren Funktionsaufruf für eine Funktion die drei Argumente benötigt:

threeArguments(1, 2, 3);
                    

Übergabe von Referenzen zur Laufzeit ist gestattet. Siehe die Sektion für Funktions Deklarationen für den richtigen Weg um Funktionsargumente per Referenz zu übergeben.

Für Funktionen deren Argumente Arrays gestatten, kann der Funktionsaufruf das "array" Konstrukt beinhalten und in mehrere Zeilen gespalten werden um die Lesbarkeit zu erhöhen. In diesen Fällen ist der Standard für das Schreiben von Arrays trotzdem:

threeArguments(array(1, 2, 3), 2, 3);

threeArguments(array(1, 2, 3, 'Zend', 'Studio',
                     $a, $b, $c,
                     56.44, $d, 500), 2, 3);
                    

B.4.6. Kontrollanweisungen

B.4.6.1. If / Else / Elseif

Kontrollanweisungen die auf den if und elseif Konstrukten beruhen müssen ein einzelnes Leerzeichen vor der öffnenden Klammer der bedingten Anweisung, und ein einzelnes Leerzeichen nach der schließenden Klammer.

Innerhalb der bedingten Anweisungen zwischen den Klammern, müssen die Operationen, für die Lesbarkeit, durch Leerzeichen getrennt werden. Innere Klammern sind zu beführworten um die logische Gruppierung von größeren Bedingungen zu erhöhen.

Die öffnende Klammer wird in der selben Zeile geschrieben wie die Bedingungsanweisung. Die schließende Klammer wird immer in einer eigenen Zeile geschrieben. Jeder Inhalt innerhalb der Klammer muß vier Leerzeichen eingerückt werden.

if ($a != 2) {
    $a = 2;
}
                    

Für "if" Anweisungen die "elseif" oder "else" beinhalten, muß die Formatierung wie in den folgenden Beispielen stattfinden:

if ($a != 2) {
    $a = 2;
} else {
   $a = 7;
}


if ($a != 2) {
    $a = 2;
} elseif ($a == 3) {
   $a = 4;
} else {
   $a = 7;
}
                    

PHP erlaubt es solche Anweisungen in einigen Fällen auch ohne Klammern zu schreiben. Der Code Standard macht keine Unterscheidungen und es müssen alle "if", "elseif" oder "else" Anweisungen in Klammern geschrieben werden.

Die Verwendung des "elseif" Konstruktes ist erlaubt es wird aber sehr stark davon abgeraten und es ist die "else if" Kombination zu bevorzugen.

B.4.6.2. Switch

Kontrollanweisungen die mit dem "switch" Konstrukt geschrieben werden müssen ein einzelnes Leerzeichen vor der öffnenden Klammer der Bedingten Anweisung besitzen, und auch ein einzelnes Leerzeichen nach der schließenden Klammer.

Jeglicher Inhalt innerhalb der "switch" Anweisung muß um vier Leerzeichen eingerückt sein. Der Inhalt unter jeder "case" Anweisung muß um vier zusätzliche Leerzeichen eingerückt werden.

switch ($numPeople) {
    case 1:
        break;

    case 2:
        break;

    default:
        break;
}
                

Das default Konstrukt darf nie bei der switch Anweisung vergessen werden.

NOTIZ: Es ist machmal nützlich eine case Anweisung zu schreiben, die durch das nächste case fällt indem in solchen Fällen kein break oder return angegeben wird. Um diese Fälle von Fehlern zu unterscheiden, muß jede case Anweisung wo break oder return unterlassen werden den Kommentar "// break intentionally omitted" enthalten.

B.4.7. Inline Dokumentation

B.4.7.1. Dokumentations Format

Alle Dokumentations Blöcke ("DocBlock") müssel mit dem phpDocumentor Format kompatibel sein. Die Beschreibung des phpDocumentor Formats is jenseits der Reichweite dieses Dokuments. Für weiterführende Informationen siehe: http://phpdoc.org">

Alle Sourcecode Datei welche für den Zend Framework geschrieben werden, oder welche mit dem Framework arbeiten müssen einen "file-level" Docblock am Beginn jeder Datei und einen "class-level" Docblock direkt überhalb jeder Klasse enthalten. Anbei sind Beispiele solcher Docblocks.

B.4.7.2. Dateien

Jede Datei die PHP Code enthält muß einen Header Block am Beginn der Datei besitzen welcher mindestens diese phpDocumentor Tags enthält:

/**
 * Kurze Beschreibung der Datei
 *
 * Lange Beschreibung der Datei (wenn vorhanden)...
 *
 * LICENSE: Einige Lizenz Informationen
 *
 * @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      Datei vorhanden seit Release 1.2.0
*/
                    

B.4.7.3. Klassen

Jede Klasse muß einen Docblock haben welche mindestens diese phpDocumentor Tags enthält:

/**
 * Kurze Beschreibung für die Klasse
 *
 * Lange Beschreibung für die Klasse (wenn vorhanden)...
 *
 * @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      Klasse vorhanden seit Release 1.2.0
 * @deprecated Klasse abgeraten ab Release 2.0.0
 */
                    

B.4.7.4. Funktionen

Jede Funktion, auch Objekt Methoden, müssen einen Docblock haben welcher mindestens folgendes enthält:

  • Eine Beschreibung der Funktion

  • Alle Argumente

  • Alle möglichen Rückgabewerte

Es ist nicht notwendig das "@access" Tag zu verwenden, weil das Accesslevel bereits vom "public", "private" oder "protected" Konstrukt bekannt ist wenn die Funktion deklariert wird.

Wenn eine Funktion/Methode eine Ausnahme werfen könnte, muß @throws verwendet werden:

@throws exceptionclass [Beschreibung]