Download the PHP package preverus/preverus-laravel without Composer

Preverus Laravel

Laravel integration for Preverus hosted-script form protection and backend fraud decisions.

Website: https://preverus.com
Documentation: https://preverus.com/docs

This package is designed for Laravel, PHP, and server-rendered applications that do not use the JavaScript npm SDK. It pairs the hosted Preverus browser script with trusted Laravel backend enforcement.

Install

Add keys to .env:

Use two keys in production:

• Browser key: publishable, used by the hosted script.
• Server key: private, used only by Laravel for decisions and lookups.

Never put your server key in Blade, JavaScript, or public config.

Quick Start

Add the hosted script to your main layout:

Protect a server-rendered form:

Before submit, the hosted script attaches hidden fields:

Evaluate risk in your controller:

No try/catch is required for normal use. If Preverus is unavailable, the package returns a fallback DecisionResult based on your configured failure mode.

Failure Modes

Failure mode is optional. If you do not configure it, the package defaults to open so your Laravel app keeps working if Preverus is temporarily unreachable.

Optional .env value:

Supported modes:

Recommended defaults:

• Use open for signup, login, and checkout if uptime/revenue continuity is the priority.
• Use review for withdrawals, payouts, password resets, and payment changes.
• Use closed only when your business explicitly wants to stop the action during vendor/API failure.

You can override per call:

Fallback decisions are still valid objects:

Retries And Timeouts

Defaults are short so your Laravel request does not hang:

The underlying PHP client retries transient network failures and retryable HTTP statuses:

It does not retry validation or auth failures like 400, 401, 403, or 422.

The Laravel wrapper automatically sends X-Idempotency-Key for decision and event POSTs.

Circuit Breaker

The package includes a simple cache-backed circuit breaker. If repeated Preverus calls fail, Laravel temporarily stops making outbound calls and immediately returns fallback decisions.

This protects merchant apps from slow request chains during an outage.

What evaluate() Sends

Preverus::evaluate($request, [...]) automatically extracts:

It sends preverus_visitor_id as X-Visitor-ID when available.

It sends preverus_risk_session_token as risk_session_token when available. This is preferred because it links the trusted backend action to the stored browser session collected moments earlier.

Sensitive Actions

Use synchronous decisions for actions where your app needs an immediate allow/review/block answer:

Good event names include:

Middleware

For simple routes, you can use middleware:

The first argument is the event_type. The second optional argument is a route name for review outcomes.

Controller-level usage is still recommended for complex flows because every application handles step-up and manual review differently.

Queue Non-Blocking Events

Use queued events for telemetry that does not need to block the user:

Queue config:

Queued event jobs retry with backoff:

Lookups

Visitor lookup:

Metadata lookup:

Use lookups for investigations and added context. Do not use lookups as the only enforcement decision for sensitive actions; call evaluate() for final allow/review/block guidance.

Webhook Verification

Webhook delivery is at-least-once. Always dedupe by X-Fraud-Webhook-Id or payload id.

For a complete verify-parse-dispatch flow:

The package does not own your idempotency table because every Laravel app stores operational events differently.

Strict Exceptions

If you want exceptions instead of fallback decisions:

Most production apps should use evaluate() so a temporary external failure does not crash the customer flow.

Full Config

Production Checklist

• Add @preverusScript(['auto' => true]) to layouts with protected forms.
• Add data-preverus-action to signup, login, checkout, withdraw, payout, password reset, and payment-change forms.
• Call Preverus::evaluate() before approving sensitive actions.
• Send your real account ID as user_id.
• Include metadata such as email, phone, username, and payment address where available.
• Use review outcomes for step-up auth or manual review.
• Configure failure mode per risk level.
• Keep PREVERUS_SERVER_KEY private.
• Verify and dedupe webhooks before processing them.