この記事は、Laravelで使えるプログラム処理内容の説明ドキュメント（処理機能記述書）生成ツールの紹介です。
はじめに
PHPer皆さん、ドキュメント書いてますか？処理フロー確認やレビュー、他人が作ったプログラムの理解を深めるためにドキュメントは大きな助けになります。一方で、Excelでドキュメントを作ってくださいとか、プログラム変更時にメンテナンスしなければいけないとか、とにかくメンドくさいですよね。このメンドくさいを減らすために、コントローラーに処理説明を書くだけでExcelドキュメント（処理機能記述書）を生成するツールを開発しました。
仕組み
Laravelのコントローラーに、コメントのような処理説明を書いて実行する（画面を表示するなど）とミドルウェアがExcelドキュメントを生成します。
準備
1. インストール
Laravelがインストールされている環境に、composerでインストールしてください。
composer require blocs/docs
2. docsをコピー
vendor/blocs/docs の下の docs をLaravelのルートにコピーします。docs/format.xlsx がフォーマットExcelで、common.php や *Controller.php が設定ファイルです。
ドキュメント生成
1. 処理説明を書く
docs() で、コントローラーに処理説明を書きます。処理説明を実行した順にドキュメントに出力します。
class TestController extends Controller
{
public function index()
{
docs('# 画面表示');
docs('テンプレートを読み込んで、HTMLを生成');
return view('welcome');
}
}
2. ルーティング
ドキュメントを生成したいルートの middleware に Blocs\Middleware\Docs::class を設定します。
Route::get('/', [TestController::class, 'index'])->middleware(Blocs\Middleware\Docs::class);
ミドルウェアのエイリアスを指定しておくと、簡単にミドルウェアを設定できます。
->withMiddleware(function (Middleware $middleware) {
$middleware->alias([
'docs' => Blocs\Middleware\Docs::class
]);
})
Route::get('/', [TestController::class, 'index'])->middleware('docs');
3. ドキュメント生成
middleware を設定したルートにアクセスすると、docs/format.xlsx を使って docs にExcelドキュメントを生成します。Excelドキュメントはルートごとに生成します。
ドキュメントは、IPO（Input: 入力、Process: 処理機能、Output: 出力）形式で出力します。システム名、成果物名、作成者は docs/format.xlsx を編集して指定します。画面名、メソッド概要は設定ファイルで指定します。作成日、メソッドは自動で出力されます。
docsの書き方
# 画面表示 のように # から始めると、処理の見出しになります。
docs('# 画面表示');
docs の引数が1つの時は処理機能、引数が複数の時は入力、処理機能、出力になります。入力、出力は連想配列で指定します。複数の処理機能を配列で指定することもできます。
docs(['POST' => '入力値'], '入力値を以下の条件で検証して、エラーがあればメッセージをセット');
docs(null, 'エラーがあれば、ログイン画面に戻る', ['FORWARD' => 'admin.user.login']);
複数の入力(例：POSTとデータベース)、出力を指定することもできます。
docs(['POST' => '旧パスワード', 'データベース' => 'ユーザー管理'], '<旧パスワード>があれば、<ユーザー管理>をチェック');
設定ファイルの書き方
設定ファイルでキーワード置換や非表示の指定ができます。common.php は全コントローラー共通の設定ファイル、*Controller.php はコントローラーごとの設定ファイルです。*Controller.php にメソッドごとの設定も書けます。
| 設定項目 | 説明 | サンプル |
|---|---|---|
| description | 画面名、メソッド概要 | 'description' => 'テスト画面' |
| keyword | テーブル名、項目名など置換するキーワード | 'keyword' => ['name' => '名前'] |
| neglect | 非表示 | 'neglect' => ['<名前>をセッションに保存'] |
| comment | 追加コメント | 'comment' => ['<名前>を表示' => 'フリガナも表示'] |
$config = [
'description' => 'テスト画面',
'keyword' => ['name' => '名前'],
'neglect' => ['<名前>をセッションに保存'],
'comment' => ['<名前>を表示' => 'フリガナも表示'],
'index' => [
'description' => '一覧画面表示',
],
];
docs('<name>を取得');
docs('<name>をセッションに保存');
docs('<name>を表示');
おわりに
最後まで読んでいただき、ありがとうございました。
いつもドキュメント作成はメンドーだなと感じていたので、ドキュメント生成ツールを作ってみました。このツールがPHPer皆さんのドキュメント作成をサポートできればいいなと思っています。