Laravel 8 中文文档 Telescope 调试工具
简介
Laravel Telescope 是 Laravel 框架的优雅调试助手。Telescope 提供了对进入您的应用程序的请求、异常、日志条目、数据库查询、排队的作业、邮件、通知、缓存操作、定时计划任务、变量转储等的深入了解。 Telescope 是您本地 Laravel 开发环境的绝佳伴侣。
安装
您可以使用 Composer 将 Telescope 安装到 Laravel 项目中：
composer require laravel/telescope
安装 Telescope 后，请使用 Artisan 命令 telescope:install 发布其资产。 安装 Telescope 后，您还应该运行 migrate 命令：
php artisan telescope:install
php artisan migrate
仅在特定环境中安装
如果您打算仅使用 Telescope 来协助您的本地开发。可以使用 --dev 标志安装 Telescope：
composer require laravel/telescope --dev
运行 telescope:install 后，您应该从 app 配置文件中删除 TelescopeServiceProvider 服务提供注册。相反，在 AppServiceProvider 的 register 方法中手动注册服务：
/**
* 注册应用服务
*
* @return void
*/
public function register()
{
if ($this->app->isLocal()) {
$this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
}
}
你还应该将以下内容添加到你的composer.json文件中来防止Telescope扩展包被 自动发现。
"extra": {
"laravel": {
"dont-discover": [
"laravel/telescope"
]
}
},
定制数据迁移
如果您不打算使用 Telescope 的默认迁移，则应该在 AppServiceProvider 的 register 方法中调用 Telescope::ignoreMigrations 方法。您可以使用 php artisan vendor:publish --tag=telescope-migrations 命令导出默认迁移。
配置
使用 Telescope，其主要配置文件将位于 config/telescope.php。此配置文件允许您配置监听程序选项，每个配置选项都包含其用途说明，因此请务必彻底浏览此文件。
如果需要，您可以使用 enabled 配置选项完全禁用 Telescope 的数据收集：
'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 即可显示仪表盘。 默认情况下，您只能在 local 环境中访问此仪表板。在你的 app/Providers/TelescopeServiceProvider.php 文件中，有一个 gate 方法。此授权能控制在 非本地 环境中对 Telescope 的访问。您可以根据需要随意修改此权限以限制对 Telescope 安装和访问：
/**
* 注册 Telescope gate
*
* 该 gate 确定谁可以在非本地环境中访问 Telescope
*
* @return void
*/
protected function gate()
{
Gate::define('viewTelescope', function ($user) {
return in_array($user->email, [
'taylor@laravel.com',
]);
});
}
注意：你应该确保在生产环境中将
APP_ENV环境变量更改为Production。 否则，你的 Telescope 调试 工具 将公开可用。
更新 Telescope
升级到Telescope的新主要版本时，务必仔细阅读 升级指南。
此外，升级到任何新的Telescope版本时，你应该重新配置加载 Telescope 实例：
php artisan telescope:publish
为了使实例保持最新状态并避免将来的更新中出现问题，可以在应用程序的 composer.json文件中的 post-update-cmd 脚本添加 telescope:publish 命令：
{
"scripts": {
"post-update-cmd": [
"@php artisan telescope:publish --ansi"
]
}
}
过滤
单项过滤
您可以通过在 TelescopeServiceProvider 中注册的 filter 回调来过滤 Telescope 记录的数据。默认情况下，此回调会记录 本地 环境中的所有数据以及所有其他环境中的异常、进程中断、计划任务和带有受监控标记的数据：
/**
* 注册应用服务
*
* @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;
/**
* 注册应用服务
*
* @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 允许你通过 tag 搜索条目。 通常，标签是 Eloquent 模型的类名或经过身份验证的用户 ID， 这些标签会自动添加到条目中。有时，您可能希望将自己的自定义标签附加到条目中。 你可以使用 Telescope::tag 方法。 tag 方法接受一个回调，该回调应返回一个标签数组。回调返回的标签将与 telescope 自动附加到条目的任何标签合并。您应该在 TelescopeServiceProvider 中调用 tag 方法:
use Laravel\Telescope\Telescope;
/**
* 注册应用服务
*
* @return void
*/
public function register()
{
$this->hideSensitiveRequestDetails();
Telescope::tag(function (IncomingEntry $entry) {
if ($entry->type === 'request') {
return ['status:'.$entry->content['response_status']];
}
return [];
});
}
可用的监听器
当在控制台执行命令或处理请求时，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'],
],
...
],
数据监听
数据监听器在 Telescope 中记录并显示您的数据变量。使用 Laravel 时，可以使用全局 dump 函数输出变量。必须在浏览器中打开数据监听器选项卡，才能进行输出变量，否则监听器将忽略此次输出。
事件监听
事件监听器记录应用程序调度的任何事件的有效负载、监听器和广播数据。事件监听器忽略了 Laravel 框架的内部事件。
异常监听
异常监听器记录应用程序引发的任何可报告异常的数据和堆栈跟踪。
Gate 监听
Gate 监听器记录您的应用程序的 Gate 和策略检查的数据和结果。如果您希望将某些能力排除在监听器的记录之外，您可 config/telescope.php 文件的 ignore_abilities 选项中指定它们：
'watchers' => [
Watchers\GateWatcher::class => [
'enabled' => env('TELESCOPE_GATE_WATCHER', true),
'ignore_abilities' => ['viewNova'],
],
...
],
Job 任务监听
任务监听器记录应用程序分派的任何作业的数据和状态。
日志监听
日志监视器记录应用程序写入的任何日志的日志数据。
邮件监听
邮件监视器允许您查看电子邮件的浏览器内预览及其相关数据。您也可以将该电子邮件下载为 .eml 文件。
模型监听
只要触发了模型的 create 、updated 、restored 或 deleted 事件，模型观察器就会记录模型更改。您可以通过监听器的 events 选项指定应记录哪些模型事件：
'watchers' => [
Watchers\ModelWatcher::class => [
'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
'events' => ['eloquent.created*', 'eloquent.updated*'],
],
...
],
消息通知监听
消息通知监听器记录您的应用程序发送的所有通知。如果通知触发了电子邮件并且您启用了邮件监听器，则电子邮件也可以在邮件监视器屏幕上进行预览。
数据查询监听
数据查询监听器记录应用程序执行的所有查询的原始 SQL 、绑定和执行时间。观察者还将任何慢于 100 毫秒的查询标记为 slow 。您可以使用观察者的 slow 选项自定义慢查询阈值：
'watchers' => [
Watchers\QueryWatcher::class => [
'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
'slow' => 50,
],
...
],
Redis 监听
Redis 监听器记录您的应用程序执行的所有 Redis 命令。如果您使用 Redis 进行缓存，Redis 监听器也会记录缓存命令。
请求监听
请求监听器记录与应用程序处理的任何请求相关联的 request 、headers 、session 和 response 数据。您可以通过 size_limit （以 KB 为单位）选项限制响应数据：
'watchers' => [
Watchers\RequestWatcher::class => [
'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
],
...
],
定时任务监听
schedule 监听器记录应用程序运行的任何计划任务的命令和输出。
显示用户头像
Telescope 仪表盘显示保存给定条目时会有登录用户的用户头像。 默认情况下，Telescope 将使用 Gravatar Web 服务检索化身。 但是，您可以通过在TelescopeServiceProvider中注册一个回调来自定义头像URL。 回调将收到用户的ID和电子邮件地址，并应返回用户的头像图像URL：
use App\Models\User;
use Laravel\Telescope\Telescope;
/**
* 注册应用服务
*
* @return void
*/
public function register()
{
Telescope::avatar(function ($id, $email) {
return '/avatars/'.User::find($id)->avatar_path;
});
}