Download the PHP package multek/laravel-business-metrics without Composer

Laravel Business Metrics

Server-side business event tracking with flexible report generation for Laravel + PostgreSQL. Get real-time dashboards in Grafana and exploratory BI in Metabase — without streaming infrastructure.

Architecture

Design principles:

• public schema = transactional writes (app)
• analytics schema = read-only aggregations (dashboards)
• Events are append-only (auditable, no data loss)
• Reports use INSERT ... ON CONFLICT DO UPDATE (incremental upsert, idempotent)
• Each report is a PHP class with full SQL control — no rigid schema
• Reports run as queued jobs — visible in Horizon, with automatic retries

Requirements

• PHP 8.2+
• Laravel 11 or 12
• PostgreSQL 14+

Installation

Publish config and enum stub:

Run migrations and create analytics schema:

Configuration

Edit config/business-metrics.php:

1. Register your events

Option A — Enum (recommended):

Edit app/Enums/BusinessEventType.php and uncomment/add your events:

Then point config to it:

Option B — Array:

2. Create reports

Each report is a PHP class that defines its own SQL, output table, and schedule. You get full SQL control — compute activation rates, cohort retention, revenue breakdowns, or anything that needs custom joins and data from any table.

This generates app/Reports/ActivationRateReport.php:

How incremental upsert works:

• WHERE occurred_at >= NOW() - INTERVAL '3 weeks' → only queries recent data
• ON CONFLICT ... DO UPDATE → upserts recent rows (insert new, update existing)
• Rows older than the lookback window → untouched, stay forever
• No retention pruning by default → data accumulates over time

3. Register reports

4. Create tables

5. How scheduling works (zero-config)

You don't need to register anything in your scheduler. The package handles it automatically.

When you register a report in config and define its schedule() cron expression, the package's ServiceProvider automatically registers it with Laravel's scheduler:

So the full flow is:

1. You create a report class with schedule() returning a cron expression (e.g. '0 */6 * * *')
2. You register it in config/business-metrics.php → 'reports' array
3. The package reads all reports on boot, and for each one registers a scheduled job with that cron
4. Laravel's scheduler (php artisan schedule:run, which your server runs every minute via crontab) checks the cron and dispatches ProcessReportJob to the queue when it matches
5. Your queue worker picks up the job, runs the report SQL, done

The only thing you need on your server is the standard Laravel crontab entry (you probably already have this):

And a queue worker running:

6. Queue configuration (optional)

Configure the queue name for report jobs in .env:

Or leave it unset to use the default queue. Report jobs are visible in Horizon, retry automatically (3 attempts, 60s backoff), and won't run concurrently for the same report (ShouldBeUnique).

7. Run reports manually

For debugging or one-off runs:

Usage

Logging events

Via Facade:

Via Trait on Models

Async events (queue)

Set in .env:

Events will be dispatched to the queue instead of writing synchronously. Use sync (null) for critical events like payments.

Artisan Commands

BusinessReport API

Each report extends Multek\BusinessMetrics\Reports\BusinessReport:

Grafana Queries (Examples)

Since reports produce custom tables, your Grafana queries match your report schema:

Connecting Dashboards

Grafana

1. Add PostgreSQL data source pointing to your DB (use read-only user)

2. Grant permissions:

3. Create dashboards querying analytics.* tables

Metabase

Same read-only user. Point Metabase to the same DB, it will discover both public and analytics schemas for ad-hoc exploration.

Scaling Roadmap

The package is designed so that when you move to a warehouse, you replicate the same business_events table and report structure — no redesign needed.

License

MIT