本地开发调试解决方案：Laravel Telescope

简介

Laravel Telescope 是一个专门为 Laravel 框架打造的优雅的调试助手。Telescope 可以为进入应用的请求、异常、日志、数据库查询、队列任务、邮件、通知、缓存操作、调度任务、变量打印等所有操作提供洞察明细功能，因此，它将成为你本地 Laravel 开发环境的又一绝佳伴侣。

安装

注：Telescope 要求 Laravel 5.7.7+ 版本。你可以通过 php artisan --version 查看自己的 Laravel 版本。

你可以使用 Composer 来安装 Telescope 到 Laravel 项目：

composer require laravel/telescope

安装完成后，使用 Artisan 命令 telescope:install 发布其公共资源，然后运行 migrate 命令执行数据库变更：

php artisan telescope:install
php artisan migrate

更新 Telescope

更新 Telescope 的时候，需要重新发布公共资源：

php artisan telescope:publish

只在指定环境安装

如果你计划只在本地开发环境安装 Telescope，可以在安装的时候使用 --dev 标记：

composer require laravel/telescope --dev

安装完成后，需要从 app 配置文件中移除 TelescopeServiceProvider 服务提供者的注册。取而代之地，要手动在 AppServiceProvider 的 register 方法中注册它：

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(TelescopeServiceProvider::class);
    }
}

迁移自定义

如果你不想使用 Telescope 的默认迁移，可以在 AppServiceProvider 的 register 方法中调用 Telescope::ignoreMigrations 方法。然后通过 php artisan vendor:publish --tag=telescope-migrations 命令导出默认迁移文件进行自定义。

配置

发布完 Telescope 的公共资源后，它的配置文件位于 config/telescope.php。该配置文件允许你配置监听选项 watchers，每个配置项都包含其用途说明，所以建议你使用 Telescope 之前通篇读一下这个配置文件。

如果需要，你可以完全禁止 Telescope 的数据收集功能，通过配置项 enabled 来设置即可：

'enabled' => env('TELESCOPE_ENABLED', true),

数据清理

如果没有清理的话，telescope_entries 表会迅速累积记录。要缓解这一现状，需要通过调度任务每天运行 Artisan 命令 telescope:prune 来清理老数据：

$schedule->command('telescope:prune')->daily();

默认情况下，所有 24 小时之前的数据都会被清理，你可以在运行上述命令的时候使用 hours 选项来决定要保存多长时间以内的 Telescope 数据。例如，下面这个命令将会删除所有 48 小时以前创建的数据：

$schedule->command('telescope:prune --hours=48')->daily();

后台授权

Telescope 可以通过 /telescope 后台访问。和 Horizon 一样，默认情况下，你只能在本地开发环境（local）下访问。在你的 app/Providers/TelescopeServiceProvider.php 文件中，有一个 gate 方法，通过该访问控制方法，可以配置哪些用户可以在非本地环境访问 Telescope 后台，你可以根据需要随时修改该方法，以便限制对 Telescope 的访问：

/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

过滤

单个条目

你可以通过 TelescopeServiceProvider 中注册的 filter 回调过滤 Telescope 记录的数据。默认情况下，该回调记录 local 环境中所有的数据以及其他环境中的异常、失败任务、调度任务和被打上监控标签的数据：

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->hasMonitoredTag();
    });
}

批量过滤

filter 回调可用于过滤单个条目的数据，而 filterBatch 方法可用于注册过滤回调用来过滤给定请求或控制台命令对应的所有数据。如果该回调返回 true，则对应的条目都会被 Telescope 记录：

use Illuminate\Support\Collection;

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
            });
    });
}

有效的监控器

当执行请求或控制台命令时，Telescope 监控器可以聚合相应的应用数据。你可以在配置文件 config/telescope.php 中自定义想要启用的监控器列表：

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

有些监控器还允许你提供额外的自定义选项：

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

缓存监控器

缓存监控器会在缓存键被命中、错过、更新和删除的时候记录数据。

命令监控器

不管 Artisan 命令是否执行，命令监控器都会记录参数、选项、退出码和输出。如果你想要从监控器记录中排除特定命令，可以在 config/telescope.php 文件的 ignore 选项中指定对应命令：

'watchers' => [
    Watchers\CommandWatcher::class => [
        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
        'ignore' => ['key:generate'],
    ],
    ...
],

Dump 监控器

dump 监控器会在 Telescope 中记录并显示变量 dump。使用 Laravel 的时候，可以通过 dump 函数打印变量。如果要记录变量打印，必须在浏览器中打开 dump 监控器标签页，否则会被忽略。

事件监控器

事件监控器会记录所有应用分发事件记录负载数据、监听器和广播数据。Laravel 框架的内部事件则会被忽略。

异常监控器

异常监控器会为所有应用抛出的可报告异常记录数据和堆栈信息。

Gate 监控器

gate 监控器会记录应用 gate 和 policy 检查数据和结果。如果你想要排除监控器记录的特定权限检查，可以在 config/telescope.php 文件的 ignore_abilities 选项中指定它们：

'watchers' => [
    Watchers\GateWatcher::class => [
        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
        'ignore_abilities' => ['viewNova'],
    ],
    ...
],

任务监控器

任务监控器会记录应用分发的队列任务数据和状态。

日志监控器

日志监控器会记录应用写入的所有日志数据。

邮件监控器

邮件监控器允许你在浏览器中预览邮件以及与之相关联的数据，还可以以 .eml 格式下载邮件文件。

模型监控器

模型监控器会 Eloquent created、updated、restored 或者 deleted 事件触发时记录模型变更，你可以通过监控器的 events 选项指定记录哪些模型事件：

'watchers' => [
    Watchers\ModelWatcher::class => [
        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
        'events' => ['eloquent.created*', 'eloquent.updated*'],
    ],
    ...
],

通知监控器

通知监控器会记录应用发送的所有通知。如果通知触发了邮件发送同时你也开启了邮件监控器，则该邮件还可以在邮件监控界面进行预览。

查询监控器

查询监控器记录应用执行的所有数据库查询对应的原生 SQL、绑定、执行时间。该监控器还会将时间慢于 100ms 的查询打上 slow 标签。你可以使用 show 选项自定义慢查询阈值：

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redis 监控器

注：要让 Redis 监控器生效，必须开启 Redis 事件。你可以通过在 app/Providers/AppServiceProvider.php 文件的 boot 方法中调用 Redis::enableEvents() 来启用 Redis 事件。

Redis 监控器会记录应用执行的所有 Redis 命令，如果你在使用 Redis 驱动的缓存，则相应的缓存命令也会被 Redis 监控器记录。

请求监控器

请求监控器会记录应用处理的所有请求关联的请求数据、请求头、会话和响应数据，你可以通过 size_limit 选项（单位：KB）来限制响应数据：

'watchers' => [
    Watchers\RequestWatcher::class => [
        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
    ],
    ...
],

调度监控器

调度监控器会记录应用运行的所有调度任务对应的命令和输出。