February 26, 2020

Laravel/PHP用パッケージ開発時のコツ

もしかして、Laravel用パッケージの開発に関してはいつの間にか自分が日本で一番詳しくなってるのでは…。
パッケージ作って何年もメンテナンス続けてる人は見た記憶がない。
実際は日本だけでなく海外にもそんなに多くない。Laravelのバージョンアップに対応できずに捨てたパッケージは大量にある。

まずは素のPHPでも使えるように作る

わざわざLaravel専用にする理由はないので素のPHPや他のフレームワークでも使えるように作る。
その上でLaravelなら簡単に使えるようにFacadeなどを整備。

Laravelの機能を拡張するパッケージなら最初から専用でいい。

composer使うのは書くまでもない当たり前の前提。

サービスコンテナやサービスプロバイダーの理解が必須

普通にLaravel使うだけなら不要だけどパッケージ作るなら必須。
というよりパッケージ作ってると勝手に身に付く。

Laravelのバージョンアップは常に追いかける

Laravelに合わせてパッケージのメンテナンスも必要。
パッケージ作るなら半年毎のメジャーバージョンアップなんて狂気に付いていく覚悟が必要。

旧バージョンのサポートは容赦なく切る

PHPもLaravelもサポート期限ははっきり決まってるので旧バージョンのサポートは切っていい。
きちんとメンテナンスされてるかどうかはここで決まる。
新機能なんか追加しなくていい。
サポート中の現行バージョンと次期バージョンで問題ないかの確認。やるべきことはこれだけ。

Laravel公式の真似をする

機能の使い方やコードの書き方などとにかくすべて公式を参考にする。非公式な情報は一切見てはいけない、全部間違ってると思っていい。
意外と非公式なものを公式と思い込んでる人は多い。GitHubにあるものだけが公式。
https://github.com/laravel

ConcernsとTraits

フレームワーク内でclassを分割する目的にはConcerns。Laravelプロジェクトで別のclassに機能を追加する目的にはTraitsで使い分けてるように見える。
同じtraitなのでそこまで厳密に考える必要はないけど。
Traitsのつもりで作ったら安易に変更しない。
Concernsは内部のみなので変更していい。

composer.lockは含めない

「ライブラリには含めない。プロジェクトには含める」composer開発者による公式見解なのでこれがルール。
プロジェクト用のテンプレートはどっちでもいい。含めなくてもcomposer installしてすぐに生成される。

不要なファイルは.gitattributesで指定

.gitignoreはよく知られてるだろうけど.gitattributesも地味に重要。

composer install時に不要なファイルは.gitattributesでexport-ignore指定。
無駄なファイルがダウンロードされずインストールが少し早くなる。
正確にはzipでダウンロード時にも含まれなくなるのでダウンロードして使う人がいると困るかもしれないけどcomposerパッケージなら関係ないだろう。

/tests export-ignore
.editorconfig export-ignore
.gitattributes export-ignore
.gitignore export-ignore
.styleci.yml export-ignore
.travis.yml export-ignore
phpunit.xml export-ignore

composer.jsonのバージョン指定

ここは各自の方針で決める所。
Laravel用パッケージなら大抵requireにilluminate/supportを指定する。
これでLaravelの対応バージョンを指定するけど

"illuminate/support": "^5.8||^6.0||^7.0",

半年毎に書き換え作業したくないなら*で指定する方法もある。

"illuminate/support": "*",

ただし*を使うのはあまり良くないのでどうするかは各自で決める。

外部サービスを活用する

OSSなら無料で使える。
使うサービスは別になんでもいい。

プロジェクト内でPHP-CS-Fixerでがんばるより外部サービスに任せたほうがいい。

TravisでPHP8.0(開発版)のテスト

たぶん2020年中にしか役に立たない。

Travisはnightlyでその時点での最新の開発版が使えるけどPHP8.0はまだ大半のパッケージが対応してないのでそのままインストールしようとしてもできない。"php": "^7.2||^8.0",としてくれるのを待つしかない。
composerのオプションで--ignore-platform-reqsを付ければ無視できるのでnightlyのみ付けるように.travis.ymlを調整。

sudo: false
language: php

jobs:
  include:
    - php: 7.2
    - php: 7.3
    - php: 7.4
    - php: nightly
      env: COMPOSER_OPTION=--ignore-platform-reqs

before_script:
  - travis_retry composer install --no-interaction --no-suggest $COMPOSER_OPTION

script:
  - vendor/bin/phpunit

8.0リリース後もまだ対応してなさそうなので8.1(開発版)でテストするためにおそらくこうなる。

jobs:
  include:
    - php: 7.2
    - php: 7.3
    - php: 7.4
    - php: 8.0
      env: COMPOSER_OPTION=--ignore-platform-reqs
    - php: nightly
      env: COMPOSER_OPTION=--ignore-platform-reqs

© kawax