Download the PHP package mirafive/sdk-php without Composer

MIRA FIVE for PHP

Privacy-first analytics and feature flags for PHP servers: send events from your backend and evaluate flags in-process, hosted in the EU.

Install

PHP 8.3 or newer with ext-json. ext-curl is used when present, otherwise PHP streams; you can also send through your own PSR-18 client. There are no required Composer dependencies.

Using a framework? Take mirafive/sdk-laravel or mirafive/sdk-symfony: they wire this SDK into the container and flush after the response.

Quickstart

Create a server source in MIRA FIVE and put its secret key in the environment:

For events that must be recorded exactly once, such as a payment webhook that may be delivered twice, send them immediately with an idempotency key:

The same key always maps to the same batch, so a repeat is stored once.

Consent & privacy

MIRA FIVE has two collection modes:

• Full (Mode::Full, the default) may carry userId, anonymousId and sessionId. Use it for people who consented, or where you already hold another lawful basis for the processing.
• Consentless (Mode::Consentless) carries no identifiers at all. Passing one throws an InvalidArgumentException, so a misconfiguration shows up on the first call instead of as refused batches.

Rules that hold in both modes:

• Never put personal data in event names or properties. No e-mail addresses, names, phone numbers or free text a person typed. Event names are labels such as signup, not signup [email protected].
• userId is pseudonymous. Pass your own internal id (u_42, a UUID), never an e-mail address.
• The secret key stays on the server. It never goes into HTML, JavaScript or a mobile app. Browsers use the public website key with the browser SDK.

API reference

MiraFive\Mira

The buffer is also sent when flushAt is reached, when the Mira object is destroyed, and once in a shutdown function at the end of the request (unless flushOnShutdown: false).

Defaults. flushAt 100 events, timeoutMs 5,000 per attempt, connectTimeoutMs 1,000, flushDeadlineMs 3,000, maxRetries 2, maxRetryAfterMs 3,000. They are lower than the Node server SDK's (10 s timeout, 3 retries) because delivery usually runs inside a PHP web request. For flags: refreshSeconds 30, a 1,500 ms document fetch, a 500 ms segment lookup and a 1,000 ms connect timeout.

Outages. A flush never takes longer than flushDeadlineMs: each attempt's timeout shrinks to what is left, and a wait that would pass the deadline ends the flush. After a flush fails for a retryable reason, flushes skip the network for 30 s and drop their events; the first skip is reported to onError. With a PSR-16 cache, that 30 s pause holds for every PHP process, so an outage costs one request a timeout rather than every request. send() and deliverPrepared() are not paused; they always try.

Refused events. When the collector refuses a buffered batch with validation_failed, the events its errors name are reported to onError and dropped, and the rest is resent under a new batch id derived from the old one (the same input always gives the same id, so a queue job that runs twice is still stored once). When an error names no event, the whole batch is reported and dropped.

Delivery. Batches go to POST {host}/v1/batch as JSON with the secret key as a bearer token, at most 1000 events and 1 MiB each (larger buffers are split). Retries use full-jitter exponential backoff (100 ms base, 1 s cap), honour Retry-After, and resend the byte-identical body under the same batch id, so a retry is never counted twice.

Empty objects. A PHP [] is sent as a JSON list; pass new stdClass where you mean {}.

Input checks. Input the collector would refuse throws an InvalidArgumentException immediately, because one bad event would otherwise cost every event in its batch: names of 1–128 characters without surrounding whitespace, $ names other than the reserved ones ($pageview, $autocapture, $identify, $search, $install_check, $exposure), blank or overlong ids, properties that are a list, nest deeper than 5 levels, carry more than 64 values or encode to more than 32 KB. Page fields that are too long are shortened instead.

Queues, frameworks and tests

• Deliver from a queue. With handOff, every buffered flush (explicit, at flushAt, on shutdown) passes the encoded batch to your closure instead of sending it. Put the body on a queue; the worker calls $mira->deliverPrepared($body) on its own Mira, so the key never travels in the message. The body is final: retries resend it byte for byte under its batch id, so a job that runs twice is stored once. send() ignores handOff and always sends immediately.
• Flush on terminate. Frameworks pass flushOnShutdown: false and call flush() after the response.
• Local and test environments. enabled: false sends nothing and needs no key, but refuses the same input as production. track() keeps nothing, send() and deliverPrepared() return a local receipt with every event accepted, and flags answer their fallbacks.

MiraFive\Receipt

batch (string), accepted (int), dropped (int), reason (bot, install_check, ingestion_paused, allowance_exhausted or null). dropped > 0 with a reason means nothing was kept; the answer is still final.

MiraFive\MiraError

Extends RuntimeException.

Transports

MiraFive\Http\CurlTransport (default, reuses one connection per request), MiraFive\Http\StreamTransport (no extensions needed) and MiraFive\Http\Psr18Transport:

A PSR-18 client applies its own timeout. Keep it short: delivery runs inside your request.

Flags

for() takes userId (the unit of flags assigned by signed-in person), anonymousId (MIRA FIVE's anonymous id from the browser SDK, the unit of flags assigned by browser) and properties (facts your rules test; they stay in memory and are never sent). Reads are synchronous and never throw: without a document, or for an unknown key, they answer your fallback.

Consent and opt-out (FLAGS.md §5.1). Leave a scope out of consent when your own lawful basis applies; set it to false when the person declined:

The document. MiraFlags fetches GET {host}/v1/flags on first use and again on a read once it is older than refreshSeconds (default 30, at least 10), revalidating with If-None-Match. PHP-FPM starts every request with an empty process, so pass a PSR-16 cache: it shares the document (and failed fetches), segment memberships, the lookup pause and the hourly exposure marks between requests. Without one, each request fetches the document once and an experiment may be counted once per request.

Segments. When a flag tests segments, for() asks POST {host}/v1/flags/segments about the unit once per minute, with a short timeout. If the lookup fails, lookups pause for 30 s (or as long as Retry-After asks), segment conditions count as false and evaluate() reports MEMBERSHIP_UNAVAILABLE.

Snapshots. $flags->snapshot() returns the document in use as the JSON string MIRA FIVE sent (or null). Store it at build or deploy time and pass it back as document: to start from it while MIRA FIVE is unreachable. A document that cannot be read is reported to onError and ignored.

Experiments. enabled, variant and config send one $exposure per person, experiment and variant for experiments counted on your server. evaluate() never counts anyone. Experiments counted in the browser answer their default on the server (NOT_ALLOWED).

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

Only flags your website reads are included, and every <, >, &, U+2028 and U+2029 is escaped, so no value can end the script. Never let a shared cache store such a page.

Reasons (MiraFive\Flags\Reason): STATIC, TARGETING_MATCH, SPLIT, DEFAULT, DISABLED, ERROR. Error codes (MiraFive\Flags\ErrorCode): UNSUPPORTED (the flag needs a newer SDK), NOT_READY, FLAG_NOT_FOUND, MEMBERSHIP_UNAVAILABLE, NOT_ALLOWED.

Troubleshooting

• Nothing arrives. Pass onError (or a logger) and look at errorCode. Without either, failures go to error_log(). Then check the key and host with an install check (below).
• unauthorized. The key is missing, wrong or revoked. MIRAFIVE_SECRET_KEY must hold the secret key of a server source.
• website_key_as_bearer. You passed the public website key. Server code needs the secret key.
• InvalidArgumentException: A consentless client may not send userId. The client is in Mode::Consentless; drop the identifiers or use Mode::Full where you have consent.
• Events arrive only at the end of a long job, or never, in a worker. Octane, RoadRunner, Swoole and queue workers run for many requests, so the shutdown flush only fires when the worker stops. Call $mira->flush() after each request or job (the Laravel and Symfony packages do).
• Slow responses when MIRA FIVE is unreachable. A flush is capped at flushDeadlineMs (3 s), and after a failure flushes skip the network for 30 s. Pass a PSR-16 cache so that pause covers every PHP-FPM process, or lower flushDeadlineMs. For no delivery work in the request at all, use handOff with a queue.
• Flags always answer the fallback. Look at $flags->status() and $user->evaluate($key)->errorCode: NOT_READY means no document yet (see onError), FLAG_NOT_FOUND that the flag is not served to this source.

For AI agents

(a) A prompt for an agent adding MIRA FIVE to a plain PHP application:

(b) Facts for agents:

• Package mirafive/sdk-php, namespace MiraFive. Classes: MiraFive\Mira, MiraFive\Mode (Full, Consentless), MiraFive\Receipt, MiraFive\MiraError, MiraFive\Flags\MiraFlags, MiraFive\Flags\UserFlags, MiraFive\Flags\Evaluation, MiraFive\Http\Psr18Transport.
• Environment: MIRAFIVE_SECRET_KEY (required), MIRAFIVE_HOST (optional, default https://events.mirafive.io).
• The secret key never goes to a browser. Browsers use the website key with @mirafive/sdk-browser or the hosted tracker.
• track() and identify() buffer; the buffer is flushed on shutdown (once), on destruction, at flushAt events, or by flush(). send() is immediate and throws MiraError.
• Ids are strings: cast integer ids with (string). Under PHP-FPM pass a PSR-16 cache.
• track()/flush() never throw for transport reasons. Invalid input and identifiers in consentless mode throw InvalidArgumentException.
• MiraError::$errorCode holds the protocol code; getCode() is the HTTP status.
• Verify a setup with $mira->send([['name' => '$install_check']]): the receipt's reason is install_check.
• Framework packages: mirafive/sdk-laravel (facade MiraFive\Laravel\Facades\Mira, flush on terminating) and mirafive/sdk-symfony (MiraFive\Symfony\MiraFiveBundle, flush on kernel.terminate).

License

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