Laravel Pulse
- Введение
- Установка
- Конфигурация
- Информационная панель
- Авторизация
- Настройка
- Разрешение пользователей
- Cards
- Захват записей
- Регистраторы (Recorders)
- Фильтрация
- Производительность
- Использование отдельной базы данных
- Использование Redis
- Выборка (Salming)
- Обрезка
- Обработка Исключений Pulse
- Пользовательские Карточки
- Компоненты Карточек
- Стилизация
- Захват данных и их агрегация
Введение
Laravel Pulse предоставляет быстрый обзор производительности и использования вашего приложения. С помощью Pulse вы можете выявить узкие места, такие как медленные задания и конечные точки, найти ваших самых активных пользователей и многое другое.
Для подробной отладки отдельных событий рекомендуется ознакомиться с Laravel Telescope.
Установка
В настоящее время для хранения данных Pulse используется собственная реализация, требующая базу данных MySQL, MariaDB или PostgreSQL. Если вы используете другой движок базы данных, вам потребуется отдельная база данных MySQL, MariaDB или PostgreSQL для хранения данных Pulse.
Вы можете установить Pulse с помощью менеджера пакетов Composer:
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 могут быть установлены через переменные среды. Чтобы увидеть доступные опции, зарегистрировать новые регистраторы(recorders) или настроить дополнительные параметры, вы можете опубликовать файл конфигурации config/pulse.php
:
php artisan vendor:publish --tag=pulse-config
Информационная панель
Авторизация
Доступ к информационной панели Pulse можно получить по маршруту /pulse
. По умолчанию вы сможете получить доступ к информационной панели только в среде local
, поэтому вам нужно будет настроить авторизацию для ваших производственных сред, настраивая шлюз авторизации (gate) 'viewPulse'
. Вы можете сделать это в файле app/Providers/AppServiceProvider.php
вашего приложения:
use App\Models\User;
use Illuminate\Support\Facades\Gate;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Gate::define('viewPulse', function (User $user) {
return $user->isAdmin();
});
// ...
}
Настройка
Карточки и макет информационной панели Pulse можно настроить, опубликовав представление(view) информационной панели. Представление информационной панели будет опубликовано в resources/views/vendor/pulse/dashboard.blade.php
:
php artisan vendor:publish --tag=pulse-dashboard
Информационная панель работает на Livewire и позволяет настраивать карточки и макет без необходимости перестройки каких-либо JavaScript-ресурсов.
Внутри этого файла компонент <x-pulse>
отвечает за отображение информационной панели и обеспечивает сетку(grid) для карточек. Если вы хотите, чтобы информационная панель распространялась на всю ширину экрана, вы можете предоставить компоненту атрибут 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 записывает только идентификатор пользователя. При рендеринге информационной панели Pulse из вашей модели Authenticatable
будет извлечены поля name
и email
, а также будет отображаться аватар с использованием веб-сервиса Gravatar.
Вы можете настроить поля и аватар, вызвав метод Pulse::user
в классе App\Providers\AppServiceProvider
вашего приложения.
Метод user
принимает замыкание, которое будет получать модель Authenticatable
, которая будет отображаться, и должен возвращать массив с информацией о name
, extra
и avatar
для пользователя:
use Laravel\Pulse\Facades\Pulse;
/**
* Bootstrap any application services.
*/
public function boot(): void
{
Pulse::user(fn ($user) => [
'name' => $user->name,
'extra' => $user->email,
'avatar' => $user->avatar_url,
]);
// ...
}
Вы можете полностью настроить захват и извлечение аутентифицированного пользователя, реализовав контракт
Laravel\Pulse\Contracts\ResolvesUsers
и привязав его к контейнеру служб Laravel.
Cards
Серверы
Карточка <livewire:pulse.servers />
отображает использование системных ресурсов для всех серверов, выполняющих команду pulse:check
. Пожалуйста, обратитесь к документации о регистраторе серверов для получения дополнительной информации об отчетах использования системных ресурсов.
Если вы заменяете сервер в своей инфраструктуре, возможно, вы захотите прекратить отображение неактивного сервера на панели управления Pulse по истечении определенного периода времени. Вы можете сделать это, используя опцию ignore-after
, которая принимает количество секунд, по истечении которых неактивные серверы должны быть удалены с панели управления Pulse. Альтернативно вы можете указать строку в формате относительного времени, например 1 hour
или 3 days and 1 hour
:
<livewire:pulse.servers ignore-after="3 hours" />
Использование приложения
Карточка <livewire:pulse.usage />
отображает топ-10 пользователей, отправляющих запросы к вашему приложению, обрабатывающих задачи и испытывающих медленные запросы.
Если вы хотите просмотреть все метрики использования на экране одновременно, вы можете включить карточку несколько раз и указать атрибут type
:
<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />
Чтобы узнать, как настроить способ получение и отображения информации о пользователях в Pulse, обратитесь к нашей документации по разрешению пользователей.
Если ваше приложение получает много запросов или отправляет много задач, вы можете захотеть включить выборку. См. документацию по регистратору запросов пользователей, регистратору задач пользователей и регистратору медленных задач для получения дополнительной информации.
Исключения
Карточка <livewire:pulse.exceptions />
отображает частоту и давность исключений, возникающих в вашем приложении. По умолчанию исключения группируются на основе класса исключения и места его возникновения. Дополнительную информацию можно найти в документации по регистратору исключений.
Очереди
Карточка <livewire:pulse.queues />
отображает пропускную способность очередей в вашем приложении, включая количество добавленных в очередь, обрабатываемых, обработанных, выпущенных и неудачных задач. Дополнительную информацию можно найти в документации по регистратору очередей.
Медленные HTTP запросы
Карточка <livewire:pulse.slow-requests />
отображает входящие запросы к вашему приложению, время выполнения которых превышает настроенный порог, по умолчанию составляющий 1 000 мс. Дополнительную информацию можно найти в документации по регистратору медленных Http запросов.
Медленные задачи
Карточка <livewire:pulse.slow-jobs />
отображает задачи, находящиеся в очереди вашего приложения, время выполнения которых превышает настроенный порог, по умолчанию составляющий 1 000 мс. Дополнительную информацию можно найти в документации по регистратору медленных задач.
Медленные запросы к базе данных
Карточка <livewire:pulse.slow-queries />
отображает запросы к базе данных вашего приложения, время выполнения которых превышает настроенный порог, по умолчанию составляющий 1 000 мс.
По умолчанию медленные запросы группируются на основе SQL-запроса (без подстановок) и места, где он был выполнен, но вы можете выбрать не захватывать местоположение, если хотите группировать исключительно по SQL-запросу.
Если вы столкнулись с проблемами производительности рендеринга из-за очень больших SQL-запросов, получающих подсветку синтаксиса, вы можете отключить подсветку, добавив параметр without-highlighting
:
<livewire:pulse.slow-queries without-highlighting />
См. документацию по регистратору медленных запросов к базе данных для получения дополнительной информации.
Медленные исходящие HTTP запросы
Карточка <livewire:pulse.slow-outgoing-requests />
отображает исходящие запросы, сделанные с использованием HTTP-клиента Laravel, время выполнения которых превышает настроенный порог, по умолчанию составляющий 1 000 мс.
По умолчанию записи будут группироваться по полному URL. Однако вы можете захотеть нормализовать или группировать подобные исходящие запросы с использованием регулярных выражений. См. документацию по регистратору медленных исходящих HTTP запросов для получения дополнительной информации.
Кэш
Карточка <livewire:pulse.cache />
отображает статистику зффективности использования кэша для вашего приложения, как глобально, так и для отдельных ключей.
По умолчанию записи будут группироваться по ключу. Однако вы можете захотеть нормализовать или группировать подобные ключи с использованием регулярных выражений. См. документацию по записи взаимодействия с кэшем для получения дополнительной информации.
Захват записей
Большинство регистраторов Pulse автоматически захватывают записи на основе событий фреймворка, отправляемых Laravel. Однако регистратор серверов и некоторые сторонние карточки должны регулярно запрашивать информацию. Чтобы использовать эти карточки, вы должны запустить демона pulse:check
на всех ваших отдельных серверах приложения:
php artisan pulse:check
Чтобы процесс
pulse:check
постоянно работал в фоновом режиме, вы должны использовать монитор процессов, такой как Supervisor, чтобы гарантировать, что команда не прекратит выполнение.
Поскольку команда pulse:check
работает в течение длительного времени, она не будет замечать изменения в вашем коде без перезапуска.
Во время развёртывания вашего приложения необходимо перезапустить команду с помощью вызова pulse:restart
:
php artisan pulse:restart
Pulse использует кэш для сохранения сигналов о перезапуске, поэтому перед использованием этой функции убедитесь, что драйвер кэша настроен правильно для вашего приложения.
Регистраторы (Recorders)
Регистраторы отвечают за захват записей из вашего приложения для записи в базу данных Pulse. Регистраторы регистрируются и настраиваются в разделе recorders
файла конфигурации Pulse.
Взаимодействие с кешем
Регистратор CacheInteractions
захватывает информацию о попаданиях и промахах кеша, происходящих в вашем приложении, для отображения в карточке Cache.
Вы можете опционально настроить уровень выборки и шаблоны игнорируемых ключей.
Вы также можете настроить группировку ключей так, чтобы похожие ключи группировались как одна запись. Например, вы можете удалить уникальные идентификаторы из ключей, кеширующих один и тот же тип информации. Группы настраиваются с использованием регулярного выражения для “поиска и замены” частей ключа. Пример включен в файле конфигурации:
Recorders\CacheInteractions::class => [
// ...
'groups' => [
// '/:\d+/' => ':*',
],
],
Будет использоваться первый подходящий шаблон. Если ни один шаблон не подошёл, то ключ будет захвачен как есть.
Исключения
Регистратор Exceptions
отслеживает информацию о возникающих в вашем приложении исключениях, подлежащих отчетности, для отображения в карточке исключений.
Вы можете опционально настраивать уровень выборки и шаблоны игнорируемых исключений. Также вы можете настроить захват местоположения, откуда произошло исключение. Захваченное местоположение будет отображаться на панели управления Pulse, что может помочь отследить источник исключения; однако, если одно и то же исключение возникает в нескольких местах, оно будет отображаться несколько раз для каждого уникального местоположения.
Очереди
Регистратор Queues
отслеживает информацию о очередях вашего приложения для отображения на карточке очередей.
Вы можете опционально настраивать уровень выборки и шаблоны игнорируемых задач.
Медленные задачи
Регистратор SlowJobs
отслеживает информацию о медленных задачах, происходящих в вашем приложении, для отображения на карточке Медленные задачи.
Вы можете опционально настраивать порог медленных задач, уровень выборки и шаблоны игнорируемых задач.
У вас могут быть некоторые работы, которые, по вашему мнению, займут больше времени, чем другие. В этих случаях вы можете настроить пороговые значения для каждого задания:
Recorders\SlowJobs::class => [
// ...
'threshold' => [
'#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
],
],
Если ни один шаблон регулярного выражения не соответствует имени класса задания, то будет использовано значение 'default'
.
Медленные Исходящие HTTP Запросы
Регистратор SlowOutgoingRequests
отслеживает информацию об исходящих HTTP-запросах, сделанных с использованием HTTP-клиента Laravel, которые превышают настроенный порог, для отображения в карточке медленные исходящие HTTP запросы.
Вы можете опционально настраивать порог медленных исходящих запросов, уровень выборки и шаблоны игнорируемых 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'
.
Медленные HTTP pапросы
Регистратор Requests
захватывает информацию о http запросах к вашему приложению для отображения в карточках медленные http запросы и использование приложения.
Вы можете настраивать порог медленных маршрутов, уровень выборки и игнорируемые пути.
У вас могут быть некоторые запросы, которые, по вашему мнению, займут больше времени, чем другие. В этих случаях вы можете настроить пороговые значения для каждого запроса:
Recorders\SlowRequests::class => [
// ...
'threshold' => [
'#^/admin/#' => 5000,
'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
],
],
Если ни один шаблон регулярного выражения не соответствует URL-адресу запроса, то будет использовано значение 'default'
.
Серверы
Регистратор Servers
захватывает информацию о загрузке процессора, памяти и хранилища серверов, обеспечивающих работу вашего приложения, для отображения в карточке Серверы. Для работы этого регистратора необходимо, чтобы на каждом сервере, который вы хотите отслеживать, была запущена команда pulse:check
.
Каждый отслеживаемый сервер должен иметь уникальное имя. По умолчанию Pulse будет использовать значение, возвращаемое функцией gethostname
PHP. Если вы хотите настроить это, вы можете установить переменную окружения PULSE_SERVER_NAME
:
PULSE_SERVER_NAME=load-balancer
Файл конфигурации Pulse также позволяет настраивать каталоги, которые будут отслеживаться.
Пользователи с задачами
Регистратор UserJobs
захватывает информацию о пользователях, отправляющих задачи в вашем приложении, для отображения в карточке использование приложения.
Вы можете опционально настраивать уровень выборки и шаблоны игнорируемых задач.
Пользователи с запросами
Регистратор UserRequests
захватывает информацию о пользователях, делающих запросы к вашему приложению, для отображения в карточке использование приложения.
Вы можете опционально настраивать уровень выборки и шаблоны игнорируемых запросов.
Фильтрация
Как мы видели, многие регистраторы предлагают возможность, через конфигурацию, “игнорировать” входящие записи на основе их значения, например, URL запроса. Однако иногда может быть полезно фильтровать записи на основе других факторов, таких как текущий аутентифицированный пользователь. Для фильтрации этих записей вы можете передать замыкание в метод filter
Pulse. Обычно метод filter
следует вызывать внутри метода boot
AppServiceProvider
вашего приложения:
use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;
/**
* Bootstrap any application services.
*/
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
Для работы с Redis Ingest требуется Redis версии 6.2 или выше, а также
phpredis
илиpredis
в качестве используемого драйвера клиента Redis.
По умолчанию Pulse сохраняет записи непосредственно в настроенное соединение с базой данных после отправки HTTP-ответа клиенту или обработки задачи; однако вы можете использовать драйвер вывода в Redis от Pulse для отправки записей в поток Redis. Это можно включить, настроив переменную окружения PULSE_INGEST_DRIVER
:
PULSE_INGEST_DRIVER=redis
По умолчанию Pulse будет использовать ваше стандартное соединение с Redis, но вы можете настроить это с помощью переменной окружения PULSE_REDIS_CONNECTION
:
PULSE_REDIS_CONNECTION=pulse
При использовании вывода в Redis вам потребуется запустить команду pulse:work
для отслеживания потока и перемещения записей из Redis в таблицы базы данных Pulse.
php artisan pulse:work
Чтобы обеспечить постоянную работу процесса
pulse:work
в фоновом режиме, рекомендуется использовать монитор процессов, такой как Supervisor, чтобы гарантировать, что рабочий процесс Pulse не прекращает свою работу.
Выборка (Salming)
По умолчанию Pulse будет захватывать каждое значимое событие, происходящее в вашем приложении. Для приложений с высокой нагрузкой это может привести к необходимости агрегировать миллионы строк из базы данных в информационную панель, особенно для более длительных временных периодов.
Вместо этого вы можете включить “выборку” для определенных регистраторов данных Pulse. Например, установка уровня выборки 0.1
для регистратора User Requests
означает, что вы записываете только примерно 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
Если ваша пользовательская карточка находится в кодовой базе вашего приложения, и вы используете интеграцию Laravel с Vite, вы можете обновить файл 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
, который соответствует селектору, переданному в стратегию выбора important
в Tailwind:
<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
, является типом
записи, второй аргумент – это ключ
, который определяет, как должны быть сгруппированы агрегированные данные. Для большинства методов агрегации вам также потребуется указать значение
, которое должно быть агрегировано. В приведенном выше примере агрегируемое значение – $sale->amount
. Затем вы можете вызвать один или несколько методов агрегации (например, sum
), чтобы Pulse мог захватывать предварительно агрегированные значения в “корзины” для эффективного извлечения позже.
Доступные методы агрегации:
avg
count
max
min
sum
При создании пакета карточек, который захватывает идентификатор текущего аутентифицированного пользователя, следует использовать метод
Pulse::resolveAuthenticatedUserId()
, который учитывает любые настройки пользовательского разрешения, примененные в приложении.
Retrieving Aggregate Data
When extending Pulse’s Card
Livewire component, you may use the aggregate
method to retrieve aggregated data for the period being viewed in the dashboard:
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
{
/**
* The events to listen for.
*
* @var array<int, class-string>
*/
public array $listen = [
Deployment::class,
];
/**
* Record the deployment.
*/
public function record(Deployment $event): void
{
$config = Config::get('pulse.recorders.'.static::class);
Pulse::record(
// ...
);
}
}