laravel-metrics-plausible

Laravel Metrics Plausible is a PHP library that wraps the Plausible Analytics Stats API v2, providing a fluent, Laravel‑native interface for retrieving and managing analytics data. Key Features - Retrieve aggregate totals (visitors, pageviews, bounce rate, etc.) - Query time‑series data with custom date ranges and dimensions (hourly, daily, monthly) - Get breakdowns by pages, entry/exit pages, sources, channels, UTM parameters, countries, regions, cities, devices, browsers, operating systems - Access goal conversions, custom events and realtime visitor count - Manage Plausible sites and goals (list, create, delete) - Build custom queries using a query builder that mirrors the API payload - Handles authentication, rate‑limit and generic API errors with specific exceptions - Works with both Plausible Cloud and self‑hosted Community Edition - Configuration stored in the database via spatie/laravel-settings, eliminating the need for config files Installation 1. Add the package: composer require jeffersongoncalves/laravel-metrics-plausible 2. Run migrations to create the settings table: php artisan migrate Configuration After migration, environment variables seed the settings: PLAUSIBLE_API_KEY – API key from Plausible Settings → API Keys PLAUSIBLE_SITE_ID – domain of the site (e.g., example.com) PLAUSIBLE_BASE_URL – base URL of Plausible (default https://plausible.io, change for self‑hosted) Settings can also be updated programmatically via the PlausibleSettings class. Usage Overview All interactions are performed through the Plausible facade. Aggregate totals: $stats = Plausible::aggregate(); $stats->visitors(); // 1234 $stats->pageviews(); // 4321 Time‑series: $rows = Plausible::timeseries(DateRange::Last30Days, Dimension::TimeDay); foreach ($rows as $row) { echo $row->label . ': ' . $row->visitors(); } Breakdowns (pages, sources, countries, devices, etc.) are available via dedicated methods such as Plausible::pages(), Plausible::countries(), Plausible::devices(). Realtime visitors: $visitors = Plausible::realtimeVisitors(); Custom queries: $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); Site management: Plausible::sites(); Plausible::createSite('example.com', 'America/Sao_Paulo'); Plausible::deleteSite('example.com'); Goal management: 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. Error Handling - AuthenticationException: missing/invalid API key or site ID, or 403 response. - RateLimitException: HTTP 429 response. - PlausibleException: generic API failures (base class for the above). Testing and Development Run the test suite with composer test, format code with composer format, and perform static analysis with composer analyse. License Distributed under the MIT License.