laravel-database-autodoc パッケージを作成した

4445 ワード
Packagist PHP7 Laravel documentation Laravel テキストリンク

数カ月前から仕事でLaravelを扱うようになって3ヶ月。初めてphpのパッケージを作って公開したのでメモがてらに投稿する。

何をつくったか?

なぜつくったか?

  • データベースのスキーマを確認するのが面倒だったので、機械的にすべてのテーブル定義をマークダウンファイルに出力するartisanコマンド。
  • php artisan migrate を実行したら、CommandFinishedイベントを拾って、ドキュメント生成のコマンドが実行される。
  • dev dependencyにインストールするだけで、コマンドの使い方などを覚える必要もなく、ドキュメントを生成/更新してくれる代物です。

👇こんなマークダウンが自動生成される👇

どのようにつくったか?

手順は以下:

  1. Packagistにアカウント登録・GitHubアカウントと連携・2FAを設定
  2. composer init
  3. てきとうなlaravel appに、ローカル環境にあるパッケージをインストール
  4. コマンドやイベントリスナーを実装して、サービスプロバイダーを作成
  5. アプリケーション側から動作することを確認
  6. GitHubにリポジトリを作って、packagistでsubmitしたら公開された

Packagistアカウントを準備

Packagist は、RubyでいうところのRubyGems、JavaScriptでいうところのnpmで、要はPHP向けのレジストリです。やることはごく簡単で以下の通り:

  • アカウント登録
  • GitHubとアカウント連携
  • 2FAを設定

パッケージを作成

$ mkdir mylib && cd mylib
$ composer init

composer.json を作った後、以下を設定した:

  • 依存関係（今回はlaravel用のライブラリなのでlaravelを設定。セマンティックバージョニングは5.7以上にする）
  • オートロード（autoload => psr-4にロードするディレクトリを指定）

適当なlaravel appにインストール

ローカルパッケージとしてインストールする。以下の記事が参考になった:

  • pathの指定が相対パスだったが、絶対パスにしないとうまくインストールされなかった。
  • キャッシュのせいなのか、 composer install だけではうまくインストールされず、 composer update を実行する必要があった。

動作確認はtinkerで、 Foo\Bar\LibraryClass をnewして、hello worldする程度でよい。

コマンドやイベントリスナーを実装して、サービスプロバイダーを作成

  • コマンドのコードは こちら
    • Laravel/frameworkのコンソールの実装を参考に雰囲気で書いた。
    • コード見ればわかるが、information_schema.tables の内容を素朴に書き出している。
    • MySQL以外で動作確認していないので、SQLiteやPostgresで動作するかは試していない（OSSなので、もし必要ならば必要だと思った方が実装すればよさそう）
  • イベントリスナーのコードは こちら
    • migrateの実行をフックしたかったのだが、どのようにやるべきか調べて、コマンド実行前と実行後にイベントがディスパッチされるので、それを拾って、Artisan::call() で実行すればよいのだなと、これもLaravel/frameworkを読んで知った。

サービスプロバイダーは、 composer.json の extra => laravel => providers にプロバイダークラスを設定すると、アプリケーション側から自動検出されるようなのでこれを使った。

アプリケーション側から動作することを確認

これはそのまんま。

GitHubにリポジトリを作って、packagistでsubmitしたら公開された

  • GitHubにpublicリポジトリを作って、そこにpush。その後、packagistからリポジトリのURLをSubmitすると公開された。
  • 公開後、クロールしているのだなと興味深かった。

感想

  • 所要時間は2時間程度。
  • ローカルパッケージが反映されず苦戦した。
  • アプリがコンテナだと当然ローカルパッケージは読み込めないので注意するといい。
  • 今回はファイルを生成するだけのコマンドなのでテストは書いていない。
  • Laravel/frameworkにパッチを書きたいので、後日テストの所作も調べたい（普通にphpunitだろうけど）
  • 普段はRubyやJavaScriptを書くことが多いけれど、phpやlaravelもなかなか面白い。

作ったパッケージはテーブル定義を確認するときブラウザからも見れるので、それなりに便利に利用できています。

$ composer require --dev yhirano55/laravel-database-autodoc

でインストールできるので、もしよかったらメンテしているLaravelアプリケーションに導入してみてください。