Laravel開発を快適にするツール

- Laravel IDE Helper: PHPDocを自動生成
- larastan: 静的解析ツール
- PHP-CS-Fixer: コード整形ツール
- L5-Swagger: OpenAPIドキュメント作成
- Redoc: OpenAPIファイルから静的なドキュメント作成

自分が残して置きたい設定などをメモ。


## Laravel IDE Helper
https://github.com/barryvdh/laravel-ide-helper

ソースコードからIDE用のPHPDocを生成する。IDEからファサードやモデルのオートコンプリートが使えるようになる。

### インストール
```bash
composer require barryvdh/laravel-ide-helper --dev 
```

### 実行
```bash
# ファサード用のPHPDocを生成（_ide_helper.phpファイルが生成される）
php artisan ide-helper:generate
# モデル用のPHPDocを生成（_ide_helper_models.phpファイルが生成される）
php artisan ide-helper:models -N
# モデル用のPHPDocを生成（モデルのファイルに直接書き込むこともできる）
php artisan ide-helper:models -W
```

生成された`_ide_helper.php`、`_ide_helper_models.php`をgitに追加するはプロジェクト次第。
（IDEに依存するところもあるので、個人的にはgit管理に含めずに`.gitignore`に追加することを勧めます。）

## larastan
https://github.com/nunomaduro/larastan

Laravel用の静的解析ツール。PHPStanの拡張でLaravel用のルールなどが追加されている。細かい設定は公式のドキュメントが詳しいので参考に。

### インストール
```bash
composer require nunomaduro/larastan --dev
```

### 設定

設定ファイル`phpstan.neon.dist`を作成し、gitに追加しておく。
個人的な設定をしたい場合、`phpstan.neon`を作成すると`phpstan.neon.dist`よりも優先される。

```:phpstan.neon.dist
includes:
    - ./vendor/nunomaduro/larastan/extension.neon

parameters:

    paths:
        - app

    # The level 9 is the highest level
    level: 5

    ignoreErrors:
        - '#PHPDoc tag @var#'

    excludePaths:
        - ./*/*/FileToBeExcluded.php

    checkMissingIterableValueType: false

    reportUnmatchedIgnoredErrors: false
```

### 実行
```bash
./vendor/bin/phpstan analyse
```

## PHP-CS-Fixer
https://github.com/FriendsOfPHP/PHP-CS-Fixer

ソースコードを自動で整形してくれるツール。PSRやSymfony、PHP-CS-Fixerのコーディング規則に合わせて自動整形してくれる。設定できるルールはかなり多いので公式ドキュメントを参考にルールセットをベースに適宜追加していけばよいかと。


### インストール
```bash
composer require friendsofphp/php-cs-fixer --dev
```

### 設定

設定ファイル`php-cs-fixer.dist.php`を作成し、gitに追加しておく。
個人的な設定をしたい場合、`php-cs-fixer.php`を作成すると`php-cs-fixer.dist.php`よりも優先される。

PHP-CS-Fixerのルールセットを使いたかったが、Laravelのコードスタイルに合わなかったので、PSR-12をベースにルールを追加して設定した。（個人的なスタイルの好みを含みます）

```php:.php-cs-fixer.dist.php
<?php

$finder = PhpCsFixer\Finder::create()
    ->exclude('vendor')
    ->exclude('storage')
    ->exclude('bootstrap/cache')
    ->in(__DIR__);
$config = new PhpCsFixer\Config();

return $config->setRules([
    '@PSR12' => true,
    'array_indentation' => true,
    'binary_operator_spaces' => true,
    'fully_qualified_strict_types' => true,
    'function_typehint_space' => true,
    'method_chaining_indentation' => true,
    'no_extra_blank_lines' => true,
    'no_multiline_whitespace_around_double_arrow' => true,
    'no_trailing_comma_in_singleline_array' => true,
    'no_unused_imports' => true,
    'no_whitespace_before_comma_in_array' => true,
    'normalize_index_brace' => true,
    'operator_linebreak' => true,
    'ordered_imports' => [
        'imports_order' => ['class', 'function', 'const'],
        'sort_algorithm' => 'alpha',
    ],
    'single_quote' => true,
    'trailing_comma_in_multiline' => true,
    'trim_array_spaces' => true,
    'whitespace_after_comma_in_array' => true,
])->setFinder($finder);
```

キャッシュファイルは不要なので.gitignoreに追加しておく。

```:.gitignore
.php-cs-fixer.cache
```

### 実行

```bash
# 自動整形
./vendor/bin/php-cs-fixer fix
# ファイルの変更は行わず、結果のみ表示
./vendor/bin/php-cs-fixer fix --dry-run
# ファイルの変更箇所を表示
./vendor/bin/php-cs-fixer fix --diff
```

### （Laravel-PHP-CS-Fixer）

https://github.com/stechstudio/Laravel-PHP-CS-Fixer

Laravelのコードスタイルをデフォルトで設定してくれるツールもあったのでこちらを使ってもいいかも。artisanコマンドでの呼び出しにも対応している様です。（初めからこっちを使っておけばよかった・・）

## L5-Swagger
https://github.com/DarkaOnLine/L5-Swagger

コントローラやモデルにアノテーションを追加してOpenAPIファイルを生成する。Swagger UIもローカルでホストしてくれるようになるのでテストなどにも便利。

Swagger-PHPのラッパーなのでアノテーションの書き方などは以下が参考になる。

- https://zircote.github.io/swagger-php/guide/annotations.html
- https://github.com/zircote/swagger-php/tree/master/Examples

アノテーションの書き方に癖があり扱いにくかった。最新のOpenAPIに完全に対応しているわけではない、ドキュメントがあまり充実してないなど苦労する点も多かったのでOpenAPIファイルを直接書いた方が良かったかもしれない。（Swagger UIとかSwagger Editorを自分で用意しなくていいのは良いですが。。）

### インストール
```bash
composer require darkaonline/l5-swagger --dev
```

### 設定

L5-Swaggerのconfigやviewをカスタマイズする場合に以下のコマンドでファイルを生成しプロジェクトに含める。

```bash
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
```

### 実行
```bash
# OpenAPIファイル生成（storage/api-docs/api-docs.jsonが生成される）
php artisan l5-swagger:generate
```

OpenAPIファイル生成後、`/api/documentation`にアクセスすれば、Swagger UI上で確認できる。

## Redoc

https://github.com/Redocly/redoc

L5-Swaggerで作成されるOpenAPIファイルを静的なHTMLファイルに出力する。L5-Swaggerでは静的なファイルを出力することはできないので。

### インストール

```bash
npm install -g redoc-cli
```

### 実行
```bash
redoc-cli bundle storage/api-docs/api-docs.json -o doc/index.html
```