PHPパッケージにバグ発見時の対処

# PHPパッケージにバグ見つけちゃいました...

composerでインストール可能なPHPパッケージを使用していて、
どうも期待通りに動かない箇所がありました。

バグ発見、応急処置、最終的にパッケージ更新までの流れをまとめてみました。

## 期待通りに動かない??
cakephp-swagger-bake
というCakePHPとswaggerの橋渡しするようなパッケージを使用して、
高速にREST API開発＆テスト環境(Swagger UI)構築を進めてました。

シンプルなAPIについては、あまり調整はいらないのですが、
複雑なリレーションなどを含むAPIの場合、アノテーションを使って微調整する必要があります。

今回はそのアノテーション処理周りで、OpenAPI仕様からずれた出力がされるケースがあり、
Swagger UI 上で、テストをしようとするとResponsesのExample values が期待通りに
出力されなかったです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/49042/8a4e8799-8efa-9763-f9b9-cfb6784acb4a.png)

## バグ発見

Swagger UIで見ていてもよくわからないので、以下の手順で問題箇所の特定を進めました。
1) アノテーションの書き方を調整してswagger.jsonの出力調整
2) swagger.jsonを手動書き換えして結果の変化を確認する
3) swagger.jsonを出力する箇所のPHPコードの確認
4) OpenAPIの仕様との照らし合わせ

結論として、今回出力しようとしたリレーションの場合、OpenAPI仕様ではおかしい形式になっていたため、正常に動作してませんでした。

## 応急処置

パッケージ本体に問題があったので、
1) パッケージをオーバーロードするような別パッケージを用意する
2) パッケージを手動で修正する
という二つの方法を検討しました。

今回の修正箇所については、１つのクラスの１メソッドなので、オーバーロードも可能といえば可能です。ただ、メソッドをオーバーロードするのは向いてないコードでしたので、メソッドは差し替えになります。
となるとバージョンアップ耐性が低い！

ということで、パッケージを手動で修正することにしました。

### パッケージ修正の永続化

インストール毎、パッケージのアップグレード毎に手作業をするのは不安定すぎるので、
パッチ作成、自動パッチ適用をすることにしました。

修正後ファイルをnewsrc/Lib/Operation/OperationResponse.php に作成してから
パッチファイル作成
```
mkdir patches
diff -ubB src/Lib/Operation/OperationResponse.php newsrc/Lib/Operation/OperationResponse.php > patches/cakephp-swagger-bake-ref-array.patch
```

パッチファイルは
```
--- src/Lib/Operation/OperationResponse.php	2023-03-03 03:35:07.000000000 +0900
+++ newsrc/Lib/Operation/OperationResponse.php	2023-03-03 03:36:41.000000000 +0900
@@ -115,9 +115,16 @@ class OperationResponse
     private function addResponseRef(Response $response, string $mimeType, OpenApiResponse $openApiResponse): bool
     {
         if ($openApiResponse->ref) {
-            $schema = (new Schema())
-                ->setAllOf([['$ref' => $openApiResponse->ref]])
-                ->setType($openApiResponse->schemaType);
+            if ($openApiResponse->schemaType == 'array') {
+                $schema = (new Schema())
+                    ->setItems(['$ref' => $openApiResponse->ref])
+                    ->setType($openApiResponse->schemaType);
+            }
+            else {
+                $schema = (new Schema())
+                    ->setAllOf([['$ref' => $openApiResponse->ref]])
+                    ->setType($openApiResponse->schemaType);
+            }

             $response->pushContent(new Content($mimeType, $schema));
             $this->operation->pushResponse($response);
```

続いて、パッチを自動適用するためのパッケージの追加
https://packagist.org/packages/cweagans/composer-patches
```
composer install cweagans/composer-patches
```

パッケージ適用するためのファイルを定義します。
patches/update.json
```
{
    "patches": {
        "cnizzardini/cakephp-swagger-bake": {
            "update ref/array problem": "patches/cakephp-swagger-bake-ref-array.patch"
        }
    }
}
```

これで自動適用できるようになりました。

## バグ報告
今回は明確にバグで困ってる人もいそうなので、バグ報告＆修正パッチの送信をすることにしました。
https://github.com/cnizzardini/cakephp-swagger-bake/issues
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/49042/bad9c1b0-8bba-6fae-e957-d75455cc00b7.png)
New issueを押して

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/49042/f5e1f452-23bd-909f-8ff2-6f2317366e3f.png)
Get startedを押すと

タイトルと本文を入力する画面になります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/49042/76c84aa8-c6a6-1f34-8e0c-e4bce08748bd.png)

タイトルはできるだけ具体的にパッケージのメンテナーの方にわかるように意識して書きました。
本文では以下の５項目を指示通りに記載します。
- Describe the bug　バグの説明
- To Reproduce 再現条件
- Expected behavior 期待される動作
- Version and Platform (please complete the following information) 確認した環境
- Additional context 追記事項

実例は
https://github.com/cnizzardini/cakephp-swagger-bake/issues/512
をご覧ください。

### 修正報告
Issue登録後、パッチの送信を準備します。
1. レポジトリのFork
1. ローカル環境にc
1. Branchを切る
1. 修正をcommit / push
1. プルリクエスト

### その後のやりとり
定められたテストが不十分で、プルリクがリジェクトされてました。
修正後、composer analyzeでコードのチェック、問題箇所を修正しました。

修正内容
- コードのフォーマットの統一
- テストコードの修正（今回はテストコード自体間違ってましたので）

### 無事リリース
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/49042/7b5b818f-d70f-8121-9ef3-ad410e41715a.png)
無事メインブランチにマージされリリースされました！

https://github.com/cnizzardini/cakephp-swagger-bake
https://packagist.org/packages/cnizzardini/cakephp-swagger-bake