PHP Doc（PHPDoc）とは？

前書き

PHPDoc は、PHPのソースコードにコメントとして記述するドキュメンテーション（文書化）スタイルのことです。
これは、関数、クラス、メソッド、プロパティなどに対する説明を記述するために使用され、コードの可読性やメンテナンス性を向上させるために重要です。

PHPDocは、Javadoc（Javaのドキュメントコメント） に似た形式を持っており、
一般的に /** ... */ のブロックコメントとして記述されます。

PHPDocの基本構造

php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


/**
 * 関数の説明（概要）
 *
 * 詳細な説明（オプション）
 *
 * @param 型 $引数名 説明
 * @return 型 説明
 * @throws 例外クラス 説明（オプション）
 */
function sampleFunction(int $num): string {
    return "Number: " . $num;
}

PHPDocで使われる主要なタグ

1. `@param`（パラメータの説明）

関数やメソッドの引数を説明するために使用します。

php

1
2
3
4
5
6
7
8
9


/**
 * 数値を文字列に変換する関数
 *
 * @param int $num 変換する数値
 * @return string 変換後の文字列
 */
function convertToString(int $num): string {
    return (string)$num;
}

2. `@return`（戻り値の説明）

関数の戻り値の型とその説明を記述します。

php

1
2
3
4
5
6
7
8


/**
 * 現在の時刻を取得する関数
 *
 * @return string 現在の時刻（フォーマット: H:i:s）
 */
function getCurrentTime(): string {
    return date("H:i:s");
}

3. `@throws`（例外の説明）

関数やメソッドがスローする可能性のある例外を示します。

php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


/**
 * 0で割り算をしないようにする関数
 *
 * @param int $a 割られる数
 * @param int $b 割る数（0はエラー）
 * @return float 割り算の結果
 * @throws Exception 割る数が0の場合に発生
 */
function divide(int $a, int $b): float {
    if ($b === 0) {
        throw new Exception("0で割ることはできません。");
    }
    return $a / $b;
}

4. `@var`（プロパティの型情報）

クラスのプロパティの型を明示するために使います。

php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class User {
    /**
     * @var string ユーザーの名前
     */
    private string $name;

    /**
     * コンストラクタ
     *
     * @param string $name ユーザーの名前
     */
    public function __construct(string $name) {
        $this->name = $name;
    }
}

5. `@property`（動的プロパティの型情報）

マジックメソッド __get() を使ってプロパティを動的に取得する場合に、型情報を明示するために使用されます。

php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


/**
 * @property string $name ユーザー名
 * @property int $age 年齢
 */
class User2 {
    private array $data = [];

    public function __get($name) {
        return $this->data[$name] ?? null;
    }

    public function __set($name, $value) {
        $this->data[$name] = $value;
    }
}

6. `@deprecated`（非推奨のメソッドや関数のマーク）

古いメソッドや推奨されないメソッドに対して警告を出すために使用されます。

php

1
2
3
4
5
6
7
8


/**
 * この関数は非推奨です。代わりに newFunction() を使用してください。
 *
 * @deprecated 1.0.0 代わりに newFunction() を使用
 */
function oldFunction() {
    echo "この関数は非推奨です。";
}

7. `@see`（関連する関数やクラスを示す）

関連する関数やクラスを参照するために使用されます。

php

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


/**
 * 文字列を大文字に変換する
 *
 * @see strtolower() 小文字に変換する関数
 *
 * @param string $str 変換する文字列
 * @return string 変換後の文字列
 */
function toUpperCase(string $str): string {
    return strtoupper($str);
}

PHPDocを活用するメリット

IDEの補助機能が強化される
- PHPStormやVSCodeなどのIDEでは、PHPDocを解析して関数の引数や戻り値の型を補完・表示してくれる。
メンテナンス性の向上
- コードの意図や仕様が明確になり、後から見ても理解しやすくなる。
静的解析ツール（PHPStan, Psalmなど）と連携できる
- PHPStanやPsalmを使うと、PHPDocをもとに型チェックを強化できる。
APIドキュメントの自動生成が可能
- phpDocumentor などのツールを使って、PHPDocコメントをもとにHTML形式のAPIドキュメントを生成できる。

PHPDocを使ったドキュメントの自動生成

PHPDocのコメントを使って、自動的にドキュメントを生成するツールがあります。

phpDocumentor をDockerコンテナで実行

事前準備

上記のソースコードを全てtest-doc.phpに貼り付けてsrcディレクトリに配置します。
下記の構成になっていればOKです。

sh

1
2
3
4


$ tree .
.
└── src
    └── test-doc.php

基本的な実行方法

以下のコマンドを実行すると、srcディレクトリにあるPHPファイルのドキュメントをdocsフォルダに生成できます。

sh

1

docker run --rm -v $(pwd):/data phpdoc/phpdoc:latest -d src -t docs

💡 オプション解説

-v $(pwd):/data : カレントディレクトリをコンテナの /data にマウント
phpdoc/phpdoc:latest : 公式のphpDocumentorの最新Dockerイメージを使用
-d src : ドキュメント生成の対象ディレクトリ（src は適宜変更）
-t docs : 生成されたドキュメントの出力先

ドキュメントを確認

成功すると、docs ディレクトリにHTMLファイルが生成されます。

ローカル環境で確認するには、docs ディレクトリを nginx などのWebサーバーで公開すれば確認できます。

例えば下記のようにdocsディレクトリをマウントしてnginxのコンテナを立ち上げます。

sh

1

docker run --rm -v $(pwd)/docs:/usr/share/nginx/html -p 8000:80 nginx

ブラウザで http://localhost:8000/ にアクセスすると、生成されたドキュメントを確認できます。

下記のようなページが表示されれば成功です。

まとめ

PHPDocは、PHPのコードを文書化するための仕組みであり、IDEのサポートを受けたり、静的解析を強化したりするために役立ちます。
特に LaravelやSymfonyなどのフレームワークでも広く利用されており、チーム開発やコードレビューにおいても非常に重要 です。

💡 ポイント

@param で引数の型と説明を記述
@return で戻り値の型と説明を記述
@throws で例外を明示
@deprecated で非推奨のメソッドをマーク
phpDocumentor を使ってドキュメントを自動生成

PHPでの開発を効率化するために、PHPDocを活用してみてください！

PHP Doc（PHPDoc）とは？

前書き

PHPDocの基本構造

PHPDocで使われる主要なタグ

1. @param（パラメータの説明）

2. @return（戻り値の説明）

3. @throws（例外の説明）

4. @var（プロパティの型情報）

5. @property（動的プロパティの型情報）

6. @deprecated（非推奨のメソッドや関数のマーク）

7. @see（関連する関数やクラスを示す）