harvv/laravel

The official Harvv Composer package for Laravel 11, 12, and 13. One command installs it, one directive renders the pixel, one middleware tags every event with the route + user that hit it.

Install

Step 1 — Composer require

Until Packagist publish completes, install via VCS:

composer config repositories.harvv vcs https://github.com/AxiomState/harvv-laravel
composer require harvv/laravel:dev-main

Once Packagist publish lands you can drop the repositories step:

composer require harvv/laravel
Auto-discovery is on. The package's ServiceProvider registers automatically. You do not need to add it to config/app.php.

Step 2 — Run the installer

php artisan harvv:install

The installer prompts for your site key, generates a HMAC secret, writes both to .env, and offers to register the HarvvContext middleware. Re-running is safe — it skips steps that are already done.

For a non-interactive install (CI, Docker entrypoint, etc.):

php artisan harvv:install --site-key=YOUR_KEY --no-middleware --no-interaction

Step 3 — Drop the directive in your layout

Above </head> in your master layout:

@harvv

That's it. View source on any page and look for:

<script async src="https://harvv.com/px/<your-key>/pixel.js"></script>

Or run the verifier:

php artisan harvv:verify

Environment variables

The installer writes these for you, but they're straightforward to set manually:

# Required
HARVV_SITE_KEY=d1db1759f22827e4

# Recommended — signs per-request context so the receiver can verify it
HARVV_HMAC_SECRET=hlv1_<64 hex chars>

# Optional — set false to skip rendering (default: true when site key is set)
HARVV_ENABLED=true
Local-dev rendering As of 2026-05-12, the pixel renders in local too whenever HARVV_SITE_KEY is set, so install-verification works without env-var spelunking. Set HARVV_ENABLED=false if you don't want it firing in local. Older versions of this package default-disabled in local — upgrade to v0.1.1+.

Middleware (recommended)

The HarvvContext middleware tags every HTML response with a signed meta tag carrying the per-request context (route name, hashed user id, request id). The pixel picks it up automatically. The result: every issue Harvv surfaces is tied to the exact Laravel route + user that hit it — pivotable in your dashboard, traceable in your application logs.

The installer offers to register it. To register manually:

Laravel 11 / 12 — bootstrap/app.php

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \Harvv\Laravel\Http\Middleware\HarvvContext::class,
    ]);
})

Laravel 10 — app/Http/Kernel.php

protected $middlewareGroups = [
    'web' => [
        \Harvv\Laravel\Http\Middleware\HarvvContext::class,
        // ...
    ],
];

Skip the middleware if you don't need per-request context (the pixel still captures everything else: clicks, scroll, Core Web Vitals, etc., just unattributed to a Laravel route).

Blade component (alternative)

The package also ships an x-harvv-pixel component if you prefer Blade components over directives:

<x-harvv-pixel />

Verify your install

One command:

php artisan harvv:verify

It checks five things and prints the rendered pixel URL:

Exits 0 on success — wire it into CI to gate deploys on a healthy Harvv install.

Troubleshooting

"@harvv renders empty in view-source"

Either HARVV_SITE_KEY is empty or HARVV_ENABLED is false. Run php artisan harvv:verify to confirm. On older versions (pre-2026-05-12), APP_ENV=local also disabled the pixel — upgrade to v0.1.1+.

"composer require harvv/laravel — Package not found"

Packagist publish hasn't completed yet. Use the VCS install:

composer config repositories.harvv vcs https://github.com/AxiomState/harvv-laravel
composer require harvv/laravel:dev-main

"Events show in the dashboard but no Laravel route attached"

The HarvvContext middleware isn't in the stack, the HMAC secret is missing, or the secret in .env doesn't match the one on the site in Studio (rotate it from Studio → Settings if unsure).

"php artisan harvv:install — command not found"

You're on an old install. Run composer update harvv/laravel and try again. The command landed in v0.1.1 (2026-05-12).

Custom config

Publish the config file only if you need to customize beyond what env vars cover:

php artisan vendor:publish --tag=harvv-config

Drops config/harvv.php into your app. Edit, deploy.

Source + issues