README

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.

oi-lab / oi-laravel-umami

Maintainers

Package info

Statistics

Security