CakePHP3のプラグインを格好良く公開する

Last updated at 2016-12-23Posted at 2016-12-22

CakePHP3 Advent Calendar 2016 - Qiita
22日目担当のひろみです。
最近軽量なCakePHP3のプラグインを作ったので、宣伝を兼ねてCakePHP3のプラグインを公開する時のtipsを紹介します。

注意事項

CakePHPとか関係ない、そもそもPHPじゃないところ満載です。
ひどく主観的なのでご気分を害された方はキレ気味にご指摘ください。
GitHubで公開することが前提ではないですが、一部はGitHub中心の説明になってしまうかもしれません。

はじめに

bakeじゃだめなんですか？

bake plugin でプラグインの雛形を生成できますが、大抵のプラグインは config/routes.php とか AppController とかは使いません。どちらかというと、テーマとして生成する為のものかと個人的には思っています。
※bakeテンプレートを用意すれば、ある程度はかっこいい雛形になるかもしれませんが、お好みで。

ではどうするか

世にある有名なプラグインを参考にしましょう！
デファクトスタンダードがわかればアレンジが効きます。
Friends Of Cake を見れば間違いがありません。CakePHPコアデベロッパーが中心になって運用している、CakePHPのプラグイン・ライブラリ群です。

作ったプラグイン

hiromi2424/cakephp-slack-log-engine
名前の通り、ログをSlackに送信するエンジンです。
説明に対応する実際に使っているファイルやコード等が見たい場合は、このレポジトリの中を見てください。

普段のログはsyslogやmonologやfluentdでいいと思いますが、CakePHPのログエンジンは重ねて設定できるので、対立しないで設定できるのが良いですね。

errorまで補足するとbotの適当なアタックのNotFoundまで拾って非常に面倒ですが、cryticalなログだけ送るなど設定すると便利かと思います。

README

READMEはライブラリの顔ですね。READMEがおざなりだと使う気にもなれないことでしょう。

バッジ

githubでよく見かける、 build passing等のバッジ。かっこいいですよね。

Shields.ioを見ればすぐに使えるバッジが山のように提供されています。
ビルドが通っているか、カバレッジが何%か、ダウンロード数、などなど、気になる情報が一目瞭然となります。是非配置しましょう。

タイトル

プラグインを表す簡素なタイトルにしましょう。無くても可。

簡単な説明

完結な文章でこのプラグインが何をするかを記述します。
長くても5〜6行におさめて書いたほうが良いでしょう。長いと高確率で読み飛ばされます。どんな文章でも同じですね。
見出しは「About」「What's this」「Introduction」~~「WTF」~~などが一般的です。

インストール方法

composer require hiromi2424/cakephp-slack-log-engine
など、composerのコマンドを書きましょう。
見出しは「Setup」「Installation」など。

要件

見出しは「Requirements」などと書きます。
対象のPHPバージョン、CakePHPのバージョンを書きましょう。
例：

CakePHP 3.x
PHP 5.5+

使い方

「Usage」「Configuration」など。
コード例を直接書くのが良いでしょう。
コード例が多すぎる、説明することが多すぎる場合は、別途ドキュメントにまとめたほうが良いです。
Wikiでも Sphinx でもドキュメント生成ツールを使うのでもなんでも良いですが、レポジトリ中にドキュメントソースがあると貢献者が増えるかもしれません。
Read the Docsは良い選択肢です。最近は採用例がかなり多いです。

コンポーネントやヘルパー、ログエンジン等のクラス設定がある場合は、列挙しておくと便利で機能要件も伝わりやすいです。

ツール

自動テスト

ユニットテストは必ず書きましょう。
普段のCakePHPアプリケーションでユニットテストを省略するような場面でも、ライブラリの場合は必ず書くべきです。
テスト自動化には Travis CI を使わない手はないでしょう。
幸い、先人たちが残した完璧な.travis.yml がある為、設定には苦労しないはずです。