Laravel 望远镜

Introduction

Laravel 望远镜 是您本地 Laravel 开发环境的绝佳伴侣。 Telescope 可以深入了解进入应用程序的请求、异常、日志条目、数据库查询、排队作业、邮件、通知、缓存操作、计划任务、变量转储等。

Installation

你可以使用 Composer 包管理器将 Telescope 安装到你的 Laravel 项目中：

composer require laravel/telescope

安装 Telescope 后，使用telescope:install 工匠命令。安装望远镜后，您还应该运行migrate 命令以创建存储 Telescope 数据所需的表：

php artisan telescope:install

php artisan migrate

迁移定制

如果你不打算使用 Telescope 的默认迁移，你应该调用Telescope::ignoreMigrations 中的方法register 你的应用程序的方法App\Providers\AppServiceProvider 班级。您可以使用以下命令导出默认迁移：php artisan vendor:publish --tag=telescope-migrations

仅本地安装

如果你打算只使用 Telescope 来协助你的本地开发，你可以使用--dev 旗帜：

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

运行后telescope:install，你应该删除TelescopeServiceProvider 从您的应用程序注册服务提供商config/app.php 配置文件。相反，在register 你的方法App\Providers\AppServiceProvider 班级。我们将确保当前环境是local 在注册提供者之前：

/**
 * Register any application services.
 */
public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

最后，你还应该防止 Telescope 包被auto-discovered 通过将以下内容添加到您的composer.json 文件：

"extra": {
    "laravel": {
        "dont-discover": [
            "laravel/telescope"
        ]
    }
},

Configuration

发布 Telescope 的资产后，其主要配置文件位于config/telescope.php.这个配置文件允许你配置你的观察者选项.每个配置选项都包含其用途的描述，因此请务必彻底浏览此文件。

如果需要，您可以使用enabled 配置选项：

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

数据修剪

在不修剪的情况下，telescope_entries table 可以非常快速地积累记录。为了减轻这种情况，你应该schedule 这telescope:prune 每天运行的 Artisan 命令：

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

默认情况下，将删除所有早于 24 小时的条目。您可以使用hours 调用命令时的选项以确定保留 Telescope 数据的时间。例如，以下命令将删除超过 48 小时前创建的所有记录：

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

仪表盘授权

可以在以下位置访问 Telescope 仪表板/telescope 路线。默认情况下，您只能在local 环境。在你的app/Providers/TelescopeServiceProvider.php 文件，有一个授权门 定义。此授权门控制对 Telescope 的访问non-local 环境。您可以根据需要自由修改此门以限制对 Telescope 安装的访问：

use App\Models\User;

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

Warning
你应该确保你改变你的APP_ENV 环境变量到production 在您的生产环境中。否则，您的 Telescope 安装将公开可用。

升级望远镜

升级到 Telescope 的新主要版本时，请务必仔细查看升级指南.

此外，当升级到任何新的 Telescope 版本时，您应该重新发布 Telescope 的资产：

php artisan telescope:publish

为了使资产保持最新并避免在未来的更新中出现问题，您可以添加vendor:publish --tag=laravel-assets 命令到post-update-cmd 应用程序中的脚本composer.json 文件：

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
        ]
    }
}

Filtering

Entries

您可以通过以下方式过滤 Telescope 记录的数据filter你定义的闭包App\Providers\TelescopeServiceProvider 班级。默认情况下，这个闭包记录了所有数据local 环境和异常、失败的作业、计划的任务以及所有其他环境中带有监控标签的数据：

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

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

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

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

Batches

虽然filter 闭包过滤单个条目的数据，您可以使用filterBatch 注册闭包的方法，该闭包过滤给定请求或控制台命令的所有数据。如果闭包返回true，所有条目都由 Telescope 记录：

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

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

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

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

Tagging

Telescope 允许您通过“标签”搜索条目。通常，标签是 Eloquent 模型类名称或 Telescope 自动添加到条目中的经过身份验证的用户 ID。有时，您可能希望将自己的自定义标签附加到条目中。为此，您可以使用Telescope::tag 方法。这tag 方法接受一个应该返回标签数组的闭包。闭包返回的标签将与 Telescope 自动附加到条目的任何标签合并。通常，您应该调用tag 内的方法register 你的方法App\Providers\TelescopeServiceProvider 班级：

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

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

    Telescope::tag(function (IncomingEntry $entry) {
        return $entry->type === 'request'
                    ? ['status:'.$entry->content['response_status']]
                    : [];
    });
 }

可用观察者

望远镜“观察者”在执行请求或控制台命令时收集应用程序数据。您可以自定义要在您的config/telescope.php 配置文件：

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

一些观察者还允许您提供额外的自定义选项：

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

批次观察者

批处理观察器记录有关排队的信息batches，包括作业和连接信息。

缓存观察者

当缓存键被命中、丢失、更新和遗忘时，缓存观察器会记录数据。

命令观察者

每当执行 Artisan 命令时，命令观察器都会记录参数、选项、退出代码和输出。如果你想排除某些命令被观察者记录，你可以在ignore 你的选项config/telescope.php 文件：

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

转储观察者

转储观察器记录并显示 Telescope 中的变量转储。使用 Laravel 时，可以使用全局变量转储dump 功能。转储观察器选项卡必须在浏览器中打开才能记录转储，否则转储将被观察器忽略。

事件观察者

事件观察器记录任何负载、监听器和广播数据events 由您的应用程序发送。 Laravel 框架的内部事件会被 Event watcher 忽略。

异常观察者

异常观察器记录应用程序抛出的任何可报告异常的数据和堆栈跟踪。

守门人

守门员记录数据和结果大门和政策 由您的应用程序检查。如果你想排除某些能力被观察者记录，你可以在ignore_abilities 你的选项config/telescope.php 文件：

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

HTTP 客户端观察器

HTTP 客户端观察器记录传出HTTP 客户端请求 由您的应用程序制作。

工作观察员

工作观察者记录任何数据和状态jobs 由您的应用程序发送。

日志观察者

日志观察者记录日志数据 对于您的应用程序编写的任何日志。

默认情况下，Telescope 只会在error 级及以上。但是，您可以修改level 应用程序中的选项config/telescope.php 配置文件来修改此行为：

'watchers' => [
    Watchers\LogWatcher::class => [
        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
        'level' => 'debug',
    ],

    // ...
],

邮件观察者

邮件观察器允许您查看浏览器内的预览emails 由您的应用程序连同其相关数据一起发送。您也可以将电子邮件下载为.eml 文件。

模型观察者

每当 Eloquent 出现时，模型观察者就会记录模型的变化模型事件 被派遣。您可以指定应通过观察者的记录哪些模型事件events 选项：

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

如果您想记录在给定请求期间水化的模型数量，请启用hydrations 选项：

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

通知观察者

通知观察者记录所有notifications 由您的应用程序发送。如果通知触发电子邮件并且您启用了邮件观察器，则该电子邮件也可以在邮件观察器屏幕上预览。

查询观察者

查询观察器记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。观察者还将任何慢于 100 毫秒的查询标记为slow.您可以使用观察者的自定义慢查询阈值slow 选项：

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

Redis观察者

Redis 观察者记录所有Redis 您的应用程序执行的命令。如果你使用 Redis 做缓存，缓存命令也会被 Redis watcher 记录下来。

请求观察者

请求观察器记录与应用程序处理的任何请求相关联的请求、标头、会话和响应数据。您可以通过以下方式限制您记录的响应数据size_limit （以千字节为单位）选项：

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

日程观察者

调度观察器记录任何命令和输出计划任务 由您的应用程序运行。

查看观察者

视图观察者记录view 渲染视图时使用的名称、路径、数据和“作曲家”。

显示用户头像

Telescope 仪表板显示在保存给定条目时经过身份验证的用户的用户头像。默认情况下，Telescope 将使用 Gravatar 网络服务检索头像。但是，您可以通过在您的App\Providers\TelescopeServiceProvider 班级。回调将接收用户的 ID 和电子邮件地址，并应返回用户的头像图像 URL：

use App\Models\User;
use Laravel\Telescope\Telescope;

/**
 * Register any application services.
 */
public function register(): void
{
    // ...

    Telescope::avatar(function (string $id, string $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}
豫ICP备18041297号-2
Please enter a query in order to search.