laravel-metrics-plausible

Laravel Metrics Plausible é uma biblioteca PHP que encapsula a API v2 de Estatísticas do Plausible Analytics, fornecendo uma interface fluente e nativa do Laravel para recuperar e gerenciar dados analíticos. Principais Recursos - Recuperar totais agregados (visitantes, visualizações de página, taxa de rejeição, etc.) - Consultar dados de séries temporais com intervalos de datas e dimensões personalizadas (horário, diário, mensal) - Obter detalhamentos por páginas, páginas de entrada/saída, fontes, canais, parâmetros UTM, países, regiões, cidades, dispositivos, navegadores, sistemas operacionais - Acessar conversões de metas, eventos personalizados e contagem de visitantes em tempo real - Gerenciar sites e metas do Plausible (listar, criar, excluir) - Construir consultas personalizadas usando um construtor de consultas que espelha o payload da API - Lida com autenticação, limite de taxa e erros genéricos da API com exceções específicas - Funciona tanto com Plausible Cloud quanto com a Community Edition auto-hospedada - Configuração armazenada no banco de dados via spatie/laravel-settings, eliminando a necessidade de arquivos de configuração Instalação 1. Adicione o pacote: composer require jeffersongoncalves/laravel-metrics-plausible 2. Execute as migrações para criar a tabela de configurações: php artisan migrate Configuração Após a migração, as variáveis de ambiente preenchem as configurações: PLAUSIBLE_API_KEY – Chave da API de Plausible Settings → API Keys PLAUSIBLE_SITE_ID – domínio do site (ex: example.com) PLAUSIBLE_BASE_URL – URL base do Plausible (padrão https://plausible.io, altere para auto-hospedado) As configurações também podem ser atualizadas programaticamente via a classe PlausibleSettings. Visão Geral de Uso Todas as interações são realizadas através da facade Plausible. Totais agregados: $stats = Plausible::aggregate(); $stats->visitors(); // 1234 $stats->pageviews(); // 4321 Séries temporais: $rows = Plausible::timeseries(DateRange::Last30Days, Dimension::TimeDay); foreach ($rows as $row) { echo $row->label . ': ' . $row->visitors(); } Detalhamentos (páginas, fontes, países, dispositivos, etc.) estão disponíveis via métodos dedicados como Plausible::pages(), Plausible::countries(), Plausible::devices(). Visitantes em tempo real: $visitors = Plausible::realtimeVisitors(); Consultas personalizadas: $query = Plausible::query() ->metrics(Metric::Visitors, Metric::Pageviews) ->dateRange(DateRange::Last7Days) ->dimensions(Dimension::Page) ->filter('is', Dimension::Country, ['BR', 'PT']) ->orderBy(Metric::Visitors, 'desc') ->limit(50); $rows = Plausible::rows($query); Gerenciamento de sites: Plausible::sites(); Plausible::createSite('example.com', 'America/Sao_Paulo'); Plausible::deleteSite('example.com'); Gerenciamento de metas: Plausible::goals(); Plausible::createEventGoal('Signup'); Plausible::deleteGoal(1); Enums Metric – Visitors, Visits, Pageviews, BounceRate, VisitDuration, Events, etc. DateRange – Day, Last7Days, Last30Days, Last12Months, Year, All, etc. Dimension – Page, Hostname, Source, Referrer, Device, Browser, Country, City, TimeHour, TimeDay, etc. Tratamento de Erros - AuthenticationException: chave da API ou ID do site ausente/inválido, ou resposta 403. - RateLimitException: resposta HTTP 429. - PlausibleException: falhas genéricas da API (classe base para as anteriores). Testes e Desenvolvimento Execute a suíte de testes com composer test, formate o código com composer format e realize a análise estática com composer analyse. Licença Distribuído sob a Licença MIT.