Download the PHP package abdulsalamalkhatib/laravel-guardian without Composer

Laravel Guardian

Production correctness engine for Laravel.

Laravel Guardian looks for code that is syntactically valid, type-correct, and often testable, but can still violate production invariants under transactions, concurrency, or serialization.

V1 intentionally ships only three rules:

• GUA-001 — External side effects inside database transactions.
• GUA-002 — Dangerous Eloquent read-modify-write / check-then-act flows.
• GUA-003 — Sensitive data reaching API serialization paths.

Guardian is not a replacement for PHPStan, Larastan, Telescope, Debugbar, or a generic SAST scanner. It focuses on Laravel-specific production semantics.

Requirements

• PHP 8.2+
• Laravel 11.44.2+, 12.4.1+, or 13.x
• PHPStan 2.2.2+
• Larastan 3.11+

Installation

After publishing the package to Packagist:

For local development from this ZIP before publishing:

Then:

Quick start

or without booting the Laravel application:

Example output:

GUA-001 — transaction side effects

Unsafe:

The remote system may commit while the DB transaction later rolls back.

Guardian also follows known application calls:

Safe queued pattern:

Built-in external-effect families include HTTP, mail, notifications, queue dispatch, filesystem writes, process execution, and configured external SDK methods.

GUA-002 — unsafe Eloquent read-modify-write

Unsafe lost update:

A database transaction by itself does not make this safe.

Safe pessimistic lock:

Safe fixed atomic delta:

Still unsafe despite using increment():

The write primitive is atomic, but the delta was derived from stale state. Guardian distinguishes this from a fixed atomic increment.

Guardian also detects check-then-act transitions such as:

Use row locks or compare-and-swap semantics for state transitions.

GUA-003 — sensitive exposure

Guardian builds a sensitivity registry from:

1. explicit sensitive_fields configuration;
2. Eloquent $hidden fields;
3. a conservative built-in list for secrets such as passwords, API keys, refresh tokens, and 2FA secrets.

Unsafe:

If Player::$hidden or Guardian config marks phone as sensitive, the resource is reported.

Configured sanitizers are treated as declassification boundaries:

Guardian also tracks simple local-variable taint into response()->json(), JsonResponse, and resource arrays.

Configuration

Publish config/guardian.php and tune only application-specific policy:

Commands

Laravel aliases:

Exit codes:

Severity and confidence are separate

A finding can be:

or:

Severity answers how bad the failure would be. Confidence answers how strongly static analysis proved the path.

Baseline

Adopt Guardian on a legacy codebase without blocking every existing issue:

This writes stable semantic fingerprints to guardian-baseline.json. Subsequent scans still show counts for suppressed/baselined findings but only new active findings block CI.

Refresh the baseline by running the command again after fixing or intentionally accepting findings.

Narrow suppressions

Inline suppression requires a reason:

Method/class suppression:

For intentional sensitive exposure, prefer the narrower field-level attribute instead of suppressing all of GUA-003:

GuardianAllowsSensitive can be placed on a resource method or class and only suppresses the listed sensitive fields.

Avoid broad project-wide ignores. A suppression is an explicit correctness exception and should be reviewable.

PHPStan / Larastan integration

The package ships a PHPStan extension bridge in extension.neon.

With PHPStan extension discovery enabled, or by including it manually:

A full-directory PHPStan analysis receives Guardian findings as PHPStan errors with identifiers:

Guardian metadata includes severity, confidence, and fingerprint. File-only partial PHPStan runs intentionally do not trigger Guardian's whole-project scan.

CI

Console gate:

SARIF:

GitLab Code Quality:

JUnit:

Plugin SDK

Guardian's registry supports additional rules and domain adapters without modifying core:

Extension contracts:

• Rule
• Reporter
• EffectProvider
• SanitizerProvider
• ConcurrencyGuardProvider
• Plugin

Future plugin families can live under separate Composer packages such as Guardian\Concurrency, Guardian\Queues, and Guardian\Performance without bloating the V1 core rule set.

Architecture

See docs/ARCHITECTURE.md for the detailed design and correctness boundaries.

Known limits

Static analysis cannot prove all behavior in highly dynamic PHP. Guardian deliberately prefers an explicit confidence level over pretending certainty.

Current V1 limitations include:

• dynamic method names and runtime-selected container bindings may not resolve interprocedurally;
• custom transaction abstractions need a future transaction-provider extension or must wrap supported Laravel primitives;
• GUA-002 is deliberately conservative and does not attempt full symbolic execution;
• GUA-003 is not an authorization theorem prover: conditional authorization lowers confidence rather than proving the exposure safe;
• distributed lock key correctness cannot generally be proven statically.

Zero Guardian findings means no supported invariant violation was proven. It does not mean the application is bug-free.

Development

The integration suite contains both unsafe fixtures that must be detected and safe fixtures that must remain clean.

License

MIT.