🤔

Laravel IDE helperのide-helper:modelで生成されるPHPdocはどこに記載すべきか

2021/09/19に公開

背景

Laravel + PHPStormで開発しているとmodel等の補完が効かず辛い。

そこでLaravel IDE Helper Generatorの出番

これを導入すると、modelに定義してあるプロパティやスコープなどをサジェストしてくれる。

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/290859/180939e1-79f2-8221-348b-8e535d6d3a4e.png" width=100%>

問題

この機能はライブラリがモデルのPHPdocを自動生成しIDEが参照することで実現している。

PHPdocをどこに生成するかはコマンドのオプションで選択可能。

# モデルクラスに直接生成
php artisan ide-helper:model --write

# 専用のファイルに別で生成
php artisan ide-helper:model --nowrite

他の方が書いた記事では--nowriteを選択してるものが多かったが結局どちらを選択すればよいのか?

調査

--nowriteオプションで生成されたide_helper_models.phpの上部のコメント

ide_helper_models.php
/**
 * A helper file for your Eloquent Models
 * Copy the phpDocs from this file to the correct Model,
 * And remove them from this file, to prevent double declarations.
 *
 * @author Barry vd. Heuvel <barryvdh@gmail.com>
 */

訳すとこんな感じ

/**
 * Eloquentモデルのヘルパーファイル。
 * このファイルからphpDocsを正しいモデルにコピーし
 * そして、二重宣言を防ぐために、このファイルからそれらを削除してください。
 */

つまり、ide-helper_models.phpのPHPdocを移植して使ってね、という意味に受け取れる。

またto prevent double declarations.とあるように、PHPStormでは二重宣言の警告がすべてのモデルで発生する。(当たり前体操

image.png

更にcmd + Bで定義箇所へのジャンプや、alt + F7の使用箇所調査でide_helper_models.phpへの無用な参照が発生する。

image.png

スクリーンショット 2021-08-04 21.35.49.png

後者はそれほど問題にならないかもしれないが、前者はcmd + Bでいちいち正しい参照先を選択する必要があり、無視できない操作コストが発生する。

結局どちらが良いのか?

  • --writeオプション

    • メリット
      • 前述の無用なエラーや参照を避けられる
      • ライブラリ作者の意図をくんでいる(?)
    • デメリット
      • 他の記事でも指摘されているようにコンフリクトが心配
      • モデルクラスの肥大化
  • --nowriteオプション

    • メリット
      • コンフリクトが起きる心配がない
      • モデルクラスの行数が肥大しない
    • デメリット
      • 前述のようなエラーが鬱陶しい

結言

他の記事でも指摘されているようにおとなしく--nowriteオプションを指定すればいいですね。

ライブラリの作者はなんであんなコメント書いたんだ、、

※記事内容に関してはご指摘歓迎します。

GitHubで編集を提案

Discussion