Namenskonventionen
Zend Framework Coding Standard für PHP
Programmer's Reference Guide

Code Stil

PHP Code Abgrenzung

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

  1. <?php
  2.  
  3. ?>

Kurze Tags sind nie erlaubt. Für Dateien, die nur PHP-Code enthalten, darf das schließende Tag nicht angegeben werden (Siehe generelle Standards).

Strings

String Literale

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

  1. $a = 'Beispiel String';

String Literale die Apostrophe enthalten

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

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

Diese Syntax ist zu bevorzugen, im Gegensatz zum Entwerten des Apostrophs, da sie viel einfacher lesbar ist.

Variablensubstitution

Variablensubstitution ist gestattet bei Verwendung einer der Formen:

  1. $greeting = "Halle $name, willkommen zurück!";
  2.  
  3. $greeting = "Hallo {$name}, willkommen zurück!";

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

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

Verbinden von Strings

Strings müssen verbunden werden, indem man den "." Operator verwendet. Ein Leerzeichen muss immer vor und nach dem "." Operator hinzugefügt werden, um die Lesbarkeit zu erhöhen:

  1. $company = 'Zend' . ' ' . 'Technologies';

Wenn Strings mit dem "." Operator verbunden werden, ist es empfohlen, 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:

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

Arrays

Numerisch indizierte Arrays

Negative Zahlen sind in Indizes nicht gestattet.

Ein indiziertes Array kann mit irgendeiner nicht-negativen Zahl beginnen, trotzdem sind alle BasisIndices außer 0 nicht erlaubt.

Wenn indizierte Arrays mit der Array -Funktion deklariert werden, muß ein folgendes Leerzeichen nach jeder Kommabegrenzung hinzugefügt werden, um die Lesbarkeit zu erhöhen:

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

Es ist bei Verwendung des "array" Konstrukts gestattet, mehrzeilige indizierte Arrays zu definieren. In diesem Fall, muss jede folgende Zeile mit Leerzeichen aufgefüllt werden, so dass der Beginn jeder Zeile ausgerichtet ist:

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

Alternativ kann das beginnende Array-Element in der folgenden Zeile beginnen. Wenn das so ist, sollte es um ein Einrückungslevel tiefer stehen als die Zeile, welche die Array-Deklaration enthält und alle folgenden Zeilen sollten die gleiche Einrückung haben; der schließende Teil sollte in einer eigenen Zeile stehen und das gleiche Einrückungslevel haben wie die Zeile, welche die Array-Deklaration enthält:

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

Wenn die letztere Deklaration verwendet wird, empfehlen wir ein endendes Komma für das letzte Element im Array zu verwenden; das minimiert das Problem beim Hinzufügen von neuen Elements mit zusätzlichen Zeilen und hilft sicherzustellen, dass durch ein fehlendes Komma keine Parsing-Fehler auftreten.

Assoziative Arrays

Wenn assoziative Arrays mit dem Array -Konstrukt deklariert werden, ist das Umbrechen der Anweisung in mehrere Zeilen gestattet. In diesem Fall muss jede folgende Zeile mit Leerraum aufgefüllt werden, so dass sowohl der Schlüssel und der Wert untereinander stehen:

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

Alternativ kann das beginnende Array-Element in der folgenden Zeile beginnen. Wenn das so ist, sollte es um ein Einrückungslevel tiefer stehen als die Zeile, welche die Array-Deklaration enthält und alle folgenden Zeilen sollten die gleiche Einrückung haben; der schließende Teil sollte in einer eigenen Zeile stehen und das gleiche Einrückungslevel haben wie die Zeile, welche die Array-Deklaration enthält. Wegen der Lesbarkeit sollten die verschiedenen "=>" Operatoren so eingerückt werden, dass sie untereinander stehen.

  1. $sampleArray = array(
  2.     'firstKey'  => 'firstValue',
  3.     'secondKey' => 'secondValue',
  4. );

Wenn die letztere Deklaration verwendet wird, empfehlen wir ein endendes Komma für das letzte Element im Array zu verwenden; das minimiert das Problem beim Hinzufügen von neuen Elements bei zusätzlichen Zeilen und hilft sicherzustellen, dass durch ein fehlendes Komma keine Parsing-Fehler auftreten.

Klassen

Klassen-Deklarationen

Klassen müssen entsprechend der Zend Framework Namenskonvention benannt werden.

Die Klammer sollte immer in der Zeile unter dem Klassennamen geschrieben werden.

Jede Klasse muss einen Dokumentationsblock haben der dem PHPDocumentor-Standard entspricht.

Jeder Code in der Klasse muss mit vier Leerzeichen eingerückt sein.

Nur eine Klasse ist in jeder PHP-Datei gestattet.

Das Platzieren von zusätzlichem Code in Klassendateien ist gestattet, aber es wird davon abgeraten. In solchen Dateien müssen zwei leere Zeilen die Klasse von jedem zusätzlichen PHP-Code in der Datei trennen.

Das folgende ist ein Beispiel einer akzeptierbaren Klassendeklaration:

  1. /**
  2. * Dokumentations Block hier
  3. */
  4. class SampleClass
  5. {
  6.     // gesamter Inhalt der Klasse
  7.     // muss mit vier Leerzeichen eingerückt sein
  8. }

Klassen, die andere Klassen erweitern oder welche Interfaces implementieren, sollen ihre Abhängigkeit auf der gleichen Zeile deklarieren, wenn das möglich ist.

  1. class SampleClass extends FooAbstract implements BarInterface
  2. {
  3. }

Wenn als Ergebnis so einer Deklaration, die Länge der Zeile die Maximale Zeilenlänge überschreitet, ist die Zeile vor dem "extends" und oder "implements" Schlüsselwort umzubrechen und diese Zeilen um ein Einrückungslevel einzurücken.

  1. class SampleClass
  2.     extends FooAbstract
  3.     implements BarInterface
  4. {
  5. }

Wenn die Klasse mehrere Interfaces implementiert und die Deklaration die maximale Zeilenlänge übersteigt, ist nach jedem Komma umzubrechen und sind die Interfaces zu separieren und die Namen der Interfaces so einzurücken, dass sie untereinander stehen.

  1. class SampleClass
  2.     implements BarInterface,
  3.                BazInterface
  4. {
  5. }

Klassenvariablen

Klassenvariablen müssen entsprechend den Variablen-Benennungs-Konventionen des Zend Frameworks benannt werden.

Jede Variable, die in der Klasse deklariert wird, muss am Beginn der Klasse vor der Deklaration von allen Methoden aufgelistet werden.

Das var Konstrukt ist nicht gestattet. Klassenvariablen definieren Ihre Sichtbarkeit durch die Verwendung des private, protected oder public Modifikatoren. Das Gestatten von direktem Zugriff auf Klassenvariablen durch deren Deklaration als public ist gestattet, aber es wird davon abgeraten, da hierfür Zugriffsmethoden verwendet werden sollten (set & get).

Funktionen und Methoden

Deklaration von Funktionen und Methoden

Funktionen müssen nach der Funktions-Namenskonvention des Zend Frameworks benannt werden.

Methoden innerhalb von Klassen müssen immer ihre Sichtbarkeit durch Verwendung einer der private, protected, oder public Modifikatoren definieren.

Wie bei Klassen, sollte die Klammer immer in der Zeile unterhalb des Funktionsnamens geschrieben werden. Leerzeichen zwischen dem Funktionsnamen und der öffnenden Klammer für die Argumente sind nicht erlaubt.

Von Funktionen im globalen Raum wird komplett abgeraten.

Das folgende ist ein Beispiel einer akzeptierbaren Funktionsdeklaration in einer Klasse:

  1. /**
  2. * Dokumentations Block hier
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Dokumentations Block hier
  8.      */
  9.     public function bar()
  10.     {
  11.         // gesamter Inhalt der Funktion
  12.         // muss durch view Leerzeichen eingerückt sein
  13.     }
  14. }

In den Fällen wo die Liste der Argumente die maximale Zeilenlänge überschreitet, sollten Zeilenumbrüche eingeführt werden. Zusätzliche Argumente der Funktion oder Methode müssen durch einen zusätzlichen Einrückungslevel nach der Funktion oder Methodendeklaration eingerückt werden. Ein Zeilenumbruch sollte dann vor dem schließenden Argument stattfinden, welcher in der gleichen Zeile platziert werden sollte wie die öffnende Klammer der Funktion oder Methode mit einem einzelnen Leerzeichen das die zwei trennt, und mit dem gleichen Einrückungslevel wie die Deklaration der Funktion oder Methode. Das folgende ist ein Beispiel so einer Situation:

  1. /**
  2. * Dokumentations Block Hier
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Dokumentations Block Hier
  8.      */
  9.     public function bar($arg1, $arg2, $arg3,
  10.         $arg4, $arg5, $arg6
  11.     ) {
  12.         // gesamter Inhalt der Funktion
  13.         // muss durch view Leerzeichen eingerückt sein
  14.     }
  15. }

Note: Notiz: Die Übergabe per Referenz ist der einzige erlaubt Mechanismus für die Übergabe von Parametern in der Deklaration einer Funktion:

  1. /**
  2. * Dokumentations Block hier
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * Dokumentations Block hier
  8.      */
  9.     public function bar(&$baz)
  10.     {}
  11. }

Der Aufruf durch Referenz ist nicht gestattet.

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

  1. /**
  2. * Dokumentations Block hier
  3. */
  4. class Foo
  5. {
  6.     /**
  7.      * FALSCH
  8.      */
  9.     public function bar()
  10.     {
  11.         return($this->bar);
  12.     }
  13.  
  14.     /**
  15.      * RICHTIG
  16.      */
  17.     public function bar()
  18.     {
  19.         return $this->bar;
  20.     }
  21. }

Verwendung von Funktionen und Methoden

Funktionsargumente sollten durch ein einzelnes trennendes Leerzeichen nach dem Komma-Trennzeichen getrennt werden. Das folgende ist ein Beispiel für einen akzeptierbaren Aufruf einer Funktion, die drei Argumente benötigt:

  1. threeArguments(1, 2, 3);

Übergabe von Referenzen zur Laufzeit ist strengstens verboten. Siehe die Sektion für Funktionsdeklarationen für den richtigen Weg um Funktionsargumente per Referenz zu übergeben.

Durch die Übergabe von Arrays als Argument für eine Funktion, kann der Funktionsaufruf den "array" Hinweis enthalten und kann in mehrere Zeilen geteilt werden, um die Lesbarkeit zu erhöhen. In solchen Fällen sind die normalen Richtlinien für das Schreiben von Arrays trotzdem noch anzuwenden:

  1. threeArguments(array(1, 2, 3), 2, 3);
  2.  
  3. threeArguments(array(1, 2, 3, 'Zend', 'Studio',
  4.                      $a, $b, $c,
  5.                      56.44, $d, 500), 2, 3);
  6.  
  7. threeArguments(array(
  8.     1, 2, 3, 'Zend', 'Studio',
  9.     $a, $b, $c,
  10.     56.44, $d, 500
  11. ), 2, 3);

Kontrollanweisungen

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

Innerhalb der bedingten Anweisungen zwischen den Klammern, müssen die Operationen, für die Lesbarkeit, durch Leerzeichen getrennt werden. Innere Klammern sind zu befürworten um die logische Gruppierung für größeren bedingte Anweisungen 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ß durch Verwendung von vier Leerzeichen eingerückt werden.

  1. if ($a != 2) {
  2.     $a = 2;
  3. }

Wenn die Kontrollanweisung die Ursache für eine Überschreitung der maximalen Zeilenlänge ist, und sie mehrere Anweisungen hat, kann die Kontrollanweisung in mehrere Zeilen gebrochen werden. In solchen Fällen, ist die Zeile vor dem logischen Operator zu brechen und die Zeile so einzurücken das sie unter dem ersten Zeichen der Kontrollanweisung steht. Der schließende Teil der Kontrollanweisung ist mit der öffnenden Klammer in einer eigenen Zeile zu platzieren, wobei ein einzelnes Leerzeichen die zwei trennen muß, und der Einrückungslevel identisch mit der öffenden Kontrollanweisung sein ist.

  1. if (($a == $b)
  2.     && ($b == $c)
  3.     || (Foo::CONST == $d)
  4. ) {
  5.     $a = $d;
  6. }

Die Einrückung des späteren Deklarationsformats dient der Vorbeugung von Problemen beim Hinzufügen oder Entfernen von Klauseln von der Kontrollanweisung bei späteren Revisionen.

Für "if" Anweisungen die "elseif" oder "else" beinhalten, sind die Konventionen der Formatierung ähnlich dem "if" Konstrukt. Das folgende Beispiel zeigt gültige Formatierungen für "if" Anweisungen mit "else" und/oder "elseif" Konstrukten:

  1. if ($a != 2) {
  2.     $a = 2;
  3. } else {
  4.     $a = 7;
  5. }
  6.  
  7. if ($a != 2) {
  8.     $a = 2;
  9. } elseif ($a == 3) {
  10.     $a = 4;
  11. } else {
  12.     $a = 7;
  13. }
  14.  
  15. if (($a == $b)
  16.     && ($b == $c)
  17.     || (Foo::CONST == $d)
  18. ) {
  19.     $a = $d;
  20. } elseif (($a != $b)
  21.           || ($b != $c)
  22. ) {
  23.     $a = $c;
  24. } else {
  25.     $a = $b;
  26. }

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

Switch

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

Jeglicher Inhalt innerhalb der "switch" Anweisung muß durch Verwendung von vier Leerzeichen eingerückt sein. Der Inhalt unter jeder "case" Anweisung muß durch Verwendung von vier zusätzlichen Leerzeichen eingerückt werden.

  1. switch ($numPeople) {
  2.     case 1:
  3.         break;
  4.  
  5.     case 2:
  6.         break;
  7.  
  8.     default:
  9.         break;
  10. }

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

Note: Notiz: Es ist machmal nützlich eine case-Anweisung zu schreiben, die durch das nächste case fällt, indem innerhalb solcher Fälle kein break oder return angegeben wird. Um diese Fälle von Fehlern zu unterscheiden, sollte jede case-Anweisung, in der break oder return unterlassen werden, einen Kommentar enthalten, der anzeigt, dass das break gewünschtermaßen unterdrückt wurde.

Inline Dokumentation

Dokumentationsformat

Alle Dokumentationsblöcke ("DocBlock") müssen mit dem phpDocumentor-Format kompatibel sein. Die Beschreibung des phpDocumentor-Formats ist nicht Thema dieses Dokuments. Für weiterführende Informationen siehe: » http://phpdoc.org">

Alle Klassendateien müssen einen "file-level" Docblock am Beginn jeder Datei und einen "class-level" Docblock direkt oberhalb jeder Klasse enthalten. Beispiele solcher Docblocks können im folgenden gefunden werden.

Dateien

Jede Datei, die PHP Code enthält, muss einen Docblock am Beginn der Datei besitzen, welcher mindestens diese phpDocumentor-Tags enthält:

  1. /**
  2. * Kurze Beschreibung der Datei
  3. *
  4. * Lange Beschreibung der Datei (wenn vorhanden)...
  5. *
  6. * LICENSE: Einige Lizenz Informationen
  7. *
  8. * @category   Zend
  9. * @package    Zend_Magic
  10. * @subpackage Wand
  11. * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
  12. * @license    http://framework.zend.com/license   BSD License
  13. * @version    $Id:$
  14. * @link       http://framework.zend.com/package/PackageName
  15. * @since      Datei vorhanden seit Release 1.2.0
  16. */

Das @category Tag muß den Wert "Zend" haben.

Das @package Tag muß hinzugefügt sein, und sollte mit dem Namen der Komponente identisch sein, dessen Klasse in der Datei enthalten ist; typischerweise wird dieser zwei Segmente haben, das Präfix "Zend", und den Namen der Komponente.

Das @subpackage Tag ist optional. Wenn es angegeben wird, sollte es der Name der Subkomponente sein, ohne das Präfix der Klasse. Im obigen Beispiel ist die Annahme, dass die Klasse in der Datei entweder "Zend_Magic_Wand" ist oder den Klassennamen als Teil seines Präfixes verwendet.

Klassen

Jede Klasse muss einen Docblock haben, welcher mindestens diese phpDocumentor Tags enthält:

  1. /**
  2. * Kurze Beschreibung für die Klasse
  3. *
  4. * Lange Beschreibung für die Klasse (wenn vorhanden)...
  5. *
  6. * @category   Zend
  7. * @package    Zend_Magic
  8. * @subpackage Wand
  9. * @copyright  Copyright (c) 2005-2011 Zend Technologies USA Inc. (http://www.zend.com)
  10. * @license    http://framework.zend.com/license   BSD License
  11. * @version    Release: @package_version@
  12. * @link       http://framework.zend.com/package/PackageName
  13. * @since      Klasse vorhanden seit Release 1.5.0
  14. * @deprecated Klasse abgeraten ab Release 2.0.0
  15. */

Das @category Tag muß den Wert "Zend" haben.

Das @package Tag muß hinzugefügt sein, und sollte mit der Komponente identisch sein, der die Klasse gehört; typischerweise wird dieser zwei Segmente haben, den Präfix "Zend", und den Namen der Komponente.

Das @subpackage Tag ist optional. Wenn es angegeben wird, sollte es der Name der Subkomponente sein, ohne das Präfix der Klasse. Im obigen Beispiel ist die Annahme, dass die Klasse in der Datei entweder "Zend_Magic_Wand" ist oder den Klassennamen als Teil seines Präfixes verwendet.

Funktionen

Jede Funktion, auch Objektmethoden, 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" Modifikator bekannt ist, wenn die Funktion deklariert wird.

Wenn eine Funktion oder Methode eine Ausnahme werfen könnte, muß @throws für alle bekannten Exception Klassen verwendet werden:

  1. @throws exceptionclass [Beschreibung]
Namenskonventionen
Zend Framework Coding Standard für PHP
Programmer's Reference Guide