Laravel 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-адресов.

Фильтрация

Как мы видели, многие регистраторы предлагают возможность, через конфигурацию, “игнорировать” входящие записи на основе их значения, например, 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(
            // ...
        );
    }
}