Laravel IDE Helper 설정하기, 자동완성이 안 될 때

IDE로 Laravel을 개발할 경우 자동완성 및 goto 기능을 지원해주는 패키지다. 파사드와 Eloquent 매직 메서드 때문에 IDE가 타입을 못 잡는 문제를 해결해준다.

왜 필요한가

Laravel은 편의성을 위해 PHP의 동적 기능을 적극적으로 쓴다. 문제는 IDE가 정적 분석으로 타입을 추론하는데, 이런 코드는 분석이 안 된다는 점이다.

• 파사드 — Auth::user() 는 실제로 __callStatic으로 뒤에서 인스턴스에 위임한다. IDE는 Auth 클래스에 user()가 없다고 본다
• Eloquent 매직 메서드 — User::where() 는 모델이 아니라 쿼리 빌더의 메서드다
• 모델 속성 — $user->email 은 DB 컬럼이라 클래스에 프로퍼티 선언이 없다
• 매크로 — 런타임에 등록되는 메서드

IDE Helper는 이 정보들을 담은 힌트 파일을 생성해서 IDE가 읽을 수 있게 만든다.

설치

composer require barryvdh/laravel-ide-helper --dev

반드시 --dev로 설치한다. 운영 환경에는 필요 없는 패키지다.

설정

운영 환경에서는 서비스 프로바이더가 등록되지 않도록 조건을 건다.

// app/Providers/AppServiceProvider.php

public function register()
{
    if ($this->app->environment() !== 'production') {
        $this->app->register(\Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider::class);
    }
}

그리고 패키지를 업데이트할 때마다 힌트 파일이 자동으로 갱신되게 composer.json에 스크립트를 등록한다.

"scripts": {
    "post-update-cmd": [
        "Illuminate\\Foundation\\ComposerScripts::postUpdate",
        "php artisan ide-helper:generate",
        "php artisan ide-helper:meta"
    ]
}

세 가지 명령어

php artisan ide-helper:generate   # _ide_helper.php — 파사드
php artisan ide-helper:models     # 모델 속성 (PHPDoc)
php artisan ide-helper:meta       # .phpstorm.meta.php — 컨테이너 바인딩

ide-helper:models

이게 실제로 체감이 가장 크다. DB 스키마를 읽어서 모델에 속성 PHPDoc을 붙여준다.

# 모델 파일에 직접 주석을 추가
php artisan ide-helper:models -W

# 별도 파일(_ide_helper_models.php)에 생성 (모델 파일을 안 건드림)
php artisan ide-helper:models -N

결과는 이렇게 생긴다.

/**
 * @property int $id
 * @property string $email
 * @property \Illuminate\Support\Carbon|null $created_at
 * @property-read \Illuminate\Database\Eloquent\Collection|Post[] $posts
 */
class User extends Model

이제 $user->email 에서 자동완성이 되고, 오타를 치면 IDE가 경고를 띄운다.

선택: 모델 파일을 건드릴 것인가

-W는 모델 파일에 직접 주석을 넣고, -N은 별도 파일로 뺀다. 팀 상황에 따라 다르다.

• -W (직접 주입): 코드를 열었을 때 속성이 바로 보인다. 대신 diff에 주석 변경이 섞인다
• -N (별도 파일): 모델이 깨끗하게 유지된다. 대신 _ide_helper_models.php 를 gitignore할지 커밋할지 정해야 한다

생성 파일은 gitignore에

# .gitignore
_ide_helper.php
_ide_helper_models.php
.phpstorm.meta.php

생성물이라 커밋할 필요가 없고, 팀원마다 DB 스키마가 다르면 충돌만 난다. 각자 로컬에서 생성하는 게 맞다.

그래도 자동완성이 안 될 때

1. 파일을 생성하고 IDE를 재인덱싱했는지

# PhpStorm
File > Invalidate Caches... > Invalidate and Restart

2. 모델 생성 시 DB 연결이 되는지

ide-helper:models는 실제 DB에 접속해서 스키마를 읽는다. .env의 DB 설정이 맞지 않으면 아무것도 생성되지 않는다.

3. 커스텀 캐스트나 접근자는 자동 인식이 안 된다

Attribute 기반 접근자나 $casts로 지정한 값 객체는 IDE Helper가 타입을 정확히 못 잡을 수 있다. 이럴 때는 수동으로 PHPDoc을 보완한다.

/**
 * @property-read \App\ValueObjects\Money $totalPrice
 */

4. 스키마를 바꿨으면 다시 생성해야 한다

마이그레이션 후에는 ide-helper:models를 다시 돌려야 새 컬럼이 반영된다. 이걸 자주 잊어버리므로 마이그레이션 alias에 묶어두면 편하다.

# composer.json
"scripts": {
    "migrate": [
        "php artisan migrate",
        "php artisan ide-helper:models -N"
    ]
}

유료 대안: Laravel Idea

JetBrains 플러그인인 Laravel Idea는 힌트 파일 생성 없이 실시간으로 처리한다. 게다가 IDE Helper가 못 하는 것들까지 해준다.

• route(''), view(''), config('') 안에서 키 자동완성
• 블레이드 컴포넌트 인식
• 컨트롤러·모델 생성 마법사
• 관계 메서드 자동 생성

유료지만 Laravel을 주력으로 쓴다면 비용 대비 효율이 좋다. 무료로 갈 거면 IDE Helper로 충분히 커버된다.

정리

• Laravel의 파사드·매직 메서드 때문에 IDE가 타입을 못 잡는 문제를 해결
• --dev로 설치하고 운영에서는 프로바이더 등록 제외
• generate(파사드), models(속성), meta(컨테이너) 세 명령
• 생성 파일은 gitignore
• 마이그레이션 후에는 다시 생성해야 새 컬럼이 반영된다