---
title: "php artisan tinkerの使い方｜Laravel Tinkerの基本コマンドとEloquent操作"
url: "https://www.issoh.co.jp/tech/details/4278/"
published: 2024-11-21
updated: 2026-07-19
categories: ["Laravel"]
publisher: "株式会社一創"
---

# php artisan tinkerの使い方｜Laravel Tinkerの基本コマンドとEloquent操作

`php artisan tinker`は、Laravelアプリを丸ごと読み込んだ状態でPHPを1行ずつ実行できる対話環境（REPL）を開くコマンドです。コントローラーやルートを書かなくても、Eloquentモデルの検索・作成・更新・削除やリレーションの確認をその場で試せます。この記事では、起動と終了、Eloquentでのデータ操作、リレーション取得、`help`や`doc`などの組み込みコマンド、そして日本語が入力できないときの原因と対処までを実例で説明します。

## まとめ

- **起動は`php artisan tinker`、終了は`exit`・`quit`・`Ctrl+D`。**LaravelにはTinker（`laravel/tinker`）が標準同梱されているため追加インストールは不要です。
- **用途はEloquentの動作確認。**モデルの`create`／`find`／`where`／`update`／`delete`やリレーションを、コードを書かずに1行で検証できます。
- **日本語が入力できないのはPHPの`readline`拡張がlibedit実装のとき。**GNU readlineに切り替えるか、`--execute`での非対話実行で回避します。
- **本番DBには直接つながる。**取り消しの効かない更新・削除を対話で打つのは避け、スクリプトとトランザクションで守ります。

以下で、それぞれのコマンドと具体的な書き方を順に見ていきます。

## Tinkerとは何か（PsySHベースのREPL）

### REPLとしてTinkerができること

Tinkerは、PHP製のREPLである**PsySH**の上にLaravelの起動処理を載せたものです。REPLは「入力→評価→結果表示」を繰り返す対話シェルで、Tinkerを起動するとフレームワークがブートストラップされ、Eloquent・キュー・イベント・設定値・サービスコンテナなどアプリ内のあらゆるオブジェクトにコマンドラインから触れます。パッケージ名は`laravel/tinker`で、2026年時点の最新は3.0系（v3.0.2、内部で`psy/psysh` 0.12系を利用、PHP 8.1以上・Laravel 13まで対応）。Laravel本体に最初から含まれるため、通常はインストール不要です。

### 起動と終了の方法

プロジェクトのルートで次を実行するとプロンプトが`>>>`に変わり、対話モードに入ります。

```
php artisan tinker
```

終了するときは`exit`または`quit`と入力するか、`Ctrl+D`を押します。実行結果はそのまま画面に返るため、たとえば`1 + 1`と打てば`2`が、`now()`と打てば現在時刻のCarbonインスタンスが表示されます。式の最後にセミコロンは不要です。

## Eloquentでのデータ操作（作成・検索・更新・削除）

Tinkerの主な使い道は、Eloquentモデルの動作をその場で確かめることです。Laravel 8以降のモデルは`App\Models`名前空間にあるため、`App\Models\User`のように完全修飾名で呼び出します。モデル名とテーブル名の対応はLaravelの規約で自動解決されます（対応の詳細は[Laravelの命名規則一覧｜テーブル・モデル・コントローラーからコーディング規約まで](/tech/details/5468/)を参照）。

### データを作成する（create・factory）

1件を作るなら`create`に配列を渡します。テスト用にまとまった件数が欲しいときは`factory`が便利です。

```
App\Models\User::create([
    'name' => 'Taro',
    'email' => 'taro@example.com',
    'password' => bcrypt('secret'),
]);

App\Models\User::factory()->count(3)->create();
```

`create`を使うにはモデルの`$fillable`に対象カラムを登録しておく必要があります。`factory`はモデルファクトリ（`database/factories`）が定義されている前提で動きます。

### データを検索する（find・where・LIKE）

主キー指定は`find`、条件指定は`where`を使います。部分一致は`like`演算子と`%`を組み合わせます。

```
App\Models\User::find(1);
App\Models\User::where('email', 'taro@example.com')->first();
App\Models\User::where('name', 'like', '%太郎%')->get();
```

`get()`はコレクションを、`first()`は1件を返します。件数だけ知りたいときは`count()`、存在確認は`exists()`で十分です。

### データを更新する（save・where update）

取得したモデルの属性を書き換えて`save`する方法と、条件に一致する行をまとめて更新する方法があります。

```
$user = App\Models\User::find(1);
$user->name = 'Jiro';
$user->save();

App\Models\User::where('id', 1)->update(['name' => 'Jiro']);
```

`update`による一括更新はモデルの取得を挟まないぶん速い反面、`updated_at`以外のモデルイベントが発火しない点に注意します。

### データを削除する（delete・ソフトデリート）

単純な削除は`delete`です。モデルが`SoftDeletes`トレイトを使っている場合は物理削除ではなく`deleted_at`に日時が入り、`withTrashed()`で復元対象を取得して`restore()`で戻せます。完全に消すには`forceDelete()`を使います。

```
App\Models\User::find(1)->delete();
App\Models\User::withTrashed()->find(1)->restore();
App\Models\User::find(1)->forceDelete();
```

外部キー制約がある子レコードを残したまま親を削除するとエラーになるため、削除順序かカスケード設定を確認してから実行します。

## リレーション経由で関連データを取得する

Tinkerはリレーションの動作確認にも向きます。定義済みのリレーションはプロパティのように参照でき、`hasMany`・`belongsTo`・`belongsToMany`のいずれも同じ書き味です。

```
$user = App\Models\User::find(1);
$user->posts;          // hasMany: そのユーザーの投稿一覧
$post = App\Models\Post::find(1);
$post->user;           // belongsTo: 投稿の作成者
$user->roles;          // belongsToMany: 中間テーブル経由のロール
```

ループ内で`$user->posts`のように都度アクセスするとN+1クエリになります。件数が多いときは`App\Models\User::with('posts')->get()`のように`with`で先読み（Eager Loading）してから確認すると、発行クエリを抑えられます。リクエスト単位で実際に何本のクエリが飛んだかを追うなら[Laravel Telescopeとは何か？その機能と重要性を徹底解説](/tech/details/3386/)と併用すると把握しやすくなります。

## 作業を速くする組み込みコマンド

Tinker（PsySH）には、変数やクラスを調べるためのコマンドが用意されています。使い方に迷ったらまず`help`を打ちます。

| コマンド     | 用途                                     |
| -------- | -------------------------------------- |
| help     | 使えるコマンドの一覧を表示                          |
| ls       | スコープ内の変数・メソッド・定数を一覧                    |
| doc      | クラスや関数のドキュメントを表示（例 doc collect）        |
| show     | 対象のソースコードを表示（例 show App\\Models\\User） |
| dump     | 値を整形して出力                               |
| whereami | デバッグ中に現在位置を表示                          |
| history  | 過去に入力したコマンドを再表示                        |

直前に発生した例外のスタックトレースは`wtf`（詳細は`wtf -a`）で確認できます。またTinkerからは一部のArtisanコマンドも実行でき、実行を許可するコマンドは設定ファイルで制御します。`php artisan vendor:publish --provider="Laravel\Tinker\TinkerServiceProvider"`で`config/tinker.php`を生成すると、Tinker内で実行できるArtisanコマンドの許可リスト（既定は`clear-compiled`・`down`・`env`・`inspire`・`migrate`・`migrate:install`・`optimize`・`up`）やエイリアス設定を編集できます。

## 日本語が入力できないときの原因と対処

Tinkerで日本語を打つと文字が消える、確定できないという不具合は、Tinker固有の問題ではなくPHPの`readline`拡張の実装差に由来します。`readline`はGNU Readlineとlibedit（EditLine）のどちらかで実装されており、**libedit実装は多バイト文字の行編集に対応していない**ため日本語入力が壊れます。macOSのHomebrew版PHPなど、libeditでビルドされた環境で起きやすい問題です。

### どちらの実装かを確認する

次のコマンドで自分のPHPがどちらを使っているか判別できます。

```
php -i | grep -i readline
```

出力に`Readline Support => enabled`とあり、ライブラリ名が`EditLine wrapper`ならlibedit（日本語が壊れる側）、`GNU readline`なら問題なく入力できます。

### readline実装を切り替える手順

- **GNU readlineでビルドしたPHPに切り替える**のが根本対処です。ソースからなら`--with-readline`を付けて再ビルドし、パッケージ管理で読み替え可能な環境ならreadline版へ入れ替えます。
- **libeditを新しい版へ更新**して共有ライブラリのリンクを張り替える方法もあります（Linuxで採られる対処）。
- すぐに直せない場合は**`--execute`での非対話実行**や、対象の日本語を含む処理をファイルに書いて読み込ませる回避策が確実です（次章）。

DockerやLaravel Sailで文字化けする場合は、readlineの実装に加えてコンテナのロケール（`ja_JP.UTF-8`や`en_US.UTF-8`）と`mbstring`の設定も合わせて確認します。

## 対話せずに実行する方法と本番環境での注意

Tinkerは対話利用が基本ですが、CI・デプロイ手順・調査用スクリプトに組み込むなら**非対話実行**が向きます。1行だけなら`--execute`にコードを渡します。まとまった処理はファイルにして起動時の引数で読み込ませます。

```
php artisan tinker --execute="echo App\Models\User::count();"
php artisan tinker path/to/script.php
```

ここで強く言えるのは、**本番環境でTinkerを対話モードのまま更新・削除に使うべきではない**ということです。Tinkerは設定されたDBへそのまま接続するため、本番で打った`delete`や`where`忘れの`update`は取り消せません。本番でデータを触る必要があるときは、レビュー済みのスクリプトを`--execute`やファイル読込で流し、`DB::transaction()`で囲んで途中失敗時にロールバックできるようにします。動作確認はステージングやローカルで済ませ、本番では読み取り以外を極力避けるのが安全です。テスト用データの生成・投入は、Tinkerでの都度実行よりも[Laravelのテスト自動化をDuskで実装する方法｜インストールからCI実行まで](/tech/details/5648/)で扱う自動テストやシーダーに寄せると再現性が高まります。

## よくある質問

### php artisan tinkerとは何をするコマンドですか？

Laravelアプリを読み込んだ状態でPHPを対話実行するREPLを起動するコマンドです。PsySHを基盤にしており、Eloquentモデルの操作やリレーションの確認、設定値の参照などをコードファイルを作らずに試せます。

### Tinkerは別途インストールが必要ですか？

不要です。`laravel/tinker`はLaravelに標準同梱されており、新規プロジェクトなら最初から`php artisan tinker`が使えます。何らかの理由で外している場合のみ`composer require laravel/tinker`で追加します。

### Tinkerを終了するにはどうすればいいですか？

`exit`または`quit`と入力するか、`Ctrl+D`を押すと通常のコマンドラインに戻ります。

### Tinkerで日本語が打てないのはなぜですか？

PHPの`readline`拡張がlibedit（EditLine）実装だと多バイト入力に対応しないためです。`php -i | grep -i readline`で実装を確認し、GNU readline版のPHPに切り替えると解決します。応急処置は`--execute`での非対話実行です。

### Tinkerと通常のphp artisanコマンドの違いは何ですか？

`php artisan tinker`以外のArtisanコマンドは、あらかじめ定義された1つの処理（マイグレーションやキャッシュ削除など）を実行して終了します。Tinkerは処理を固定せず、任意のPHP・Eloquentを1行ずつ試せる対話環境である点が異なります。

## 関連記事

- [Laravelの命名規則一覧｜テーブル・モデル・コントローラーからコーディング規約まで](/tech/details/5468/)
- [Laravel Telescopeとは何か？その機能と重要性を徹底解説](/tech/details/3386/)
- [Laravelのテスト自動化をDuskで実装する方法｜インストールからCI実行まで](/tech/details/5648/)
- [LaravelでのEnum実装方法とその利点](/tech/details/4422/)
- [Laravel 12のリリース予定と新機能の詳細](/tech/details/5637/)

---

出典: [php artisan tinkerの使い方｜Laravel Tinkerの基本コマンドとEloquent操作](<https://www.issoh.co.jp/tech/details/4278/>)（株式会社一創）