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 がある為、設定には苦労しないはずです。
カバレッジ
先人たちが残した完璧な.travis.yml には Codecov というカバレッジ監視のサービス(もちろんオープンソース無料！)へカバレッジを送信するコマンドもついています。
バッジにカバレッジを表示するだけでなく、
コミット単位・PR単位でカバレッジが確認できます。超かっちょいい。
テストを書いていないのがバレると思って慌てて直したりするわけないですよねー
静的解析
scrutinizer さんは最高ですね。
これが無料というのですからオープンソース最高！と叫びたくなるのも頷けます。
詳しくは以下を参考にしてください。
コードの健康状態までバッジに表示されている！使わねば（使命感）
となること請け合いですね！
ソース
PHPDoc形式のソースコメントは必ずつけましょう。
PHPStorm等のIDEではPHPDocの型情報があると自動補完が効きます。
私もコメントが少ない方ですが、プラグインでは 事細かに書いています。
あとがき
拙作のプラグインを作っている時は、正直ソース書く時間よりもドキュメントを書く時間が長かったです。
正直動けばいいレベルのプラグインでドキュメントとか無く自分用みたいなところがあるのですが、習作として最後まで仕上げてみました。（まだまだ粗があるとは思いますが）
今回私が紹介したもの以外にも色々な工夫があると思いますが、最高のプラグインを作ってくれる皆様の一力添えとなれば幸いです。
22日25時に書き上げたからセーフですよね？
しかももう23日分が公開されていたなんて言えない