oi-laravel-umami maintained by oi-lab
OI Laravel Umami
A typed Laravel wrapper around the Umami analytics REST API. Works
with Umami Cloud (API key) and self-hosted instances (username/password), caches
reporting responses, and returns spatie/laravel-data
DTOs — discoverable by oi-lab/oi-laravel-ts for TypeScript
generation.
Requirements
- PHP 8.2+
- Laravel 11, 12, or 13
spatie/laravel-data^4.0
Installation
composer require oi-lab/oi-laravel-umami
Publish the configuration:
php artisan vendor:publish --tag=oi-laravel-umami-config
Configuration
Umami Cloud:
UMAMI_BASE_URL=https://api.umami.is/v1
UMAMI_API_KEY=your-api-key
UMAMI_WEBSITE_ID=your-website-uuid
Self-hosted (note the trailing /api):
UMAMI_BASE_URL=https://stats.example.com/api
UMAMI_USERNAME=admin
UMAMI_PASSWORD=secret
UMAMI_WEBSITE_ID=your-website-uuid
When UMAMI_API_KEY is set the client sends the x-umami-api-key header; otherwise it
logs in with the username/password and caches the bearer token. Reporting responses are
cached (UMAMI_CACHE_TTL, default 300s).
Usage
Use the Umami facade or inject OiLab\OiLaravelUmami\Client.
Reporting
use OiLab\OiLaravelUmami\Facades\Umami;
use Illuminate\Support\Carbon;
// Defaults to the configured website and the last 7 days.
$stats = Umami::stats();
$stats->pageviews->value; // int
$stats->visitors->prev; // ?int (previous period)
Umami::activeVisitors()->visitors; // int
Umami::pageviews()->pageviews; // DataPointData[]
Umami::metrics(options: ['type' => 'url']); // Collection<MetricData>
// Custom range + bypass cache
Umami::stats(websiteId: 'site-uuid', options: [
'startAt' => Carbon::now()->subMonth(),
'endAt' => Carbon::now(),
], fresh: true);
startAt / endAt accept Carbon, DateTimeInterface, date strings, or epoch
milliseconds.
Websites & users
Umami::websites(); // Collection<WebsiteData>
Umami::createWebsite(['name' => 'Site', 'domain' => 'example.com']);
Umami::updateWebsite('site-uuid', ['name' => 'Renamed']);
Umami::deleteWebsite('site-uuid'); // bool
Umami::users(); // Collection<UserData>
Umami::createUser(['username' => 'jane', 'password' => 'secret']);
Umami::deleteUser('user-id'); // bool
DTOs & TypeScript
Responses are spatie/laravel-data objects under OiLab\OiLaravelUmami\Data
(WebsiteStatsData, PageviewsData, MetricData, WebsiteData, UserData, …). To
generate TypeScript interfaces, add the namespace to config/oi-laravel-ts.php:
'data_namespaces' => [
'OiLab\\OiLaravelUmami\\Data',
],
then run php artisan oi:gen-ts.
Testing
composer test
AI Assistant Skills
Install the bundled skill into your app:
php artisan oi:install-ai-skill
This copies oilab-laravel-umami into your .claude/ and .junie/ skill directories and
updates your root CLAUDE.md.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
When contributing:
- Write tests for new features
- Ensure all tests pass:
vendor/bin/pest - Follow existing code style
- Update documentation as needed
License
This package is open-source software licensed under the MIT license.
Credits
Olivier Lacombe - Creator and maintainer
Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.
Projects & Resources:
- OI Dev Docs - Documentation for all Open Source OI Lab packages
- OnAI - Training courses and masterclasses on generative AI for businesses
- Promptr - Prompt engineering Management Platform
Support
For support, please open an issue on the GitHub repository.