Download the PHP package mirafive/sdk-laravel without Composer

MIRA FIVE for Laravel

Privacy-first analytics and feature flags for Laravel, hosted in the EU: track business events from your controllers and jobs, evaluate flags in-process, and add the website tracker with one Blade directive. Events are sent after the response, so your pages never wait for analytics.

Install

PHP 8.3+, Laravel 11, 12 or 13. The service provider and the Mira facade are discovered automatically. To change the defaults, publish the configuration:

Quickstart

Create a server source and a website source in MIRA FIVE and put their keys in .env:

Track from a controller:

Identify after login, with the user's internal id and a few traits:

Mira::forUser($request->user()) fills in getAuthIdentifier() as the user id for track(), identify() and flags().

Add the tracker to your layout's <head>:

It prints the hosted script with your website key, data-mode="full" when MIRAFIVE_SCRIPT_MODE=full (plus data-host when you use your own host), and a Vite CSP nonce when one is set. More tracker attributes go in as an array:

Verify the setup:

It sends a $install_check event (never stored or billed) and prints the receipt.

Consent & privacy

MIRA FIVE has two collection modes, full and consentless, set separately for server events (MIRAFIVE_MODE, default full) and for the tracker (MIRAFIVE_SCRIPT_MODE, default consentless):

• full may carry userId, anonymousId and sessionId. Server events assume your site already holds consent or another lawful basis for the person they describe; the SDK cannot ask. A tracker in full mode stores nothing until your consent banner grants it (mirafive('consent', true)).
• consentless carries no identifiers at all and needs no banner, which is why it is the tracker's default. On the server, passing an identifier throws an InvalidArgumentException, so a misconfiguration shows up on the first call.

Rules for both modes:

• Never send an email address as userId. Use your internal id (42, a UUID). forUser() uses getAuthIdentifier(), which is the primary key for Eloquent users.
• No personal data in event names or properties: no names, emails, phone numbers or free text a person typed.
• The secret key never reaches a page. @mirafiveScript prints only the website key.

Configuration

Delivery failures go to your default log channel as warnings. MiraFive\Mira and MiraFive\Flags\MiraFlags can be injected directly; to send through your own HTTP client, bind MiraFive\Http\Transport (e.g. to MiraFive\Http\Psr18Transport) before they are resolved.

Queues & Octane

When events are sent. track() and identify() buffer. The buffer is sent once, when Laravel terminates (after the response under PHP-FPM), after each Octane request, task and tick, and after each queued job; the core's own shutdown flush is switched off. Every 100 events it is sent early. send() is always immediate.

Queued delivery. With MIRAFIVE_QUEUE set, each buffered batch is encoded once and handed to a MiraFive\Laravel\Queue\SendBatch job, so the request does not wait for MIRA FIVE at all. The job carries the body, never the key: the worker sends it with its own configuration. The body is final and keeps its batch id, so a job that runs twice is stored once. Retryable failures are retried by the queue (5 tries, backoff up to 15 minutes); refused batches are logged and dropped. A worker without MIRAFIVE_SECRET_KEY logs an error and fails the job instead of dropping it; one with MIRAFIVE_ENABLED=false drops it quietly. Batches are up to 1 MiB of JSON (SQS allows 256 KB). send() never queues: it always sends immediately and returns the collector's receipt.

Octane. The package is safe in long-running workers: no request state is kept in singletons, and the buffer is flushed at the end of every request. It adds MiraFive\Mira, MiraFlags, the transport and the facade's client to octane.warm, so a worker keeps one HTTP connection and one flag document instead of building them per request.

Flags

Or Mira::forUser($request->user())->flags(properties: [...]), which reads the opt-out from the current request unless you pass optedOut. Reads never throw; without a document every flag answers its fallback. The document is fetched on first use and shared between requests through the cache store.

Bootstrap in Blade. Hand the server's answers to the browser SDK so the first paint shows the right variant:

The unit takes userId, anonymousId, properties, consent and optedOut (read from Sec-GPC/DNT when left out). You can also pass flags you already read: @mirafiveFlags($flags). Only flags your website reads are included, and every value is escaped so it cannot end the script.

A page carrying a bootstrap must never be stored by a shared cache. The package adds Cache-Control: private, no-store to every response whose view printed @mirafiveFlags; nothing to configure. If you print $flags->bootstrap() yourself, send the header yourself: response($html)->withHeaders(MiraFive\Flags\MiraFlags::BOOTSTRAP_HEADERS).

Testing with Mira::fake()

The fake records track(), identify() and send() through the facade and through an injected MiraFive\Laravel\Client. Input is still checked, so an event MIRA FIVE would refuse fails the test. Flags answer their fallbacks. Code that injects MiraFive\Mira directly is not faked; set MIRAFIVE_ENABLED=false in phpunit.xml so it sends nothing.

Troubleshooting

• Nothing arrives. Run php artisan mirafive:check. Then look for [mirafive] warnings in your log.
• unauthorized. MIRAFIVE_SECRET_KEY is missing, wrong or revoked; it must be the secret key of a server source. After changing .env in production, run php artisan config:cache again.
• website_key_as_bearer. The website key ended up in MIRAFIVE_SECRET_KEY. Server code needs the secret key.
• InvalidArgumentException: A consentless client may not send userId. MIRAFIVE_MODE is consentless; drop the identifiers or switch to full where you hold consent.
• No tracker tag. MIRAFIVE_WEBSITE_KEY is empty or MIRAFIVE_ENABLED is false.
• Queued batches never arrive. A worker must run the configured queue (php artisan queue:work redis --queue=mirafive).
• Flags always answer the fallback. Check Mira::flags()->status() and ->evaluate($key)->errorCode: NOT_READY means no document (see the log), FLAG_NOT_FOUND that the flag is not served to this source.

For AI agents

A prompt for an agent adding MIRA FIVE to a Laravel application:

Facts for agents:

• Package mirafive/sdk-laravel, namespace MiraFive\Laravel, facade MiraFive\Laravel\Facades\Mira (alias Mira), wrapping mirafive/sdk-php (MiraFive\Mira, MiraFive\Flags\MiraFlags, both container singletons).
• Env: MIRAFIVE_SECRET_KEY, MIRAFIVE_WEBSITE_KEY, MIRAFIVE_HOST, MIRAFIVE_MODE (server, default full), MIRAFIVE_SCRIPT_MODE (tracker, default consentless), MIRAFIVE_QUEUE, MIRAFIVE_ENABLED, MIRAFIVE_SCRIPT_URL, MIRAFIVE_FLAGS_REFRESH, MIRAFIVE_FLAGS_CACHE. Config file config/mirafive.php, publish tag mirafive-config.
• Facade: track(name, userId:, anonymousId:, sessionId:, properties:, time:, page:), identify(userId, traits), send(events, idempotencyKey:) (immediate, returns MiraFive\Receipt, throws MiraFive\MiraError), flush(), flags(), forUser($user), optedOut($request), fake().
• Buffered events are flushed on terminate, Octane RequestTerminated, and after each queued job. Never call flush() in normal code.
• Blade: @mirafiveScript / @mirafiveScript([...data attributes]), @mirafiveFlags($unit) (sets Cache-Control: private, no-store automatically).
• Without a secret key, or with MIRAFIVE_ENABLED=false, nothing is sent and no key is needed; invalid events still throw.
• With MIRAFIVE_QUEUE, buffered batches go to SendBatch jobs; send() is always synchronous.
• php artisan mirafive:check proves key and host; success is a receipt with reason install_check.
• userId is the internal id, never an email. The secret key never goes to a browser.

License

MIT, see LICENSE. Copyright (c) 2026 Cloo GmbH.