Was sind Annotationen?
Das Wort Annotationen kommt aus dem Lateinischen annotatio und bedeutet wörtlich „Anmerkung“ oder „Bemerkung“. Annotationen sind spezielle Kommentare im Quellcode, die mit einem @ beginnen und zusätzliche Informationen zu einer Funktion oder Methode liefern. Sie stehen meist direkt oberhalb einer Funktion im PHPDoc-Block (also zwischen /** … */).
Diese Annotationen werden nicht vom PHP-Interpreter ausgewertet, sondern dienen der eigenen Dokumentation, der automatischen Codeauswertung (z. B. durch einen
Parser
Ein Parser (von englisch to parse = „analysieren“, „zerlegen“) ist ein Programmteil, der Text in kleinere Einheiten zerlegt, um ihn besser zu verstehen und weiterzuverarbeiten.
Ein Parser nimmt z. B. Quellcode oder Daten entgegen und erkennt darin bestimmte Strukturen – wie Funktionen, Annotationen oder Parameter. Dadurch kann der Code automatisch dokumentiert, analysiert oder in etwas anderes umgewandelt werden.
Beispiel:
Ein Parser liest einen PHP-Quelltext ein und erkennt:
- wo eine Funktion beginnt,
- welche Annotationen davor stehen (z. B. @acl),
- welche Parameter übergeben werden,
- und welche Beschreibung dazu gehört.
Diese Informationen kann er dann z. B. in einer Referenzseite anzeigen oder zur Prüfung verwenden.
) und der späteren Verarbeitung in der Oberfläche. So kann man z. B. definieren, welche Rolle Zugriff auf eine Funktion hat (@acl), ob Eingaben validiert sind (@validated) oder ob die Funktion veraltet ist (@deprecated).
Vorteil: Statt Informationen doppelt zu pflegen – im Code und in externen Dokumentationen – kann alles an einer Stelle notiert werden. Der Parser kann daraus später automatisch eine strukturierte, verständliche und filterbare Referenz erzeugen.
Kurz: Annotationen sind strukturierte Zusatzinformationen im Quellcode, die ihn verständlicher machen und automatisierte Prozesse unterstützen können.
Die hier aufgeführten Annotationen können flexibel erweitert oder angepaßt werden, je nachdem, welche Informationen im Code sichtbar gemacht und zentral ausgewertet werden sollen.
Damit sie später auch einen Nutzen ergeben, muß der jeweilige PHPDoc- Parser sie natürlich unterstützen!
Zugriff & Sichtbarkeit
@acl rolle – Gibt an, welche Rolle Zugriff hat. Beispiel: @acl administranto
@public – Öffentliche Methode/API, auch für externe Nutzung geeignet.
@internal – Intern gedacht, nicht für externe Nutzung vorgesehen.
Sicherheit
@secure – Methode nutzt vorbereitete Abfragen oder andere Schutzmechanismen.
@validated – Übergabeparameter werden geprüft (z. B. Typ, Format).
@encrypted – Es werden verschlüsselte Daten verarbeitet oder gespeichert.
Wartung & Entwicklung
@deprecated – Veraltet, soll nicht mehr verwendet werden.
@todo – Offene Aufgabe oder geplante Erweiterung.
@experimental – Noch instabil, API kann sich ändern.
@see – Verweis auf verwandte Methode(n) oder Klassen. Beispiel: @see getBenutzerBySession()
Allgemeine PHPDoc-Annotationen
@param – Beschreibt einen Funktionsparameter mit Typ und Zweck.
Beispiel: @param string $benutzername Der Name des Benutzers
@return – Gibt den Rückgabetyp und ggf. eine Beschreibung an.
Beispiel: @return bool True bei Erfolg, sonst false
@throws – Gibt an, welche Exceptions ausgelöst werden können.
Beispiel: @throws InvalidArgumentException
@see – Verweist auf verwandte Funktionen oder Dokumentation.
Beispiel: @see checkLogin()
@link – Verlinkt eine externe Quelle oder Dokumentation.
Beispiel: @link https://www.php.net/manual/de/
@example – Beispielhafte Anwendung der Methode.
Beispiel: @example getBenutzer.php
@since – Seit welcher Version existiert diese Methode.
Beispiel: @since 2.1.0
@author – Autor oder Team.
Beispiel: @author Mac
@version – Version der Funktion oder Datei.
Beispiel: @version 1.0.3
@license – Lizenz, unter der die Datei steht.
Beispiel: @license MIT
@internal – Nicht für öffentliche Nutzung vorgesehen (nur intern).
@todo – Ausstehende Aufgabe oder zukünftige Verbesserung.
Beispiel: @todo Validierung für Gast-Benutzer
@fixme – Markiert bekannte Probleme, die noch behoben werden müssen.
Beispiel: @fixme Sonderzeichen werden nicht korrekt gefiltert
Codebeispiele
@code ... @endcode – Eingebettetes Beispiel für die Methode.
Beispiel:
function add($a, $b) {
return $a + $b;
}Praxisbeispiele
Annotationen lassen sich direkt in PHP-Dokumentation verwenden:
/**
* @short Lädt die Benutzerliste
* @acl redaktoro
* @secure
* @validated
* @see getBenutzerByID
*/
function ladeBenutzer() {
// ...
}Beispiel für Zugriffsbeschränkung: Nur eingeloggte Admins dürfen diese Funktion aufrufen.
/**
* @short Löscht einen Benutzer aus der Datenbank
* @acl administranto
* @secure
* @validated
* @deprecated
* @module user
*/
function loescheBenutzer($id) {
// ...
}Beispiel für interne Helferfunktion ohne externe Nutzung:
/**
* @short Erstellt einen Eintrag im Log
* @internal
* @category logging
*/
function logEintrag($msg) {
// ...
}Beispiel mit Codeblock (für die Doku-Ausgabe):
/**
* @short Addition zweier Zahlen
* @code
* addiere(2, 3); // ergibt 5
* @endcode
*/
function addiere($a, $b) {
return $a + $b;
}
