こんにちは！
九保すこひです（フリーランスのITコンサルタント、エンジニア）

さてさて、Laravelはすでに多くの便利な機能を揃えていて、何か特定の機能がほしい場合、ほぼどんなものでもその解決に役立つものが見つかるというのが現状です。

ただ、そうはいってもたった１つの機能で全てをカバーできるわけではなく、クライアントさんのご希望にできるだけ添えるようにするには、複数の機能を連携させて（もしくは足りない部品は自分でつくって）様々なシステムを開発していくのが通常ではないでしょうか。

しかし、そうなってくるとより必要性を増してくるのが「デバッグ」です。

ある部分を変更すると、全く違う部分にも影響が出てくるということもしばしばあることなので、しっかりしたデバッグ・ツールをもっているというのは開発者にとって大きなアドバンテージになります。

そこで！

今回はそんなデバッグができるLaravel公式のデバッグ・パッケージ「Laravel Telescope」の使い方をまとめみます。

ぜひ開発の参考にしてくださいね。

※ 開発環境： Laravel 5.7.13

インストールする

Larave Telescopeは、Laravelのパッケージとして公開されているので、composerで一気にインストールすることができます。

composer require laravel/telescope

続いてartisanコマンドでLaravel本体へインストールを実行します

php artisan telescope:install

このコマンドが実行されると、次の３ヶ所にファイルがコピーされています。

app/Providers/TelescopeServiceProvider.php
config/telescope.php
public/vendor/telescope/*

※ なお、このコマンドを実行すると以下のようなエラーが発生することがありますが、これはまだテーブルが存在していないために発生しています。気にせず次のマイグレーションを実行してください。

local.ERROR: SQLSTATE[42S02]: Base table or view not found

次にマイグレーションを実行してDBにテーブルをつくります。

php artisan migrate

マイグレーションが終わるとテーブル内にtelescope_*****というテーブルが３つ作成されています。

ではインストールが完了しましたのでhttps://******.com/telescopeへアクセスしてみましょう。

次のような、ちょっとおしゃれなページが表示されれば成功です。

では次の項目から各ページの内容を見ていきましょう。

Laravel telescopeの各ページ

Requests

Requestsは、アクセスがあったページの詳細を確認することができるページです。
実際に/loginにアクセスした後Requestsを見てみましょう。

このようにアクセスしたページがひとつずつ登録されています。
そして、このページにアクセスされた時の詳細を見るためには一番右側にある目のマークをクリックします。

すると、ページ上部に日時やHTTPメソッドなどの情報が表示され、

さらにページ下部には、

Payload　・・・　GETやPOSTなどの送信データ
Headers　・・・　ヘッダー情報
Session　・・・　折衝情報
Response　・・・　レスポンス（ビューやリダイレクトなど）

の情報を確認することができます。

comannds

過去に実行されたartisanコマンドの履歴を確認することができます。
ではphp artisan migrateを実行した後でこのページを確認してみましょう。

「php artisan」を除いたコマンド名が表示されています。

また、一番右側の目のマークをクリックするとその詳細を表示することができます。

Schedule

Laravelに登録されたスケジュールが実行された時の履歴です。
今回はテストとして、app/Console/Kernel.php内に次のようなスケジュールを登録して実行してみました。

protected function schedule(Schedule $schedule)
{
     $schedule->command('inspire')->everyMinute(); // 毎分実行されます
}

※ ちなみにinspireコマンドは以下の名言が表示されるおまけ的なコマンドになります。

Simplicity is an acquired taste. – Katharine Gerould

では実行結果です。
このように絶対パスを含むコマンドが表示されました。

目のマークをクリックすると次のような詳細が確認できます。

Jobs

Laravelで設定されたキュー（Queue）の履歴を確認するページです。

では、テストでTestJobという名前のJobを作り、sync（同期）形式のまま実際に実行してみます。

php artisan make:job TestJob

\App\Jobs\TestJob::dispatch(); // ジョブを実行

すると実行されたジョブは次のようにリスト表示されます。

一番右側の目のマークをクリックすると詳細が表示されます。

Exceptions

Laravelで発生した例外（エラーのようなもの）の一覧を確認できるページです。
では、今回は存在しないartisanコマンドを実行して例外を発生させてみましょう。

php artisan xxx

結果はこうなります。

ちなみにこのページが他と比嘉うのはOccurrencesの部分です。これは「発生回数」です。つまり同じExceptionはひとつにまとめてくれるというわけですね。

そして、目のマークをクリックすると次のような詳細が表示されます。

ここで、「View Other Occurrences」をクリックすると、その他に発生した同じExceptionの一覧が表示され、それぞれの詳細を確認することができます。

Logs

Logsは過去の保存されたログの一覧を表示するページです。
では、次のコードを実行してログを作成してtelescopeで確認してみましょう。

\Log::emergency('システムがダウンしています！');

結果はこうなります。

そして、目のマークをクリックすると詳細が表示されます。

なお、「View Request」をクリックするとRequestsの該当ページへ移動することになります。

Dumps

artisanコマンドにあるDump Serverが実行された履歴になります。

では、テストで実際にDump Serverを起動してみます。

php artisan dump-server

するとこのようにデータ送信を待ち構えている表示になりました。

この状態で次のコードを実行してみます。

dump(['key' => 'value']);

するとDumpsページはこのようになります。

Queries

DBにアクセスしたクエリーの一覧を確認するページです。
今回はテストとして次のコードを実行してみます。

$user = \App\User::find(1);

するとQueriesページはこのようになります。

さらに、詳細ページはこうなります。

ちなみにLocationはDBクエリーが実行されたファイルの位置になります。
デバッグするにはこういうものまで表示してくれると嬉しいですね。

また、「View Request」をクリックするとRequestsの該当ページへ移動することができます。

Models

モデル（つまりDBテーブル）に追加や更新、削除があった履歴を確認するページです。
では、次のように新規ユーザーを登録してみましょう。

$user = new \App\User();
$user->name = '三郎';
$user->email = 'saburo@example.com';
$user->password = bcrypt('********');
$user->save();

すると、Modelsページはこうなります。
（IDまで分かるのはありがたいですね）

詳細ページはこうなります。

「View Request」をクリックするとRequestsの該当ページへ移動することができます。

Events

Eventが実行されたときの履歴情報になります。
では、新規ユーザーが登録されたときに実行されるUserCreatedイベントをを実行してみましょう。

まずはコマンドでイベントファイルをつくります。

php artisan make:event UserCreated

そして、作成したUserCreated.phpを開いてコンストラクタを次のように変更します。（つまりJSONで表示するだけです）

public function __construct(User $user)
{
    echo $user;
}

そして、User.phpに$dispatchesEventsを登録します。

protected $dispatchesEvents = [
    'created' => UserCreated::class
];

ではイベントを実行してみましょう。
結果はこうなります。

そして、詳細ページはこちら。

なお、「View Request」をクリックするとRequestsの該当ページへ移動することができます。

Mail

送信されたメール内容を確認するページです。

今回は以前Laravel + Vue で問い合わせフォームをつくるで作ったContactedという名前のMailableを使ってメール送信してみます。

まずは、.envでメール送信はlogにします。（こうするとメール送信の環境が整っていなくてもエラーが発生することはなくなるからです）

MAIL_DRIVER=log

そして、実際にメール送信した後のMailページがこちらです。

そして詳細ページです。

メール本文が表示されているのもそうですが、.emlファイルとして内容をダウンロードすることもできます。

ちなみに.emlファイルは次のような内容になります。

Notifications

Laravelで送信された通知の履歴を確認するページです。
Laravel 5.7 の新機能まとめで開発したOrderedを使って通知してみます。

実行結果はこうなります。

そして、詳細ページです。

対象となったモデルとIDまで分かるのは嬉しいですね。

また、「View Request」をクリックするとRequestsの該当ページへ移動することができます。

Cache

キャッシュされたデータを確認するページです。
テストとして以下のコードを実行してから確認してみましょう。

cache(['test' => 'テストです'], 10);

実際の結果です。

ちなみにキャッシュは保存したときだけでなく、以下のようなActionが存在しています。

set　・・・　キャッシュが保存された
hit　・・・　キャッシュを取得した
missed　・・・　キャッシュを取得しようとしたが存在してなかった
forget　・・・　キャッシュを削除した

そして、詳細ページではキャッシュの内容も表示してくれます。

Expireが有効時間、Valueがキャッシュの中身です。

また、「View Request」をクリックするとRequestsの該当ページへ移動することができます。

Redis

redisを使った履歴を確認するページです。
では、redisサーバーを起動し、さらに.envでキャッシュのドライバーをredisへ変更して実際に試してみましょう。

CACHE_DRIVER=redis

cache(['test' => 'テストです'], 10);

※ 注意

この記事を書いているほんの少し前にパッケージの仕様に変更があり、RedisMangerのイベントが初期状態でfalseになってしまいました。この影響で手動でRedisManagerがイベントを実行できるよう設定する必要があるのですが、GitHubのIssueにはServiceProviderでRedis::enableEvents();を追加すればいけると書かかれいますが、タイミングが前後してしまってうまくいきませんでした。

そのため、今回はRedisServiceProviderを継承したExtendedRedisServiceProviderを作ってconfig/app.phpへ登録します。

// Illuminate\Redis\RedisServiceProvider::class,
\App\Providers\ExtendedRedisServiceProvider::class,

（app/Providers/ExtendedRedisServiceProvider.php）

<?php

namespace App\Providers;

use Illuminate\Redis\RedisManager;
use Illuminate\Redis\RedisServiceProvider;
use Illuminate\Support\Arr;

class ExtendedRedisServiceProvider extends RedisServiceProvider
{
    /**
     * Register services.
     *
     * @return void
     */
    public function register()
    {
        $this->app->singleton('redis', function ($app) {
            $config = $app->make('config')->get('database.redis', []);

            $manager = new RedisManager($app, Arr::pull($config, 'client', 'predis'), $config);
            $manager->enableEvents();
            return $manager;
        });

        $this->app->bind('redis.connection', function ($app) {
            return $app['redis']->connection();
        });
    }
}

では実際の結果です。

そして詳細ページです。

各ページの追加情報

ユーザー情報

もしログインした状態であれば各ページに次のようなユーザー情報も追加してくれます。

DBのクエリー情報

DBへのアクセスがあればクエリー情報まで表示してくれる親切設計です。

タグ検索

各ページの一覧にはタグ検索ができるようになっているものがあります。
次の例はAuth:1、つまりユーザーID１の人がアクセスしたデータだけ表示する方法です。

Telescopeのコマンド

telescope:clear でデバッグ情報を削除する

DBテーブル内の全デバッグ情報を削除するコマンドです。

php artisan telescope:clear

telescope:install でインストール

このページ冒頭のインストールするをご覧ください。

php artisan telescope:install

telescope:prune で古いデバッグ情報を削除する

php artisan telescope:prune

毎日古いデバッグ情報を削除するには、app/Console/Kernel.phpのschedule()へ次のように登録しておくといいでしょう。

protected function schedule(Schedule $schedule)
{
    $schedule->command('telescope:prune')->daily();
}

telescope:publish

Laravel Telescopeのパブリッシュ（ファイルのコピー）をするコマンドです。
Telescopeはまだまだ開発中ですので、アップデートした場合はこのコマンドを実行してコードを最新のものにキープしておきましょう。

コンフィグ

config/telescope.phpの説明です。

path

Laravel TelescopeのURLが決定されます。
初期状態では “telescope”なのでhttps://****.com/telescopeがURLになりますが、

'path' => 'telescope',

下記のようにdebugへ変更した場合はhttps://****.com/debugがURLになります。

'path' => 'debug',

.envで設定できること

TELESCOPE_DRIVER

デバッグを保存するドライバーです。
初期値は “database” です。

DB_CONNECTION

データベースの接続情報です。
初期値は “mysql” です。

TELESCOPE_ENABLED

Laravel Telescopeを有効にするかどうかです。
初期値は、“true”。

各種ウォッチャーを使うかどうかの設定

以下のウォッチャー（つまり、デバッグ情報を保存する監視コード）を使うかどうかをtrue or false で指定することができます。（デフォルトは全てtrue）

TELESCOPE_CACHE_WATCHER　・・・　キャッシュ
TELESCOPE_COMMAND_WATCHER　・・・　コマンド
TELESCOPE_DUMP_WATCHER　・・・　DUMP
TELESCOPE_EVENT_WATCHER　・・・　イベント
TELESCOPE_EXCEPTION_WATCHER　・・・　例外（Exception）
TELESCOPE_JOB_WATCHER　・・・　ジョブ（Queue）
TELESCOPE_LOG_WATCHER　・・・　ログ
TELESCOPE_MAIL_WATCHER　・・・　メール
TELESCOPE_MODEL_WATCHER　・・・　モデル
TELESCOPE_NOTIFICATION_WATCHER　・・・　通知（Notification）
TELESCOPE_QUERY_WATCHER　・・・　DBクエリー
TELESCOPE_REDIS_WATCHER　・・・　Redis
TELESCOPE_REQUEST_WATCHER　・・・　Request
TELESCOPE_RESPONSE_SIZE_LIMIT　・・・　スケジュール

TELESCOPE_RESPONSE_SIZE_LIMIT　・・・　レスポンスの最大サイズ

特定のユーザーだけTelescopeにアクセスできるようにする

app/Providers/TelescopeServiceProvider.phpの中にgate()というメソッドがあるので、この中で以下のように設定します。

例えば、メールアドレスがtaro@example.comとなっているユーザーだけ閲覧ができるようにするにはこのようにします。

Gate::define('viewTelescope', function ($user) {
    return in_array($user->email, [
        'taro@example.com'
    ]);
});

※ 注意：ただしこの設定の効果があるのは.envのAPP_ENVが “local” 「以外」の場合です。もし “local” の場合は、設定をしようがしまいが誰でもアクセスできてしまいます。

また、もしroleなどユーザータイプが分かるデータをもっているのであれば次のようなコードでもいいでしょう。

protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return ($user->role == 'admin');
    });
}

特定の環境にだけTelescopeをインストールする

特定の環境にだけTelescopeをインストールするにはcomposerコマンドに--devをつけて実行します。

composer require laravel/telescope --dev

ただし、production（本番）やstaging（テスト）環境などでは存在しないパッケージとなってしまいますので、config/app.phpで登録されているTelescopeServiceProviderはコメントアウトするなどして実行されないようにしておきましょう。

// App\Providers\TelescopeServiceProvider::class,

また、そうなるとローカル環境への登録がなくなってしまうので、代わりにapp/Providers/AppServiceProvider.phpに次のように環境で切り替わる登録をしておきましょう。

public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(TelescopeServiceProvider::class);
    }
}

もしくは、次のように環境名を指定する方法でもいいでしょう。

if (env('APP_ENV') == 'production') {
    $this->app->register(TelescopeServiceProvider::class);
}

お問い合わせ、お待ちしております。

開発のご依頼はこちら: お問い合わせ

どうぞよろしくお願いいたします！ by 九保すこひ

全28項目！Laravel Telescope使い方のまとめ

インストールする

Laravel telescopeの各ページ

Requests

comannds

Schedule

Jobs

Exceptions

Logs

Dumps

Queries

Models

Events

Mail

Notifications

Cache

Redis

各ページの追加情報

ユーザー情報

DBのクエリー情報

タグ検索

Telescopeのコマンド

telescope:clear でデバッグ情報を削除する

telescope:install でインストール

telescope:prune で古いデバッグ情報を削除する

telescope:publish

コンフィグ

path

.envで設定できること

TELESCOPE_DRIVER

DB_CONNECTION

TELESCOPE_ENABLED

各種ウォッチャーを使うかどうかの設定

特定のユーザーだけTelescopeにアクセスできるようにする

特定の環境にだけTelescopeをインストールする

あわせて読みたい！