Версія фреймворка: 8.x

Телескоп Laravel

Вступ

Телескоп Laravel - це елегантний помічник з налагодження для фреймворку Laravel. Телескоп забезпечує розуміння запитів, що надходять у вашу програму, винятків, записів журналу, запитів до бази даних, завдань у черзі, пошти, сповіщень, операцій кешування, запланованих завдань, дампів змінних тощо. Телескоп є чудовим супутником вашого місцевого середовища для розвитку Laravel.

Встановлення

Ви можете використовувати Composer для встановлення телескопа у ваш проект Laravel:

composer require laravel/telescope

Після встановлення Telescope опублікуйте його активи за допомогоюtelescope:installArtisan командування. Після встановлення телескопа вам слід також запуститиmigrateкоманда:

php artisan telescope:install

php artisan migrate

Встановлення лише в певних середовищах

Якщо ви плануєте використовувати Телескоп лише для сприяння вашому місцевому розвитку, Ви можете встановити Телескоп за допомогою--devпрапор:

composer require laravel/telescope --dev

Після бігуtelescope:install, слід видалитиTelescopeServiceProviderреєстрація постачальника послуг від вашогоappфайл конфігурації. Натомість зареєструйте постачальника послуг вручну вregisterметод вашогоAppServiceProvider:

/**
 * Register any application services.
 *
 * @return void
 */
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"
        ]
    }
},

Налаштування міграції

Якщо ви не збираєтесь використовувати міграції за замовчуванням у Телескопі, вам слід зателефонувати доTelescope::ignoreMigrationsметод уregisterметод вашогоAppServiceProvider. Ви можете експортувати міграції за замовчуванням за допомогоюphp artisan vendor:publish --tag=telescope-migrationsкоманди.

Конфігурація

Після публікації активів Телескопа його основний файл конфігурації буде розміщений за адресоюconfig/telescope.php. Цей конфігураційний файл дозволяє вам налаштувати параметри вашого спостерігача, і кожен параметр конфігурації включає опис його призначення, тому обов’язково ретельно вивчіть цей файл.

За бажанням ви можете вимкнути збір даних телескопа повністю, використовуючиenabledваріант конфігурації:

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

Обрізання даних

Без обрізкиtelescope_entriesтаблиця може накопичувати записи дуже швидко. Щоб пом'якшити це, слід заплануватиtelescope:pruneКоманда ремісників бігати щодня:

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

За замовчуванням усі записи старші за 24 години будуть обрізані. Ви можете використовуватиhoursопція при виклику команди, щоб визначити, як довго зберігати дані телескопа. Наприклад, наступна команда видалить усі записи, створені понад 48 годин тому:

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

Авторизація інформаційної панелі

Телескоп виставляє приладову панель на/telescope. За замовчуванням ви зможете отримати доступ до цієї інформаційної панелі лише вlocalнавколишнє середовище. В межах вашогоapp/Providers/TelescopeServiceProvider.phpфайл, є файлgateметод. Ця авторизація контролює доступ до телескопа внемісцевийсередовищах. Ви можете змінювати ці ворота за необхідності, щоб обмежити доступ до вашої установки телескопа:

/**
 * 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',
        ]);
    });
}
Переконайтеся, що ви змінилиAPP_ENVсередовище змінна доproductionу вашому виробничому середовищі. В іншому випадку установка вашого телескопа буде загальнодоступною.

Модернізація телескопа

Під час оновлення до нової основної версії телескопа важливо уважно переглянути йогопосібник з оновлення.

Крім того, під час оновлення до будь-якої нової версії телескопа, вам слід повторно опублікувати активи телескопа:

php artisan telescope:publish

Щоб оновити об’єкти та уникнути проблем із майбутніми оновленнями, ви можете додати файлtelescope:publishкоманда доpost-update-cmdсценарії у вашому додаткуcomposer.jsonфайл:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan telescope:publish --ansi"
        ]
    }
}

Фільтрування

Записи

Ви можете відфільтрувати дані, записані телескопом, черезfilterзворотний дзвінок, зареєстрований у вашомуTelescopeServiceProvider. За замовчуванням цей зворотний виклик записує всі дані вlocalсередовище та винятки, невдалі завдання, заплановані завдання та дані з відстежуваними тегами у всіх інших середовищах:

/**
 * Register any application services.
 *
 * @return void
 */
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();
    });
}

Партії

Покиfilterзворотній дзвінок фільтрує дані для окремих записів, ви можете використовуватиfilterBatchметод реєстрації зворотного виклику, який фільтрує всі дані для даного запиту або консольної команди. Якщо зворотний дзвінок повернетьсяtrue, всі записи записані телескопом:

use Illuminate\Support\Collection;

/**
 * Register any application services.
 *
 * @return void
 */
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();
            });
    });
}

Позначення

Телескоп дозволяє шукати записи за "тегом". Часто теги - це красномовні імена класів моделі або автентифіковані ідентифікатори користувачів, які Телескоп автоматично додає до записів. Іноді вам може знадобитися приєднати власні власні теги до записів. Для цього ви можете використовуватиTelescope::tagметод.tagметод приймає зворотний виклик, який повинен повертати масив тегів. Теги, повернуті зворотним викликом, будуть об’єднані з будь-якими тегами, які телескоп автоматично приєднає до запису. Вам слід зателефонувати доtagметод у вашомуTelescopeServiceProvider:

use Laravel\Telescope\Telescope;

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

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

        return [];
    });
 }

Доступні спостерігачі

Спостерігачі телескопів збирають дані програми, коли виконується запит або команда консолі. Ви можете налаштувати список спостерігачів, які ви хотіли б увімкнути в своєму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. Якщо ви хочете виключити певні команди із запису спостерігачем, ви можете вказати команду вignoreваріант у вашомуconfig/telescope.phpфайл:

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

Смітник спостерігач

Спостерігач дампів записує та відображає ваші дамп змінних у телескопі. При використанні Laravel змінні можуть бути скинуті за допомогою глобальноїdumpфункція. Вкладка спостерігача дампа повинна бути відкрита у браузері, щоб відбулося записування, інакше спостерігачі ігнорують дампи.

Спостерігач за подіями

Спостерігач подій реєструє корисне навантаження, слухачі та дані трансляції для будь-яких подій, надісланих вашим додатком. Внутрішні події фреймворку Laravel ігноруються спостерігачем подій.

Надзвичайний спостерігач

Диспетчер винятків реєструє дані та трасування стека для будь-яких звітів, що підлягають звітуванню, які створює ваша програма.

Ворота спостерігач

Переглядач шлюзу реєструє дані та результати перевірок воріт та політики вашим додатком. Якщо ви хочете виключити певні здібності з реєстрації спостерігачем, ви можете вказати їх уignore_abilitiesваріант у вашомуconfig/telescope.phpфайл:

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

Job Watcher

Диспетчер вакансій реєструє дані та стан будь-яких вакансій, надісланих вашим додатком.

Запис журналу

Переглядач журналів записує дані журналу для будь-яких журналів, написаних вашою програмою.

Поштовий спостерігач

Програма для перегляду пошти дозволяє переглядати в браузері попередній перегляд електронних листів разом із відповідними даними. Ви також можете завантажити електронне повідомлення як.emlфайл.

Модель спостерігача

Модель спостерігача записує зміни моделі, коли Eloquentcreated,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 Watcher.

Запит спостерігача

Переглядач запитів реєструє запит, заголовки, сеанс та дані відповідей, пов’язані з будь-якими запитами, обробленими додатком. Ви можете обмежити свої дані відповідей черезsize_limit(у КБ) варіант:

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

Графік спостерігача

Диспетчер розкладів записує команди та результати будь-яких запланованих завдань, що виконуються вашим додатком.

Переглянути спостерігач

Переглядач переглядів реєструє ім’я подання, шлях, дані та "композитори", що використовуються під час рендерингу переглядів.

Відображення аватарів користувачів

На інформаційній панелі телескопа відображається аватар користувача для користувача, який увійшов у систему при збереженні заданого запису. За замовчуванням Telescope отримує аватари за допомогою веб-служби Gravatar. Однак ви можете налаштувати URL-адресу аватару, зареєструвавши зворотний дзвінок у своємуTelescopeServiceProvider. Зворотний дзвінок отримає ідентифікатор користувача та адресу електронної пошти та повинен повернути URL-адресу зображення аватара користувача:

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

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}