Laravel Tinkerとは？使い方から終了方法・モデル操作・便利コマンドまで徹底解説

「php artisan tinkerで何ができるのか知りたい」「終了方法や基本的なコマンド、モデルの操作手順がわからない」とお悩みではありませんか？

Laravel Tinkerは、Laravelアプリケーションをターミナル上で対話的に操作できる便利なREPL（Read-Eval-Print Loop）ツールです。Webブラウザからリクエストを送ったり、一時的なルーティング・コントローラーを作成したりしなくても、Eloquentモデルの検索やデータベース操作、サービスクラスの動作確認、Laravelの各機能の検証をその場で即座に行えます。

本記事では、Laravel Tinkerの起動・終了といった基本操作から、Eloquentモデルを使ったCRUD処理、Docker（Laravel Sail）環境での動かし方、トランザクションを使った安全なDB検証、PsySHの便利コマンド、--executeオプションによるスクリプト実行、つまずきやすいエラーの対処法まで徹底解説します。

Laravel Tinkerとは？何ができるツール？
1. Tinkerの主な用途
Tinkerの起動方法と終了方法
Eloquentモデルとデータベースの操作手順
実務で役立つTinkerの検証テクニック
知っておくと差がつくPsySHの便利コマンド
1. doc コマンドでドキュメントを参照する例
2. show コマンドでソースコードを確認する例
Tinker内からArtisanコマンドを実行する
1. 1. ホワイトリスト登録済みコマンド
2. 2. その他のArtisanコマンド（Artisanファサード）
非対話でTinkerを実行する：–executeオプション
1. 活用シーン
config/tinker.phpでTinkerの挙動をカスタマイズする
つまずきやすいエラー・注意点と対処法
まとめ
関連記事

Laravel Tinkerとは？何ができるツール？

Laravel Tinkerは、PHP向けの対話型シェルであるPsySHをベースに構築された、Laravel専用の対話型実行環境（REPL）です。

通常、Laravelでコードの動作を確認する場合、ルート（routes/web.php）を定義してブラウザでアクセスするか、テストコードを書く必要があります。しかしTinkerを使えば、ターミナル上でPHPコードを1行入力するだけで、その場で実行結果を確認できます。

Tinkerの主な用途

EloquentモデルのCRUD操作：データの取得、作成、更新、削除、リレーションの確認
ビジネスロジックの動作確認：ServiceクラスやJob、Notificationの単体テスト
Laravelヘルパー・Facadeの動作確認：config()、now()、Hash::make()、Storageなどの挙動確認
Artisanコマンドの実行・マイグレーション：対話シェル内からの各種操作

Laravel 10 / 11 / 12 / 13などの主要なバージョンにおいて、laravel/tinkerは標準で依存関係（composer.json）に含まれているため、追加のセットアップなしにすぐ利用できます。

Tinkerの起動方法と終了方法

1. ローカル環境での起動

ローカル環境（PHPがインストールされている環境）では、Laravelプロジェクトのルートディレクトリで以下のArtisanコマンドを実行します。

php artisan tinker

起動に成功すると、Psy Shellのバージョン情報とともにプロンプト（>）が表示されます。

Psy Shell v0.12.0 (PHP 8.3.0 — cli) by Justin Hileman
>

2. Laravel Sail（Docker環境）での起動

Laravel Sailを利用してDockerコンテナ上で環境を動かしている場合は、次のコマンドでコンテナ内のTinkerを起動します。

./vendor/bin/sail tinker
# または sailエイリアスを設定している場合
sail tinker

あるいは、sail artisan tinkerと入力しても同様に起動できます。

3. Tinkerの終了方法

Tinkerの対話モードを終了して通常のターミナルに戻るには、以下のいずれかの方法を実行します。

終了方法	入力内容 / ショートカット	特徴・備考
コマンド入力（推奨）	`exit` または `quit` または `q`	プロンプトに直接入力してEnterを押すと`Goodbye.`と表示されて安全に終了します
キーボードショートカット	`Ctrl` + `D`	入力の終端（EOF）を送信して即座にシェルを終了します
割り込み終了	`Ctrl` + `C`	処理実行中の割り込みや強制終了に使用します

実際の終了画面例：

> exit

   INFO  Goodbye.

Eloquentモデルとデータベースの操作手順

Tinkerの最も代表的な活用例が、Eloquentモデルを通じたデータベースのCRUD（作成・読取・更新・削除）操作です。

モデルの自動エイリアス機能

Laravel Tinkerでは、App\Models\Userのようなフルネーム（完全修飾クラス名）を入力しなくても、User::all()のように短縮して記述できます。初回アクセス時にTinkerが自動でエイリアスを設定してくれます。

> User::first();
[!] Aliasing 'User' to 'App\Models\User' for this Tinker session.

1. データの検索・取得（Read）

主キーによる取得や条件検索、特定カラムの抽出が簡単に行えます。文末のセミコロン（;）は省略しても実行可能です。

// ID指定で1件取得
$user = User::find(1);

// 先頭の1件を取得
$user = User::first();

// 条件を指定して複数件取得
$activeUsers = User::where('status', 'active')->get();

// 特定のカラムのみを配列/コレクションとして取得
User::pluck('email');
// => Illuminate\Support\Collection {#... all: ["user1@example.com", "user2@example.com"] }

// 件数をカウント
User::count();
// => 10

2. データの新規作成（Create）

手動でモデルインスタンスを作成して保存する方法と、Factoryを利用してダミーデータを自動生成する方法があります。

手動で作成する場合：

$user = User::create([
    'name' => '山田 太郎',
    'email' => 'yamada@example.com',
    'password' => bcrypt('password123'),
]);
$user->id;
// => 11

Factoryを使って作成する場合：

// 1件生成して保存
$user = User::factory()->create();

// 属性を一部上書きして3件まとめて作成
$users = User::factory()->count(3)->create(['status' => 'active']);

3. データの更新（Update）

既存レコードの取得後にプロパティを変更してsave()するか、update()メソッドを呼び出します。

$user = User::find(1);
$user->name = '山田 次郎';
$user->save();

// updateメソッドで直接更新
User::where('id', 1)->update(['name' => '山田 三郎']);

4. データの削除（Delete）

$user = User::find(1);
$user->delete();

// 条件に一致するものを一括削除
User::where('status', 'banned')->delete();

5. リレーションの確認

モデル間の関連付け（1対多、多対多など）が正しく定義されているかを検証できます。

$user = User::with('posts')->first();
$user->posts->count();
// => 5

// リレーション先の特定メソッドを呼ぶ
$user->posts()->where('is_published', true)->get();

実務で役立つTinkerの検証テクニック

1. トランザクションで安全にデータ検証（ロールバック前提）

「データの更新や削除ロジックを試したいが、データベースのデータを汚したくない」という場合は、トランザクションとロールバックを組み合わせます。

// トランザクション開始
DB::beginTransaction();

// データの作成・更新・削除をテスト
$user = User::find(1);
$user->delete();
User::count(); // 削除後の件数を確認

// 検証が終わったらロールバック（元に戻す）
DB::rollBack();

// 元に戻っていることを確認
User::find(1); // 復元されている

この手順を使えば、データベースの状態を変更することなく、複雑なクエリや処理の挙動を安全に確認できます。

2. 発行されるSQLクエリをその場で確認する

Eloquentが実際にどのようなSQLを発行しているかを確認したい場合、DB::listen()やクエリログを活用します。

DB::listen()を使う方法（リアルタイム出力）：

DB::listen(function ($query) {
    dump([
        'sql' => $query->sql,
        'bindings' => $query->bindings,
        'time' => $query->time . 'ms',
    ]);
});

// この後にEloquentを実行すると発行SQLが出力される
User::where('status', 'active')->orderBy('created_at', 'desc')->take(3)->get();

クエリログを使う方法：

DB::enableQueryLog();

User::with('posts')->get();

dump(DB::getQueryLog());

N+1問題の発生有無や、インデックスが効くクエリになっているかの確認に最適です。

3. ServiceクラスやDI（依存注入）の動作検証

コントローラー内に書く前のビジネスロジックや、サービスコンテナにバインドされたクラスをテストできます。

// サービスコンテナ経由でクラスをインスタンス化（依存関係も自動解決される）
$paymentService = app(App\Services\PaymentService::class);

// メソッドを実行して戻り値を確認
$result = $paymentService->calculateTotal(1000, 0.1);
dump($result);

4. ヘルパー関数・Facadeの動作確認

Laravelの組み込みヘルパーやFacadeの挙動もそのままテストできます。

// 設定値の確認
config('app.timezone');
// => "Asia/Tokyo"

// 日時操作（Carbon）
now()->addDays(7)->toDateTimeString();

// パスワードハッシュの生成と検証
$hash = Hash::make('secret-password');
Hash::check('secret-password', $hash);
// => true

// ログ出力テスト
Log::info('Tinkerからのテストログ出力');

ログの出力方法やデバッグ手法については、Laravel Logの使い方完全ガイドやLaravelのdd関数を活用したデバッグ方法もあわせてご覧ください。

知っておくと差がつくPsySHの便利コマンド

Laravel TinkerはPsySHの機能をすべて備えているため、ターミナル上で直接ドキュメントやコードを参照できる強力な対話コマンドが利用できます。

コマンド	構文例	役割・機能
`doc`	`doc User` / `doc str_contains`	クラスや関数、メソッドのPHPDocや型定義を表示する
`show`	`show User::scopeActive`	対象クラスやメソッドのPHPソースコードを直接ターミナルに表示する
`ls`	`ls $user` / `ls User`	インスタンスやクラスのプロパティ、定数、メソッド一覧を一覧表示する
`wtf`	`wtf`	直前に発生した例外エラーの詳細スタックトレースを表示する
`history`	`history --show 20`	過去に入力したコマンドの履歴を表示する
`help`	`help`	PsySHの全コマンドと使い方ヘルプを表示する

doc コマンドでドキュメントを参照する例

> doc User::find
// => メソッドのシグネチャとPHPDoc説明が表示される

show コマンドでソースコードを確認する例

ライブラリやモデルの内部実装をわざわざエディタで開いて探さなくても、Tinker内から直接ソースコードを閲覧できます。

> show User::scopeActive

Tinker内からArtisanコマンドを実行する

Tinkerを開いたまま、各種Artisanコマンドを実行できます。

1. ホワイトリスト登録済みコマンド

以下のコマンドは、Tinker内でコマンド名を入力するだけで直接実行できます。

clear-compiled, down, env, inspire, migrate, migrate:install, optimize, up

例えば、Tinkerを開いたままテーブルを更新したい場合は、migrateと入力するだけでマイグレーションが走ります。

2. その他のArtisanコマンド（Artisanファサード）

ホワイトリストにないコマンド（Seederの実行など）は、Artisan::call()経由で実行します。

use Illuminate\Support\Facades\Artisan;

// Seederの実行
Artisan::call('db:seed', ['--class' => 'UserSeeder']);
echo Artisan::output();

Seederの詳しい使い方についてはLaravel Seeder実行方法まとめをご参照ください。

非対話でTinkerを実行する：–executeオプション

Tinkerは対話シェルとして対話的に操作するだけでなく、--executeオプションを使用することで、1行のPHPコードをワンライナーとして即座に実行できます。

php artisan tinker --execute="echo App\Models\User::count();"

このコマンドを実行すると、対話シェルを起動せずに結果だけが標準出力に返されます。

活用シーン

CI/CDパイプラインやデプロイスクリプト内でのデータ整合性チェック
シェルスクリプトからLaravelのModelや設定値を呼び出す自動化処理
本番リリース直後の初期データ存在確認

config/tinker.phpでTinkerの挙動をカスタマイズする

Tinkerの設定をカスタマイズしたい場合、設定ファイルを発行できます。

php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"

発行後、config/tinker.phpで以下の項目を設定できます。

設定項目	説明
`commands`	Tinker内でコマンド名のみで短縮実行できるArtisanコマンドを追加登録する
`alias` / `dont_alias`	自動エイリアスの対象に含める、または除外するクラス名前空間を指定する（デフォルトでは`App\Nova`などが除外）
`trust_project`	PsySHのプロジェクト信頼警告の挙動を制御する（`always`など）

つまずきやすいエラー・注意点と対処法

1. コードを変更してもTinkerに反映されない

Tinkerを起動した状態で、別エディタでモデルやサービスクラスのコードを修正・保存しても、起動中のTinkerセッションには反映されません。

Tinkerは起動時にクラスやオートローダーをメモリ上にロードするためです。コードを修正した場合は、一度exit（またはCtrl + D）で終了し、再度php artisan tinkerを起動し直してください。

2. 本番環境での取り扱い注意

Tinkerはデータベースの直接操作やコードの即時実行が可能なため、本番環境での不用意な実行は非常に危険です。

User::truncate() や条件なしの delete() などによるデータ消失リスク
トランザクションを貼らない更新によるデータ不整合

本番サーバー上でやむを得ず調査を行う場合は、事前にバックアップを取得したうえで、前述の DB::beginTransaction() を徹底し、作業完了後にロールバックまたは慎重にコミットしてください。

3. 入力履歴ファイルの場所

Tinkerに入力した履歴は、キーボードの上下矢印キーで呼び出すことができます。この履歴はOSごとのPsySH履歴ファイルに保存されます。

Linux / macOS: ~/.config/psysh/psysh_history
Windows: %APPDATA%\PsySH\psysh_history

4. 「Class not found」エラーが出る場合

新規作成したクラスが見つからない場合は、Composerのオートロードが更新されていない可能性があります。ターミナルでcomposer dump-autoloadを実行してから再度Tinkerを起動してください。

まとめ

Laravel Tinkerは、ターミナルから直接Laravelアプリケーションを操作・検証できる非常に強力なツールです。

起動・終了: php artisan tinker（Sailはsail tinker）で起動、exitやCtrl + Dで終了
Eloquent操作: クラス名エイリアスにより短縮記法でCRUD・リレーションを即座にテスト可能
安全な検証: DB::beginTransaction() と DB::rollBack() でデータを壊さずにロジックを試せる
PsySHコマンド: doc、show、ls、wtfを活用すればターミナル上でドキュメントやコードを確認可能
非対話実行: --execute オプションでスクリプトや自動化処理にも組み込める

日々の開発で新機能のロジックやEloquentクエリを試す際は、ぜひTinkerを活用して開発効率を向上させてみてください。