PHP
PHPDoc

構文

• @api
• @author [name] [<email address>]
• @copyright <description>
• @deprecated [<"セマンティックバージョン">] [：<"セマンティックバージョン">] [<description>]
• @example [URI] [<description>]
• {@example [URI] [：<start> .. <end>]}
• @inheritDoc
• @内部
• {@内部[説明]}}
• @license [<SPDX識別子> | URI] [名前]
• @method [return "Type"] [name]（["Type"] [パラメータ]、[...]）[説明]
• @package [レベル1] \ [レベル2] \ [etc。]
• @param ["Type"] [name] [<description>]
• @property ["Type"] [name] [<description>]
• @return <"Type"> [description]
• @see [URI | "FQSEN"] [<description>]
• @since [<""セマンティックバージョン ">] [<description>]
• @throws ["Type"] [<description>]
• @todo [説明]
• @uses [ファイル| "FQSEN"] [<description>]
• @var ["Type"] [element_name] [<description>]
• @version ["セマンティックバージョン"] [<description>]
• @filesource - 現在のファイルをphpDocumentorまたは解析結果に含めます
• @link [URI] [<description>] - リンクタグは、 構造要素間の関係やリンクを定義するのに役立ちます。

備考

/**
 *
 */

関数にメタデータを追加する

関数レベルの注釈は、IDEが戻り値または潜在的に危険なコードを識別するのに役立ちます

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

ファイルにメタデータを追加する

ファイルレベルのメタデータは、ファイル内のすべてのコードに適用され、ファイルの先頭に配置する必要があります。

<?php

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

親構造からのメタデータの継承

クラスが別のクラスを拡張して同じメタデータを使用する場合、 @inheritDoc提供することは同じドキュメントを使用する簡単な方法です。複数のクラスが基底から継承する場合、影響を受ける子を変更するために基底のみを変更する必要があります。

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

変数の記述

@varキーワードを使用して、以下のタイプと使用方法を記述できます。

• クラスプロパティ
• ローカル変数またはグローバル変数
• クラスまたはグローバル定数

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;

    ...
}

型は、組み込みのPHP型のいずれか、または名前空間を含むユーザー定義のクラスのいずれかです。

変数の名前を含める必要がありますが、docblockが1つの項目にのみ適用される場合は省略できます。

パラメータの記述

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

コレクション

PSR-5は、コレクションのジェネリックス形式の記法を提案しています。

ジェネリックスの構文

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

コレクション内の値は別の配列であっても、別のコレクションであってもよい（MAY）。

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

例

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