PHP
PHPDoc

Syntaxe

• @api
• @author [nom] [<adresse email>]
• @copyright <description>
• @ obsolète [<"Version sémantique">] [: <"Version sémantique">] [<description>]
• @exemple [URI] [<description>]
• {@exemple [URI] [: <début> .. <fin>]}
• @inheritDoc
• @interne
• {@internal [description]}}
• @license [<identifiant SPDX> | URI] [nom]
• @method [return "Type"] [name] (["Type"] [paramètre], [...]) [description]
• @package [niveau 1] \ [niveau 2] \ [etc.]
• @param ["Type"] [nom] [<description>]
• @property ["Type"] [nom] [<description>]
• @return <"Type"> [description]
• @see [URI | "FQSEN"] [<description>]
• @since [<"Version sémantique">] [<description>]
• @throws ["Type"] [<description>]
• @todo [description]
• @usus [fichier | "FQSEN"] [<description>]
• @var ["Type"] [nom_élément] [<description>]
• @version ["Version sémantique"] [<description>]
• @filesource - Inclut le fichier en cours dans les résultats d'analyse phpDocumentor
• @link [URI] [<description>] - La balise de lien aide à définir la relation ou le lien entre les éléments structurels .

Remarques

/**
 *
 */

Ajout de métadonnées aux fonctions

Les annotations au niveau des fonctions aident les EDI à identifier les valeurs de retour ou les codes potentiellement dangereux

/**
 * 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(/* ... */);
}

Ajout de métadonnées aux fichiers

Les métadonnées de niveau fichier s'appliquent à tout le code du fichier et doivent être placées en haut du fichier:

<?php

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

Héritage des métadonnées des structures parentes

Si une classe étend une autre classe et utilise les mêmes métadonnées, la fournir à @inheritDoc est un moyen simple d’utiliser la même documentation. Si plusieurs classes héritent d'une base, seule la base doit être modifiée pour que les enfants soient affectés.

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

Décrire une variable

Le mot clé @var peut être utilisé pour décrire le type et l'utilisation de:

• une propriété de classe
• une variable locale ou globale
• une classe ou constante globale

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;

    ...
}

Le type peut être l'un des types PHP intégrés ou une classe définie par l'utilisateur, y compris les espaces de noms.

Le nom de la variable doit être inclus, mais peut être omis si le bloc de documents s'applique à un seul élément.

Description des paramètres

 /**
 * 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)
{
}

Collections

PSR-5 propose une forme de notation de type générique pour les collections.

Syntaxe des génériques

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

Les valeurs d'une collection PEUVENT même être un autre tableau et même une autre collection.

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

Exemples

<?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()
]);