vendor:publish — パッケージの資産を公開するコマンド
artisan
php artisan vendor:publish コマンドについての解説
一言概要
- カテゴリ：artisan
- 掲載バージョン：Laravel 12・PHP 8.4
- 名前空間 / FQCN / コマンド：
vendor:publish / php artisan vendor:publish
- 関連：config:cache, config:clear, view:clear, route:clear, event:cache
- 変更履歴：5.2 追加 → 5.6 でタグ指定が必須に → 8.0 で
--force のデフォルト無効化
要点（TL;DR）
- 目的：パッケージの config・migration・view・asset 等をアプリへコピー
- 最低限：
php artisan vendor:publish
- よくある罠
- すべてを公開してしまう
- 既存ファイルとの競合
- キャッシュ未クリアで変更が反映されない
概要
vendor:publish は、パッケージの公開可能ファイルを指定してアプリにコピーします。
タグやプロバイダーを指定すると、必要なリソースだけを限定して公開できます。
構文 / シグネチャ
php artisan vendor:publish [options] [--] <args>
オプション表
| オプション | 型 | 必須 | 既定値 | 説明 |
|---|
--provider | string | いいえ | なし | 指定プロバイダーのファイルのみ公開 |
--tag | string | いいえ | なし | タグ付きファイルのみ公開（スペース区切り） |
--force | flag | いいえ | なし | 既存ファイルを上書き |
--quiet | flag | いいえ | なし | 出力を抑制 |
--ansi | flag | いいえ | なし | ANSI カラーを有効化 |
--no-ansi | flag | いいえ | なし | ANSI カラーを無効化 |
戻り値
- コンソール出力（文字列）
- 終了コード：成功 0、失敗 1
副作用
- ファイルコピーとパスの書き込み
- 既存ファイルの上書き（
--force）
config:cache, view:clear, route:clear 等のキャッシュクリアが必要になる場合がある
例外
RuntimeException：指定プロバイダーが見つからないIOException：ファイル書き込み失敗
使用例
最小例
php artisan vendor:publish
実務例
# config と migrations だけ公開
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag="config,migrations"
# 既存ファイルを上書き
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --force
よくある落とし穴・注意
| 症状/エラー | 原因 | 対処 |
|---|
Invalid provider | FQCN が誤っている | php artisan vendor:publish で確認 |
File exists, not overwriting | --force が無い | --force を付ける |
| キャッシュ残存 | config キャッシュが残る | php artisan config:clear を実行 |
| パーミッション不足 | storage / bootstrap/cache が書き込み不可 | chmod -R 775 storage bootstrap/cache |
| CI 失敗 | 権限・ロックの問題 | sudo chown -R $USER storage bootstrap/cache |
代替・関連APIとの比較
| 手段 | メリット | デメリット | 選択基準 |
|---|
--tag=... | タグ単位で細かい制御 | タグが無いと使えない | 特定リソースのみ更新したい時 |
--provider=... | プロバイダー全体をまとめて公開 | タグが混在すると全公開 | プロバイダー全体を管理したい時 |
無指定 vendor:publish | すべてを一括で公開 | 余計なファイルがコピーされる | 初回セットアップ時に一括公開したい時 |
テスト例（Pest）
it('publishes config files', function () {
$this->artisan('vendor:publish', ['--tag' => 'config'])
->expectsOutput('Published [config/vendor.php]')
->assertExitCode(0);
expect(config_path('vendor.php'))->toBeFile();
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|
Cannot create directory | 書き込み権限不足 | sudo chown -R $USER storage bootstrap/cache |
File exists, not overwriting | --force が無い | --force を付与 |
Missing tag | タグ未設定 | パッケージドキュメント確認 |
Cannot write file | ファイルロック | 関連プロセスを停止または再起動 |
実行環境
- 開発マシン（Laravel Sail, Homestead 等）
- 本番サーバー（
storage と bootstrap/cache に 775/775 の書き込み権限が必要）
- CI/CD 環境（パーミッションとキャッシュのクリアを事前に設定）
終了コード
| コード | 状態 |
|---|
| 0 | 成功（公開済み） |
| 1 | 失敗（例外・エラー） |
参考リンク
