PHP
PHPDoc

Syntax

• @api
• @author [Name] [<E-Mail-Adresse>]
• @copyright <Beschreibung>
• @deprecated [<"Semantic Version">] [: <"Semantic Version">] [<description>]
• @example [URI] [<description>]
• {@example [URI] [: <start> .. <end>]}
• @inheritDoc
• @internal
• {@interne [Beschreibung]}}
• @license [<SPDX-Kennung> | URI] [Name]
• @method [return "Type"] [Name] (["Type"] [Parameter], [...]) [Beschreibung]
• @Paket [Ebene 1] \ [Ebene 2] \ [etc.]
• @param ["Typ"] [Name] [<Beschreibung>]
• @ property ["Type"] [name] [<description>]
• @return <"Type"> [Beschreibung]
• @see [URI | "FQSEN"] [<description>]
• @since [<"Semantic Version">] [<description>]
• @throws ["Typ"] [<description>]
• @Todo [Beschreibung]
• @uses [Datei | "FQSEN"] [<description>]
• @var ["Typ"] [Elementname] [<Beschreibung>]
• @version ["Semantic Version"] [<description>]
• @filesource - Schließt die aktuelle Datei in die Analyseergebnisse von phpDocumentor ein
• @link [URI] [<description>] - Das Link-Tag hilft beim Definieren der Beziehung oder Verknüpfung zwischen Strukturelementen .

Bemerkungen

/**
 *
 */

Metadaten zu Funktionen hinzufügen

Anmerkungen auf Funktionsebene helfen IDEs, Rückgabewerte oder möglicherweise gefährlichen Code zu identifizieren

/**
 * Adds two numbers together.
 *
 * @param Int $a First parameter to add
 * @param Int $b Second parameter to add
 * @return Int
 */
function sum($a, $b)
{
    return (int) $a + $b;
}

/**
 * Don't run me! I will always raise an exception.
 *
 * @throws Exception Always
 */
function dangerousCode()
{
    throw new Exception('Ouch, that was dangerous!');
}

/**
 * Old structures should be deprecated so people know not to use them.
 *
 * @deprecated
 */
function oldCode()
{
    mysql_connect(/* ... */);
}

Metadaten zu Dateien hinzufügen

Metadaten auf Dateiebene gelten für den gesamten Code in der Datei und sollten am Anfang der Datei stehen:

<?php

/**
 * @author John Doe ([email protected])
 * @copyright MIT
 */

Vererbung von Metadaten aus übergeordneten Strukturen

Wenn eine Klasse eine andere Klasse erweitert und dieselben Metadaten verwenden würde, ist die Bereitstellung von @inheritDoc eine einfache Möglichkeit, dieselbe Dokumentation zu verwenden. Wenn mehrere Klassen von einer Basis erben, muss nur die Basis geändert werden, damit die Kinder betroffen sind.

abstract class FooBase
{
    /**
     * @param Int $a First parameter to add
     * @param Int $b Second parameter to add
     * @return Int
     */
    public function sum($a, $b) {}
}

class ConcreteFoo extends FooBase
{
    /**
     * @inheritDoc
     */
    public function sum($a, $b)
    {
        return $a + $b;
    }
}

Eine Variable beschreiben

Das @var Schlüsselwort kann verwendet werden, um den Typ und die Verwendung von zu beschreiben:

• eine Klasseneigenschaft
• eine lokale oder globale Variable
• eine Klasse oder globale Konstante

class Example {
    /** @var string This is something that stays the same */
    const UNCHANGING = "Untouchable";

    /** @var string $some_str This is some string */
    public $some_str;

    /**
     * @var array $stuff    This is a collection of stuff
     * @var array $nonsense These are nonsense
     */
    private $stuff, $nonsense;

    ...
}

Der Typ kann einer der integrierten PHP-Typen sein oder eine benutzerdefinierte Klasse, einschließlich Namespaces.

Der Name der Variablen sollte enthalten sein, kann aber weggelassen werden, wenn der Docblock nur für ein Element gilt.

Parameter beschreiben

 /**
 * Parameters
 * 
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param($int, $string, $array, $bool)
{
}

 /**
 * Parameters - Optional / Defaults
 *
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false)
{
}

/**
 * Parameters - Arrays
 * 
 * @param array          $mixed
 * @param int[]          $integers
 * @param string[]       $strings
 * @param bool[]         $bools
 * @param string[]|int[] $strings_or_integers
 */
function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers)
{
}

/**
 * Parameters - Complex
 * @param array $config 
 * <pre>
 * $params = [
 *         'hostname'     => (string) DB hostname. Required.
 *         'database'     => (string) DB name. Required.
 *         'username'     => (string) DB username. Required.
 * ]
 * </pre>
 */
function demo_param_complex($config)
{
}

Sammlungen

PSR-5 bietet eine Form von Notics im generischen Stil für Sammlungen.

Generics-Syntax

Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>

Werte in einer Collection können sogar ein anderes Array und sogar eine andere Collection sein.

Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>

Beispiele

<?php

/** 
 * @var ArrayObject<string> $name 
 */
$name = new ArrayObject(['a', 'b']);

/** 
 * @var ArrayObject<int> $name 
 */
$name = new ArrayObject([1, 2]);

/** 
 * @var ArrayObject<stdClass> $name 
 */
$name = new ArrayObject([
    new stdClass(), 
    new stdClass()
]);

/** 
 * @var ArrayObject<string|int|stdClass|bool> $name 
 */
$name = new ArrayObject([
    'a', 
    true, 
    1, 
    'b', 
    new stdClass(), 
    'c', 
    2
]);

/**
 * @var ArrayObject<ArrayObject<int>> $name 
 */
$name = new ArrayObject([
    new ArrayObject([1, 2]), 
    new ArrayObject([1, 2])
]);

/** 
 * @var ArrayObject<int, string> $name 
 */
$name = new ArrayObject([
    1 => 'a', 
    2 => 'b'
]);

/** 
 * @var ArrayObject<string, int> $name 
 */
$name = new ArrayObject([
    'a' => 1, 
    'b' => 2
]);

/** 
 * @var ArrayObject<string, stdClass> $name 
 */
$name = new ArrayObject([
    'a' => new stdClass(), 
    'b' => new stdClass()
]);