PHPファイルから画面仕様書の叩きを生成するツールが作りたい〜調査編〜

はじめに

この記事は、

の作業内容をまとめたものになります。

よければ先にこちらを一読してからこの記事に戻っていただけると嬉しいです。

今回やること

今回は、既存のドキュメント生成ツールについて調査した内容をまとめる回になります。

各ツールの公式Docsの確認に加え、テスト環境を作ってデモもやってみましたので、それもまとめてみます。

本編

調査したツールは以下の４つです。
また、そのうち２つのデモを行いました。

phpDocumentor（デモ済み）
phpDox
Laravel API Document Generation
blocs（デモ済み）

結構自分の作りたいものに近いツールが見つかったので、活かせる部分を見つけて取り入れていきたいところです。

phpDocumentor

Home

概要

20年以上前からある、PHPプロジェクトのドキュメントアプリケーション
どんなプロジェクトでも恩恵を受けられる（公式ドキュメントより）
プロジェクト内or指定された範囲を探索して、見つけたPHPファイルの情報を使ってHTMLのドキュメントを生成する
PHPファイル１つごとにHTMLが１つ生成される。また、ドキュメント用のCSSなども作られる
- 生成された時点で結構完成されているため、生成後のドキュメントに何か書き加えたりするのはデザインが崩れる可能性がありそう
各PHPファイル内のfunction, constant, class, interface, trait, class constant, property, methodなどの要素を認識し、これを元にドキュメントが作られる

使い方
Dockerを使う方法と、pharファイルをダウンロードする方法があります。

Docker

Dockerイメージをプル

$ docker pull phpdoc/phpdoc

docker runする（この時、探索する範囲を決めておかないと全探索してしまってめっちゃ時間がかかるので注意。僕はこれで16分待つことになった）

$ docker run --rm -v $(pwd):/data phpdoc/phpdoc -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

phar

https://github.com/phpDocumentor/phpDocumentor/releases　からphpDocumentor.pharをダウンロードする
ダウンロードしたphpDocumentor.pharファイルを実行する

$ php <tools_directory>/phpDocumentor.phar -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>

デモ

SymfonyでPlayGround環境を作って、以下のようなファイルを作りました。

app/
├ src/
│ └ Controller/
│   └ TestController.php
└ templates/
  └ test
    └ index.html.twig

TestController.php

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use function random_int;

class TestController extends AbstractController
{
    #[Route('/test', name: 'test')]
    public function index(): Response
    {
        return $this->render('test/index.html.twig', [
            'number' => random_int(1, 100),
        ]);
    }
}

index.html.twig

<h1>Test Page</h1>

<p>number: {{ number }}</p>

この状態で、ターミナルで以下のコマンドを実行します。
（僕はpharをダウンロードして使いました）

$ php phpDocumentor.phar -d app/src/Controller -t .phpdoc

すると、プロジェクトルートに.phpdocというディレクトリが作成され、中に生成されたドキュメントのデータが格納されていました。
こんな感じで、色んなファイルが生成されます。

phpDocumentor_生成されたディレクトリ.png

この中の、build/classes/App-Controller-TestController.htmlというHTMLファイルが、TestController.phpのドキュメントです。

phpDocument_生成されたドキュメント1.png

概要で説明した通り、ファイル内の要素とattributesに記述した内容をツールが認識して、ドキュメント化しているようですね。

他のディレクトリにもHTMLファイルが格納されていて、それぞれが左のメニューバーから遷移できるページとなっています。

phpDocument_生成されたドキュメント2.png

phpDocument_生成されたドキュメント3.png

phpDox

https://phpdox.net/

概要

PHP-ParserでPHPコードベースに関する情報を収集し、ドキュメントを生成する
生成されるのはXMLファイル
各PHPファイル内のfunction, constant, class, interface, trait, class constant, property, methodなどの要素を認識し、これを元にドキュメントが作られる
annotationの内容も認識され、ドキュメント内に記述される
- 現在PHP7.xまでしか対応されていないようなので、attributesではない

使い方
Composerを使う方法と、pharファイルをダウンロードする方法があります。

Composer

composerコマンドでインストール

$ composer require --dev theseer/phpdox

ターミナルで以下のコマンドを実行する

$ vendor/bin/phpdox --version

phar
1-a. https://github.com/theseer/phpdox/releases/tag/0.12.0からphpdox.pharをダウンロードする

1-b. もしくは、phiveコマンドでインストールする

$ phive install phpdox

ターミナルで以下のコマンドを実行する

$ php <tools_directory>/phpdox --version

また、こちらはローカル環境のデモは用意しなかったのですが、公式サイト上でデモが実行できるようになっていたためそちらを実行してみました。

こんな感じで表示されます。
プロジェクト内の状態を、ドキュメント化してくれるようです。

ページ上部はメニューバーになっており、クリックするとOverviewで表示されていた各項目の詳細を見ることができます。

Laravel API Document Generation

概要

名前の通り、Laravel用のドキュメント生成ツール
APIのドキュメント生成を行う
- Laravelアプリのルーティング情報を認識する
- エンドポイントごとに、phpdocのコメント、リクエストメソッド、パラメータなどを文書化する

使い方
Composerを使ってインストールできます。

Composerコマンドでインストール

$ composer require --dev mpociot/laravel-apidoc-generator

artisanコマンドで実行する

$ php artisan vendor:publish --provider=<provider_class> --tag=apidoc-config

現在、Laravelのv5.7-6.xまでしか対応していないらしく、結構古めでした。

blocs

概要

Controllerで作成したアクションごとにエクセルのドキュメントを生成する
Laravelのコントローラーに処理説明を書くだけで、エクセルドキュメント（処理機能記述書）を生成するミドルウェア（公式ドキュメントより）
ミドルウェアなので、ページにアクセスがあったらドキュメントが生成されるようになっている
アクションメソッド内でドキュメントに表示したい内容を記述できる
生成されるドキュメントはIPO（Input, Process, Output）形式
完成された状態で生成するphpDocumentorと異なり、雛形のような状態で生成される

使い方
Composerを使ってインストールできます。

Composerコマンドでインストール

$ composer require blocs/docs

blocs/docsミドルウェアとして登録
bootstrap/app.php

<?php

// 省略
use Blocs\Middleware\Docs;

// 省略
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias(['docs' => Docs::class]);  // ←これを追加
    })
// 省略

routes/web.php

<?php
// こんな感じでrouteを設定する
Route::get('/demo/1', [TestController::class, 'index'])
    ->name('demo')
    ->middleware('docs');

2で設定したrouteのページにアクセスすると、ドキュメントが生成される

デモ

LaravelでPlayGround環境を作って、以下のようなファイルを作りました。

web/
├ app/
│ └ Http/
│   └ Controller/
│     └ TestController.php
├ resources
│ └ views
│   └ test.blade.php
└ routes/
	└ web.php

TestController.php

<?php

namespace App\Http\Controllers;

use Illuminate\View\View;

class TestController extends Controller
{
    public function page1(): View
    {
        docs('# Test page 1');
        docs('This is page 1 of Test Controller.');

        return view('test');
    }
    public function page2(): View
    {
        docs('# Test page 2');
        docs('This is page 2 of Test Controller.');

        return view('test');
    }
}

test.blade.php

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <title>Test</title>
    </head>

    <body>
        <h1>Number</h1>
        <p>{{ $number }}</p>
    </body>
</html>

web.php

<?php

use App\Http\Controllers\TestController;
use Illuminate\Support\Facades\Route;

Route::get('/blocs_docs/1', [TestController::class, 'page1'])
    ->name('blocs_docs')
    ->middleware('docs');

Route::get('/blocs_docs/2', [TestController::class, 'page2'])
    ->name('blocs_docs')
    ->middleware('docs');

この状態で、/page1か/page2のどちらかにアクセスすると、ミドルウェアが作動してドキュメントが生成されます。

以下は、page1のドキュメントです。

生成時点では、アクションメソッド名、テンプレートファイル、メソッド内でdocs()を使って設定したテキストが出力されています。

エクセルファイルなので、後から書き込むことも可能です。

blocs_書き込み後.png

画像を貼り付けたりもできるので、画面仕様書として扱いやすそうですね！

最後に

この記事では、既存のPHPファイルからドキュメントを生成するツールの調査内容をまとめました。

参考にできそうな部分も色々見つかったので、これらのツールをもう少し掘り下げてみたいと思います。

では、今回はこの辺で！

PHPファイルから画面仕様書の叩きを生成するツールが作りたい 〜調査編〜