Laravel Ai Guard Laravel Package

Product Decisions This Supports

• Whether to treat AI traffic as a first-class product surface. With v3.1.0, the package no longer just blocks or allows — it identifies. BotClassified, AgentVerified, and SpoofedBotDetected give you a named, categorised, method-attributed verdict (chatgpt.com / ai_agents / web_bot_auth) that other parts of the product can act on. That unlocks roadmap conversations that were previously blocked on "we can't tell who's hitting us": agent-specific rate limits or metering, AI-crawler-aware analytics segmentation, content licensing or pay-per-crawl experiments, verified-search-engine handling for SEO, and spoofed-crawler alerting for security.
• Build vs. buy, with the lock-in objection removed. Verification is genuinely hard to build (Web Bot Auth signature validation, published IP range matching, reverse DNS, plus spoof detection when a client claims an identity and fails every check). The ai-guard.verdict/1 contract means other teams subscribe to a stable, versioned payload rather than importing the package — so adopting it is a reversible decision, not a platform commitment. That materially changes the calculus in a buy-vs-build review.
• Decoupling identity from policy. The release makes an explicit product distinction: a verified Googlebot reports as search_engines even though that category isn't blocked by default. That lets you separate "who is this?" from "what do we do about it?" — so blocking rules can live in product/ops config while identity is consumed by billing, analytics, and personalisation without stepping on each other.
• Feature-level decisions now cheap to test. Because verdicts are also readable from request()->attributes->get('ai_guard.verdict') and listeners run through the standard Laravel event bus, an experiment (e.g. "serve a different response to verified AI agents") is a listener, not a fork. Cheap to prototype, cheap to remove.
• Observability and compliance. The SIEM/OpenTelemetry export fix in this release matters if you're reporting on bot traffic to security or legal — version attribution was wrong in 3.0.1, so any dashboards built on it should be re-baselined.

When to Consider This Package

Consider it when:

• You run a Laravel app (10–13 on PHP 8.1–8.4) with meaningful public, unauthenticated traffic and no reliable way to separate humans from agents.
• You need verified identity, not just user-agent sniffing — i.e. the difference between "claims to be Googlebot" and "is Googlebot" is a decision you actually make.
• More than one team or subsystem needs bot identity (security, analytics, growth, monetisation). The interop contract is designed precisely for this: subscribe by class-name string, no use statement, no Composer dependency, keeps working if the package is later removed.
• You want identity published as events with safe payloads — scalar, read-only, queueable, no query strings — so downstream consumers can't be broken by a malformed listener, and a throwing listener never fails the request.
• You need an escape hatch: interop.enabled => false kills the events; whitelisted requests aren't evaluated at all.

Look elsewhere when:

• You need edge/WAF-level mitigation or volumetric bot defence. This is application-layer identity and gating, not a CDN substitute.
• You need ML-driven behavioural scoring, fingerprinting, or CAPTCHA orchestration — this package classifies known bots and verifiable agents, not novel or adversarial human-like traffic.
• You're not on Laravel. The contract is a Laravel event-bus idiom; a Symfony or framework-agnostic service would need an adapter, which reintroduces the coupling the release is trying to remove.
• You require a commercial SLA, indemnity, or vendor support contract. This is a community package; the stability guarantee is a test-enforced fixture, not a legal one.
• Your traffic volume makes per-request in-app evaluation cost-prohibitive relative to doing it at the edge.

How to Pitch It (Stakeholders)

For executives: This release turns a bot-blocking utility into a reusable identity layer for the platform. The strategic point is optionality — we can now make deliberate decisions about AI traffic (allow, meter, license, block, or simply measure) and change our mind later, because every other system consumes a stable, versioned contract rather than the package itself. Adoption cost is low and reversible: the change is purely additive, nothing alters behaviour unless a team opts in, and there's a one-flag off switch. Verification of bot identity — signatures, IP ranges, reverse DNS, spoof detection — is work we would otherwise have to buy or build and maintain; this lets us defer that spend while keeping the door open.

For engineering: v3.1.0 is additive and non-breaking. Three events fire at most once per request, carrying a fixture-locked ai-guard.verdict/1 payload with a guarantee that fields may be added but never renamed or removed within v1 — the test suite fails if the package drifts from the canonical fixture. Payloads are scalar, read-only, and queueable; listener exceptions are contained. The same verdict is available synchronously via a request attribute. Quality signals are reasonable for a dependency of this role: 482 tests, PHPStan level 6, Laravel Pint, and support across Laravel 10–13 / PHP 8.1–8.4. The one thing to note operationally is the SIEM/OTel version-attribution fix — if we're already exporting, existing telemetry mislabels 3.0.1 as 3.0.0 and should be re-baselined after the upgrade.