Laravel документація українською

Laravel Pulse

Вступ

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

Для детального налагодження окремих подій, перегляньте Laravel Telescope.

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

Реалізація зберігання першої сторони Pulse наразі вимагає бази даних MySQL, MariaDB або PostgreSQL. Якщо ви використовуєте інший механізм бази даних, вам знадобиться окрема база даних MySQL, MariaDB або PostgreSQL для ваших даних Pulse.

Ви можете встановити Pulse за допомогою менеджера пакетів компонувальник:

composer require laravel/pulse

Далі, ви повинні опублікувати файли конфігурації та міграції Pulse, використовуючи команду Artisan vendor:publish:

php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

Нарешті, вам слід виконати команду migrate, щоб створити таблиці, необхідні для зберігання даних Pulse:

php artisan migrate

Після того як міграції бази даних Pulse були виконані, ви можете отримати доступ до панелі керування Pulse через маршрут /pulse.

Якщо ви не хочете зберігати дані Pulse в основній базі даних вашого застосунку, ви можете вказати окреме підключення до бази даних.

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

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

php artisan vendor:publish --tag=pulse-config

Панель управління

Авторизація

Панель керування Pulse може бути доступна через маршрут /pulse. За замовчуванням, ви зможете отримати доступ до цієї панелі лише в середовищі local, тому вам потрібно налаштувати авторизацію для ваших виробничих середовищ, налаштувавши шлюз авторизації 'viewPulse'. Ви можете зробити це у файлі app/Providers/AppServiceProvider.php вашого застосунку:

use App\Models\User;
use Illuminate\Support\Facades\Gate;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });
 
    // ...
}

Налаштування

Панель керування Pulse та макет можуть бути налаштовані шляхом публікації представлення панелі керування. Представлення панелі керування буде опубліковано в resources/views/vendor/pulse/dashboard.blade.php:

php artisan vendor:publish --tag=pulse-dashboard

Панель керування працює на Livewire і дозволяє налаштовувати картки та макет без необхідності перебудови будь-яких JavaScript-ресурсів.

У цьому файлі компонент <x-pulse> відповідає за відображення панелі інструментів і забезпечує сіткове розташування для карток. Якщо ви хочете, щоб панель інструментів займала всю ширину екрану, ви можете надати компоненту властивість full-width:

<x-pulse full-width>
    ...
</x-pulse>

За замовчуванням компонент <x-pulse> створює сітку з 12 колонок, але ви можете налаштувати це, використовуючи властивість cols:

<x-pulse cols="16">
    ...
</x-pulse>

Кожна картка приймає властивості cols і rows для керування простором і позиціонуванням:

<livewire:pulse.usage cols="4" rows="2" />

Більшість карток також приймають властивість expand для відображення повної картки замість прокручування:

<livewire:pulse.slow-queries expand />

Вирішення Користувачів

Для карток, що відображають інформацію про ваших користувачів, таких як картка Використання Застосунку, Pulse буде записувати лише ID користувача. Під час рендерингу панелі керування, Pulse буде отримувати поля name та email з вашої моделі за замовчуванням Authenticatable і відображати аватари за допомогою веб-сервісу Gravatar.

Ви можете налаштувати поля та аватар, викликавши метод Pulse::user у класі App\Providers\AppServiceProvider вашого застосунку.

Метод user приймає замикання, яке отримає модель Authenticatable, що буде відображена, і має повернути масив, що містить інформацію name, extra та avatar для користувача:

use Laravel\Pulse\Facades\Pulse;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);
 
    // ...
}

Ви можете повністю налаштувати, як автентифікований користувач захоплюється та отримується, реалізувавши контракт Laravel\Pulse\Contracts\ResolvesUsers і зв'язавши його в сервіс-контейнері Laravel.

Карти

Сервери

The <livewire:pulse.servers /> картка відображає використання системних ресурсів для всіх серверів, на яких виконується команда pulse:check. Будь ласка, зверніться до документації щодо реєстратора серверів для отримання додаткової інформації про звітування системних ресурсів.

Якщо ви замінюєте сервер у вашій інфраструктурі, можливо, ви захочете припинити відображення неактивного сервера на панелі Pulse після певного періоду. Ви можете досягти цього, використовуючи властивість ignore-after, яка приймає кількість секунд, після яких неактивні сервери повинні бути видалені з панелі Pulse. Альтернативно, ви можете надати строку з відносним часом, таку як 1 hour або 3 days and 1 hour:

<livewire:pulse.servers ignore-after="3 hours" />

Використання застосунку

The <livewire:pulse.usage /> картка відображає топ-10 користувачів, які роблять запити до вашого застосунку, виконують завдання та стикаються з повільними запитами.

Якщо ви бажаєте переглянути всі метрики використання на екрані одночасно, ви можете включити картку кілька разів і вказати атрибут type:

<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />

Щоб дізнатися, як налаштувати спосіб отримання та відображення інформації про користувачів у Pulse, зверніться до нашої документації про розв'язання користувачів.

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

Винятки

The <livewire:pulse.exceptions /> картка показує частоту та недавність винятків, що виникають у вашому застосунку. За замовчуванням винятки групуються на основі класу винятку та місця, де вони виникли. Дивіться документацію реєстратора винятків для отримання додаткової інформації.

Черги

Картка <livewire:pulse.queues /> показує пропускну здатність черг у вашому застосунку, включаючи кількість завдань у черзі, оброблюваних, оброблених, випущених та невдалих. Дивіться документацію записувача черг для отримання додаткової інформації.

Повільні запити

The <livewire:pulse.slow-requests /> картка показує вхідні запити до вашого застосунку, які перевищують налаштований поріг, що за замовчуванням становить 1,000 мс. Дивіться документацію реєстратора повільних запитів для отримання додаткової інформації.

Повільні Завдання

The <livewire:pulse.slow-jobs /> картка показує завдання в черзі у вашому застосунку, які перевищують налаштований поріг, що за замовчуванням становить 1,000мс. Дивіться документацію реєстратора повільних завдань для отримання додаткової інформації.

Повільні запити

The <livewire:pulse.slow-queries /> картка показує запити до бази даних у вашому застосунку, які перевищують налаштований поріг, що за замовчуванням становить 1,000 мс.

За замовчуванням повільні запити групуються на основі SQL-запиту (без прив'язок) та місця, де вони виникли, але ви можете вибрати не фіксувати місце, якщо бажаєте групувати виключно за SQL-запитом.

Якщо ви стикаєтеся з проблемами продуктивності рендерингу через надзвичайно великі SQL-запити, які отримують підсвічування синтаксису, ви можете вимкнути підсвічування, додавши властивість without-highlighting:

<livewire:pulse.slow-queries without-highlighting />

Дивіться документацію реєстратора повільних запитів для отримання додаткової інформації.

Повільні Вихідні Запити

Картка <livewire:pulse.slow-outgoing-requests /> показує вихідні запити, зроблені за допомогою HTTP-клієнта Laravel, які перевищують налаштований поріг, що за замовчуванням становить 1,000 мс.

За замовчуванням записи будуть згруповані за повною URL-адресою. Однак, ви можете бажати нормалізувати або групувати схожі вихідні запити, використовуючи регулярні вирази. Дивіться документацію реєстратора повільних вихідних запитів для отримання додаткової інформації.

Кеш

The <livewire:pulse.cache /> картка показує статистику влучень та промахів кешу для вашого застосунку, як глобально, так і для окремих ключів.

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

Захоплення Записів

Більшість реєстраторів Pulse автоматично фіксують записи на основі подій фреймворку, які відправляються Laravel. Однак, реєстратор серверів та деякі сторонні картки повинні регулярно опитувати інформацію. Щоб використовувати ці картки, ви повинні запускати демон pulse:check на всіх ваших окремих серверах застосунку:

php artisan pulse:check

Щоб процес pulse:check постійно працював у фоновому режимі, слід використовувати монітор процесів, такий як Supervisor, щоб забезпечити безперервну роботу команди.

Оскільки команда pulse:check є довготривалим процесом, вона не побачить змін у вашій кодовій базі без перезапуску. Ви повинні коректно перезапустити команду, викликавши команду pulse:restart під час процесу розгортання вашого застосунку:

php artisan pulse:restart

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

Рекордери

Рекордери відповідають за захоплення записів із вашого застосунку для збереження в базі даних Pulse. Рекордери реєструються та налаштовуються в секції recorders файлу конфігурації Pulse.

Взаємодії з кешем

Записувач CacheInteractions захоплює інформацію про влучення та промахи кешу, що відбуваються у вашому застосунку, для відображення на картці Кеш.

Ви можете за бажанням налаштувати частоту вибірки та ігноровані шаблони ключів.

Ви також можете налаштувати групування ключів, щоб схожі ключі були згруповані як один запис. Наприклад, ви можете захотіти видалити унікальні ідентифікатори з ключів, що кешують один і той самий тип інформації. Групи налаштовуються за допомогою регулярного виразу для "пошуку та заміни" частин ключа. Приклад включено у файл конфігурації:

Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d+/' => ':*',
    ],
],

Перший шаблон, що відповідає, буде використано. Якщо жоден шаблон не відповідає, тоді ключ буде захоплено як є.

Винятки

The Exceptions реєстратор захоплює інформацію про винятки, які можна звітувати, що виникають у вашому застосунку для відображення на картці Exceptions.

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

Черги

The Queues реєстратор захоплює інформацію про черги вашого застосунку для відображення на Черги.

Ви можете за бажанням налаштувати частоту вибірки та шаблони ігнорованих завдань.

Повільні завдання

Реєстратор SlowJobs захоплює інформацію про повільні завдання, що виникають у вашому застосунку, для відображення на картці Повільні завдання.

Ви можете за бажанням налаштувати поріг повільної роботи, частоту вибірки та ігноровані шаблони завдань.

Ви можете мати деякі завдання, які, як ви очікуєте, займатимуть більше часу, ніж інші. У таких випадках ви можете налаштувати пороги для кожного завдання:

Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

Якщо жоден шаблон регулярного виразу не відповідає імені класу завдання, тоді буде використано значення 'default'.

Повільні Вихідні Запити

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

Ви можете за бажанням налаштувати поріг повільного вихідного запиту, частоту вибірки та ігноровані шаблони URL.

Ви можете мати деякі вихідні запити, які, як ви очікуєте, займатимуть більше часу, ніж інші. У таких випадках ви можете налаштувати пороги для кожного запиту:

Recorders\SlowOutgoingRequests::class => [
    // ...
    'threshold' => [
        '#backup.zip$#' => 5000,
        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
    ],
],

Якщо жоден шаблон регулярного виразу не відповідає URL запиту, тоді буде використано значення 'default'.

Ви також можете налаштувати групування URL, щоб подібні URL були згруповані як один запис. Наприклад, ви можете захотіти видалити унікальні ідентифікатори з шляхів URL або згрупувати лише за доменом. Групи налаштовуються за допомогою регулярного виразу для "пошуку та заміни" частин URL. Деякі приклади включені у файл конфігурації:

Recorders\SlowOutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d+#' => '/*',
    ],
],

Перший шаблон, що співпаде, буде використано. Якщо жоден шаблон не співпаде, тоді URL буде захоплено як є.

Повільні запити

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

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

Ви можете мати деякі запити, які, як очікується, займатимуть більше часу, ніж інші. У таких випадках ви можете налаштувати пороги для кожного запиту:

Recorders\SlowQueries::class => [
    // ...
    'threshold' => [
        '#^insert into `yearly_reports`#' => 5000,
        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
    ],
],

Якщо жоден шаблон регулярного виразу не відповідає SQL-запиту, то буде використано значення 'default'.

Повільні запити

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

Ви можете за бажанням налаштувати поріг повільного маршруту, частоту вибірки та ігноровані шляхи.

Ви можете мати деякі запити, які, як ви очікуєте, займатимуть більше часу, ніж інші. У таких випадках ви можете налаштувати пороги для кожного запиту:

Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

Якщо жоден шаблон регулярного виразу не відповідає URL запиту, тоді буде використано значення 'default'.

Сервери

Реєстратор Servers фіксує використання процесора, пам'яті та сховища серверів, які забезпечують роботу вашого застосунку, для відображення на картці Servers. Цей реєстратор вимагає, щоб команда pulse:check command виконувалася на кожному з серверів, які ви бажаєте моніторити.

Кожен сервер звітності повинен мати унікальне ім'я. За замовчуванням Pulse використовуватиме значення, яке повертає функція PHP gethostname. Якщо ви бажаєте налаштувати це, ви можете встановити змінну середовища PULSE_SERVER_NAME:

PULSE_SERVER_NAME=load-balancer

Файл конфігурації Pulse також дозволяє налаштувати каталоги, які відстежуються.

Завдання Користувача

Реєстратор UserJobs захоплює інформацію про користувачів, які відправляють завдання у вашому застосунку, для відображення на картці Використання Застосунку.

Ви можете за бажанням налаштувати частоту вибірки та ігноровані шаблони завдань.

Запити користувачів

Реєстратор UserRequests захоплює інформацію про користувачів, які роблять запити до вашого застосунку, для відображення на картці Використання Застосунку.

Ви можете за бажанням налаштувати частоту вибірки та ігноровані шаблони URL.

Фільтрація

Як ми бачили, багато реєстраторів пропонують можливість, через конфігурацію, "ігнорувати" вхідні записи на основі їх значення, наприклад, URL запиту. Але іноді може бути корисно відфільтрувати записи на основі інших факторів, таких як поточний автентифікований користувач. Щоб відфільтрувати ці записи, ви можете передати замикання методу filter Pulse. Зазвичай, метод filter слід викликати в межах методу boot вашого застосунку в AppServiceProvider:

use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;
 
/**
 * Ініціалізувати будь-які сервіси застосунку.
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });
 
    // ...
}

Продуктивність

Pulse було розроблено для інтеграції в існуючий застосунок без потреби в додатковій інфраструктурі. Однак для застосунків з високим трафіком існує кілька способів зменшення впливу Pulse на продуктивність вашого застосунку.

Використання іншої бази даних

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

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

PULSE_DB_CONNECTION=pulse

Redis Ingest

Redis Ingest вимагає Redis 6.2 або новішої версії та phpredis або predis як налаштований клієнтський драйвер Redis для застосунку.

За замовчуванням, Pulse буде зберігати записи безпосередньо у налаштоване підключення до бази даних після того, як HTTP-відповідь була відправлена клієнту або завдання було оброблено; однак, ви можете використовувати драйвер інгесту Pulse для Redis, щоб відправляти записи до потоку Redis. Це можна увімкнути, налаштувавши змінну середовища PULSE_INGEST_DRIVER:

PULSE_INGEST_DRIVER=redis

Pulse за замовчуванням використовуватиме ваше підключення Redis, але ви можете налаштувати це через змінну середовища PULSE_REDIS_CONNECTION:

PULSE_REDIS_CONNECTION=pulse

Коли ви використовуєте Redis ingest, вам потрібно виконати команду pulse:work, щоб відстежувати потік і переміщувати записи з Redis у таблиці бази даних Pulse.

php artisan pulse:work

Щоб процес pulse:work постійно працював у фоновому режимі, слід використовувати монітор процесів, такий як Supervisor, щоб гарантувати, що обробник Pulse не зупиняється.

Оскільки команда pulse:work є довготривалим процесом, вона не побачить змін у вашій кодовій базі без перезапуску. Ви повинні коректно перезапустити команду, викликавши команду pulse:restart під час процесу розгортання вашого застосунку:

php artisan pulse:restart

Pulse використовує кеш для зберігання сигналів перезапуску, тому перед використанням цієї функції слід переконатися, що для вашого застосунку налаштовано драйвер кешу.

Sampling

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

Ви можете натомість вибрати увімкнення "вибірки" на певних записувачах даних Pulse. Наприклад, встановлення частоти вибірки на 0.1 на записувачі Запити користувачів означатиме, що ви записуєте лише приблизно 10% запитів до вашого застосунку. У панелі керування значення будуть масштабовані та префіксовані символом ~, щоб вказати, що вони є приблизними.

Загалом, чим більше записів у вас є для певної метрики, тим нижче ви можете безпечно встановити частоту вибірки без значної втрати точності.

Обрізання

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

Обробка Винятків Pulse

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

Якщо ви бажаєте налаштувати обробку цих винятків, ви можете надати замикання методу handleExceptionsUsing:

use Laravel\Pulse\Facades\Pulse;
use Illuminate\Support\Facades\Log;
 
Pulse::handleExceptionsUsing(function ($e) {
    Log::debug('An exception happened in Pulse', [
        'message' => $e->getMessage(),
        'stack' => $e->getTraceAsString(),
    ]);
});

Користувацькі картки

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

Компоненти карток

Створення користувацької картки в Laravel Pulse починається з розширення базового компонента Livewire Card та визначення відповідного представлення:

namespace App\Livewire\Pulse;
 
use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;
 
#[Lazy]
class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers');
    }
}

Коли ви використовуєте функцію ліниве завантаження Livewire, компонент Card автоматично надасть заповнювач, який враховує атрибути cols і rows, передані вашому компоненту.

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

<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
    <x-pulse::card-header name="Top Sellers">
        <x-slot:icon>
            ...
        </x-slot:icon>
    </x-pulse::card-header>
 
    <x-pulse::scroll :expand="$expand">
        ...
    </x-pulse::scroll>
</x-pulse::card>

Змінні $cols, $rows, $class і $expand повинні бути передані до відповідних компонентів Blade, щоб макет картки можна було налаштувати з представлення панелі керування. Ви також можете додати атрибут wire:poll.5s="" у ваше представлення, щоб картка автоматично оновлювалася.

Після того як ви визначили свій компонент Livewire і шаблон, картка може бути включена у ваше представлення панелі приладів:

<x-pulse>
    ...
 
    <livewire:pulse.top-sellers cols="4" />
</x-pulse>

Якщо ваша картка включена в пакет, вам потрібно зареєструвати компонент з Livewire, використовуючи метод Livewire::component.

Стилізація

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

Інтеграція Laravel Vite

Якщо ваша власна картка знаходиться в кодовій базі вашого застосунку і ви використовуєте інтеграцію Vite Laravel, ви можете оновити ваш файл vite.config.js, щоб включити спеціальну точку входу CSS для вашої картки:

laravel({
    input: [
        'resources/css/pulse/top-sellers.css',
        // ...
    ],
}),

Ви можете використовувати директиву Blade @vite у вашому представленні панелі керування, вказуючи точку входу CSS для вашої картки:

<x-pulse>
    @vite('resources/css/pulse/top-sellers.css')
 
    ...
</x-pulse>

Файли CSS

Для інших випадків використання, включаючи картки Pulse, що містяться в пакеті, ви можете вказати Pulse завантажити додаткові таблиці стилів, визначивши метод css у вашому компоненті Livewire, який повертає шлях до вашого CSS файлу:

class TopSellers extends Card
{
    // ...
 
    protected function css()
    {
        return __DIR__.'/../../dist/top-sellers.css';
    }
}

Коли ця картка включена на інформаційну панель, Pulse автоматично включить вміст цього файлу в тег <style>, тому його не потрібно публікувати в директорії public.

Tailwind CSS

Коли використовуєте Tailwind CSS, вам слід створити окремий файл конфігурації Tailwind, щоб уникнути завантаження непотрібного CSS або конфліктів з класами Tailwind від Pulse:

export default {
    darkMode: 'class',
    important: '#top-sellers',
    content: [
        './resources/views/livewire/pulse/top-sellers.blade.php',
    ],
    corePlugins: {
        preflight: false,
    },
};

Ви можете вказати файл конфігурації у вашій точці входу CSS:

@config "../../tailwind.top-sellers.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;

Вам також потрібно включити атрибут id або class у вашому представленні картки, який відповідає селектору, переданому стратегії важливих селекторів Tailwind: important selector strategy:

<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
    ...
</x-pulse::card>

Захоплення та Агрегація Даних

Користувацькі картки можуть отримувати та відображати дані з будь-якого місця; однак, ви можете скористатися потужною та ефективною системою запису та агрегування даних Pulse.

Захоплення Записів

Pulse дозволяє записувати "записи" за допомогою методу Pulse::record:

use Laravel\Pulse\Facades\Pulse;
 
Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();

Перший аргумент, наданий методу record, є type для запису, який ви реєструєте, тоді як другий аргумент є key, що визначає, як агреговані дані повинні бути згруповані. Для більшості методів агрегації вам також потрібно буде вказати value для агрегації. У наведеному вище прикладі значення, яке агрегується, це $sale->amount. Потім ви можете викликати один або кілька методів агрегації (таких як sum), щоб Pulse міг захопити попередньо агреговані значення в "кошики" для ефективного отримання пізніше.

Доступні методи агрегації:

  • avg
  • count
  • max
  • min
  • sum

Коли створюєте пакет карток, що захоплює ідентифікатор поточного автентифікованого користувача, ви повинні використовувати метод Pulse::resolveAuthenticatedUserId(), який враховує будь-які кастомізації резолвера користувачів, зроблені в застосунку.

Отримання агрегованих даних

Коли ви розширюєте компонент Livewire Card Pulse, ви можете використовувати метод aggregate для отримання агрегованих даних за період, що переглядається на інформаційній панелі:

class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers', [
            'topSellers' => $this->aggregate('user_sale', ['sum', 'count'])
        ]);
    }
}

Метод aggregate повертає колекцію об'єктів PHP stdClass. Кожен об'єкт міститиме властивість key, захоплену раніше, разом із ключами для кожного з запитаних агрегатів:

@foreach ($topSellers as $seller)
    {{ $seller->key }}
    {{ $seller->sum }}
    {{ $seller->count }}
@endforeach

Pulse в основному отримуватиме дані з попередньо агрегованих кошиків; тому вказані агрегати повинні бути зафіксовані заздалегідь за допомогою методу Pulse::record. Найстаріший кошик зазвичай частково виходитиме за межі періоду, тому Pulse агрегуватиме найстаріші записи, щоб заповнити прогалину та надати точне значення для всього періоду, без необхідності агрегувати весь період при кожному запиті.

Ви також можете отримати загальне значення для заданого типу, використовуючи метод aggregateTotal. Наприклад, наступний метод отримає загальну суму всіх продажів користувачів замість групування їх за користувачем.

$total = $this->aggregateTotal('user_sale', 'sum');

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

Коли ви працюєте з агрегатами, які записують ідентифікатор користувача як ключ, ви можете вирішити ключі до записів користувачів, використовуючи метод Pulse::resolveUsers:

$aggregates = $this->aggregate('user_sale', ['sum', 'count']);
 
$users = Pulse::resolveUsers($aggregates->pluck('key'));
 
return view('livewire.pulse.top-sellers', [
    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
        'user' => $users->find($aggregate->key),
        'sum' => $aggregate->sum,
        'count' => $aggregate->count,
    ])
]);

Метод find повертає об'єкт, що містить ключі name, extra та avatar, які ви можете за бажанням передати безпосередньо до Blade-компонента <x-pulse::user-card>:

<x-pulse::user-card :user="{{ $seller->user }}" :stats="{{ $seller->sum }}" />

Спеціальні Реєстратори

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

Реєстратори реєструються в секції recorders файлу конфігурації config/pulse.php застосунку:

[
    // ...
    'recorders' => [
        Acme\Recorders\Deployments::class => [
            // ...
        ],
 
        // ...
    ],
]

Рекордери можуть слухати події, вказуючи властивість $listen. Pulse автоматично зареєструє слухачів і викличе метод record рекордерів:

<?php
 
namespace Acme\Recorders;
 
use Acme\Events\Deployment;
use Illuminate\Support\Facades\Config;
use Laravel\Pulse\Facades\Pulse;
 
class Deployments
{
    /**
     * Події для прослуховування.
     *
     * @var array<int, class-string>
     */
    public array $listen = [
        Deployment::class,
    ];
 
    /**
     * Записати розгортання.
     */
    public function record(Deployment $event): void
    {
        $config = Config::get('pulse.recorders.'.static::class);
 
        Pulse::record(
            // ...
        );
    }
}
Хостинг для Laravel – Ukraine