Laravel - Package - Telescope (官方文件原子化翻譯)

Dev 11 分钟 讀完 (大概 1714 字)

# 前言

學習一個框架, Ray 的想法是, 在深入理解底層實作的原理之前, 應該先知道這個框架的 使用方法; 先學習怎麼使用這個前人造的輪子, 再學習怎麼樣造一個輪子。
所以本篇文章重點在於細讀官方文件, 並將內容理解後以 Q&A 的方式記錄下來, 加速學習以及查詢。


# Installation

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    composer require laravel/telescope

    php artisan telescope:install

    php artisan migrate
  • Answer:
    安裝 telescope 套件
    安裝相關 UI
    migrate 資料庫
以下的 Laravel example code 的意思是？
  • Example:
    // terminal
    composer require laravel/telescope --dev

    php artisan telescope:install

    php artisan migrate

    // AppServiceProvider
    public function register()
    {
        if ($this->app->environment('local')) {
            $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
            $this->app->register(TelescopeServiceProvider::class);
        }
    }

    // composer.json
    "extra": {
        "laravel": {
            "dont-discover": [
                "laravel/telescope"
            ]
        }
    },
  • Answer:
    若只要安裝 telescope 在 dev
    要從 config/app.php 當中移除 telescope service provider
    在 AppServiceProvider 中另行註冊
    修改 composer.json 避免 auto-discover

# Configuration

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    'enabled' => env('TELESCOPE_ENABLED', true),
  • Answer:
    可使用 env 來決定是否 enable Telescope
    更多設定可參考 config/telescope.php

# Data Pruning

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    $schedule->command('telescope:prune')->daily();
  • Answer:
    定義一個 scheduled task, 每天清空 telescope 的紀錄
以下的 Laravel example code 的意思是？
  • Example:
    <?php
    $schedule->command('telescope:prune --hours=48')->daily();
  • Answer:
    定義一個 scheduled task, 每天清空 telescope 48 小時前的紀錄
以下的 Laravel example code 的意思是？
  • Example:
    <?php
    {
        "scripts": {
            "post-update-cmd": [
                "@php artisan telescope:publish --ansi"
            ]
        }
    }
  • Answer:
    當更新 Laravel Telescope 後, 務必要 re-publish Telescope’s asserts, 可以寫在 composer.json 中, 以免忘記

# Filtering

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    public function register()
    {
        $this->hideSensitiveRequestDetails();

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

            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
        });
    }
  • Answer:
    TelescopeServiceProvider 中的 Telescope::filter(), 可以定義哪些要 record, 哪些不要
    在 local env 下會 record 所有紀錄, 其他 env 會 record failed job, reportable exception, scheduled task, 以及 monitored tag, 可自定義

# Batches

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    use Illuminate\Support\Collection;

    public function register()
    {
        $this->hideSensitiveRequestDetails();

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

            return $entries->contains(function ($entry) {
                return $entry->isReportableException() ||
                    $entry->isFailedJob() ||
                    $entry->isScheduledTask() ||
                    $entry->hasMonitoredTag();
                });
        });
    }
  • Answer:
    filter 只可 filter 單筆資料, 假如今天有一個 request 出了一個 exception, 而我想將該次 request 的所有資料都記錄下來, 那就可以使用 filterBatch
以下的 Laravel example code 的意思是？
  • Example:
    <?php
    public function register()
    {
        $this->hideSensitiveRequestDetails();

        Telescope::tag(function (IncomingEntry $entry) {
            return $entry->type === 'request'
                        ? ['status:'.$entry->content['response_status']]
                        : [];
        });
     }
  • Answer:
    當使用 Telescope 時, 一般會自動為 entry 加上預設的 tag, 但若要自己加入 tag, 可在 TelescopeServiceProvider 的 register() 中, 使用 tag method, tag method 接受一個 closure, closure 回傳的 tag 會被 telescope 一起 attach 到該 entry

# Available Watchers

以下的 Laravel example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\CacheWatcher::class => true,
        Watchers\CommandWatcher::class => true,
        ...
    ],
  • Answer:
    在 config/telescope 中, 可在 watchers array 指定哪些 watcher 要打開, 每個 watcher 都針對 Laravel 的一個模組, 像是 Cache, Command, Queue 等等
以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\QueryWatcher::class => [
            'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
            'slow' => 100,
        ],
        ...
    ],
  • Answer:
    Telescope 中, 有些 watcher 提供額外選項

# Batch Watcher

Laravel Telescope 的 Batch Watcher 紀錄了什麼？

batch watcher 紀錄了 Laravel Queue Batch 的資料


# Cache Watcher

Laravel Telescope 的 Cache Watcher 紀錄了什麼？

當 cache key 被 hit, missed, updated, 或 forgotten, 會被記錄下來


# Command Watcher

Laravel Telescope 的 Command Watcher 紀錄了什麼？

command 的 arguments, options, exit code, output

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\CommandWatcher::class => [
            'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
            'ignore' => ['key:generate'],
        ],
        ...
    ],
  • Answer:
    可在 config 中, 指定哪一些 command 不要被 record

# Dump Watcher

Laravel Telescope 的 Dump Watcher 紀錄了什麼？

紀錄 dump 資訊


# Event Watcher

Laravel Telescope 的 Event Watcher 紀錄了什麼？

會紀錄 event 的 listener, payload, 以及 broadcast data, 但 Laravel 內部的 event 會被 ignore


# Exception Watcher

Laravel Telescope 的 Exception Watcher 紀錄了什麼？

紀錄了 exception 的 data 以及 stack trace


# Gate Watcher

Laravel Telescope 的 Gate Watcher 紀錄了什麼？

紀錄了 gate 以及 policy 的檢查結果以及其 data

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\GateWatcher::class => [
            'enabled' => env('TELESCOPE_GATE_WATCHER', true),
            'ignore_abilities' => ['viewNova'],
        ],
        ...
    ],
  • Answer:
    可在 GateWatcher 中定義, 哪些 gate 是要 ignore 的

# Job Watcher

Laravel Telescope 的 Job Watcher 紀錄了什麼？

任何被 dispatched jon 的 data and status


# Log Watcher

Laravel Telescope 的 Log Watcher 紀錄了什麼？

任何 Application 所寫下的 log


# Mail Watcher

Laravel Telescope 的 Mail Watcher 紀錄了什麼？

Mail watcher 允許用瀏覽器來 preview sent emails 以及 associated data, 也可下載 .eml file


# Model Watcher

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\ModelWatcher::class => [
            'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
            'events' => ['eloquent.created*', 'eloquent.updated*'],
        ],
        ...
    ],
  • Answer:
    可在 Model Watcher 指定要記錄哪一些 model event 的資料
以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\ModelWatcher::class => [
            'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
            'events' => ['eloquent.created*', 'eloquent.updated*'],
            'hydrations' => true,
        ],
        ...
    ],
  • Answer:
    Model Watcher 也可啟用 hydrations option

# Notification Watcher

Laravel Telescope 的 Notification Watcher 紀錄了什麼？

記錄所有的 notification


# Query Watcher

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\QueryWatcher::class => [
            'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
            'slow' => 50,
        ],
        ...
    ],
  • Answer:
    Query Watcher 會紀錄下每個 query 的 raw SQL, bindings, 以及 executing time, 超過 100ms 的會被 tag slow, 可在 config 自定義 slow 的標準

# Redis Watcher

Laravel Telescope 的 Redis Watcher 紀錄了什麼？

記錄所有被執行的 redis commands


# Request Watcher

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    'watchers' => [
        Watchers\RequestWatcher::class => [
            'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
            'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
        ],
        ...
    ],
  • Answer:
    Request Watcher 預設會紀錄每一個 request, 以及其 headers, session, 以及 response, 可透過 size_limit (kilobytes) 參數來限制大小

# Schedule Watcher

Laravel Telescope 的 Schedule Watcher 紀錄了什麼？

scheduled tasks 以及其 output


# View Watcher

Laravel Telescope 的 View Watcher 紀錄了什麼？

view name, path, data, 以及 render 時用到的 composers


# Displaying User Avatars

以下的 Laravel Telescope example code 的意思是？
  • Example:
    <?php
    public function register()
    {
        // ...

        Telescope::avatar(function ($id, $email) {
            return '/avatars/'.User::find($id)->avatar_path;
        });
    }
  • Answer:
    Telescope 預設使用 Gravatar 來顯示 user avatar, 也可在 TelescopeServiceProvider 的 register() 中, 使用 Telescope::avatar 來 return 一個 user avatar image url

# 修改成 JWT 驗證

# 新增 Admin model, migration

php artisan make:model Admin -m

# 修改 Admin model

需 extend authenticatable, implement JWTSubject
JWT 部分可參考 文件

# 新增 Admins guard, Admins provider

JWT 部分可參考 文件

# 新增 middleware

public function handle(Request $request, Closure $next)
{
    $response = $next($request);

    if ($request->route()->getName() != 'telescope') {
        return $response;
    }

    if ($request->cookie('token')) {
        return $response;
    }

    if (empty($token = $request->input('token'))) {
        return $response;
    }

    $payload = JWTAuth::setToken($token)->getPayload();
    $exp = $payload->get('exp');
    $minutes = floor(($exp - time()) / 60);

    $response = $next($request);
    $response->withCookie(cookie('token', $token, $minutes));

    return $response;
}

# 修改 Telescope config

加上剛剛建立的 middleware, 並且將 ‘web’ 改成 auth middleware 並指定 guard

    'middleware' => [
//        'web',
        \App\Http\Middleware\AppendTokenForTelescope::class,
        'auth:admins',
        Authorize::class,
    ],

# 修改 TelescopeServiceProvider

這邊可自訂規則

protected function gate()
{
    Gate::define('viewTelescope', function (UserInterface $user) {
        return $user->isAdmin();
    });
}

# 建立 Admin login API

# 在資料庫中新增帳號密碼

# 登入以取得 token

# 測試

輸入 https://projectName/telescope?token=yourToken
在 production 環境也可存取 Telescope

#Laravel #Laravel Documentation #Laravel Telescope
Laravel - Testing - Database (官方文件原子化翻譯筆記) Laravel - Testing - Mocking (官方文件原子化翻譯)

留言

Your browser is out-of-date!

Update your browser to view this website correctly. Update my browser now

×