Intercept Injection Guard Laravel Package

Getting Started

• Install with composer require promptphp/intercept-injection-guard. The package is a read-only subtree split of promptphp/intercept, so the code you get here is a mirror of one directory in the monorepo.
• Look upstream first. Issues, PRs, and the fuller documentation live in promptphp/intercept, not in this split repo. Clone the monorepo when you need to read tests or see how the guard is wired into the rest of the Intercept stack.
• Check whether a config file is publishable (php artisan vendor:publish --tag=intercept-injection-guard-config). If a config lands in config/, that file is your primary tuning surface — read it end to end before writing any code, since the defaults are what actually run in production.
• First use case: put the guard at the input boundary. In a typical Laravel app that means a middleware on the web/API group or a rule inside the FormRequest that validates untrusted input before it reaches the query builder, a raw DB::statement, or an outbound prompt/LLM call. Start by guarding a single endpoint, log what it flags, and only then consider throwing.
• Confirm the version you installed lines up with the monorepo commit you intend to track. v1.1.1 corresponds to intercept-source: 73ed9bb731d9b793173dba33cf4a96cce8c8d5ea; if you file a bug, quote that hash so upstream can locate the exact code.

Implementation Patterns

• HTTP boundary middleware. Register the guard globally or on specific route groups. Keep it off routes that carry large binary or base64 payloads unless you've explicitly allowed those shapes — the guard runs on every request in the group.
• FormRequest integration. Prefer validating untrusted fields explicitly (per-field rules) over a blanket middleware when only a couple of inputs are risky. This keeps the failure message attached to the right field and avoids rejecting unrelated traffic.
• Service-layer calls for non-HTTP entry points. Queued jobs, console commands, webhooks, and scheduled tasks never pass through HTTP middleware. Wrap the same guard around the point where those paths assemble a query or a prompt, ideally in one small helper/service so there's a single call site to audit.
• Centralised configuration, environment-scoped strictness. Keep pattern lists and allowlists in config, not inline. Run permissive (log-only) in local and staging, strict (reject) in production — a config flag rather than a code branch.
• Telemetry on interception. Log every hit with the route, field name, and a redacted sample. Injection guards are notoriously noisy at first; without this data you cannot tune the allowlist and will end up disabling the package.
• Test with realistic payloads. Add feature tests that assert a known-bad payload is rejected and that legitimate ones (markdown, code snippets, JSON columns, localized names with apostrophes) pass. The second set is what breaks in production.
• Pin the version in composer.json and upgrade deliberately. Because this is a split, a patch bump here can carry changes made anywhere in the monorepo's guard directory.

Gotchas and Tips

• Do not open pull requests against this repository. It is generated; changes must go to promptphp/intercept and will be re-split. A PR here will be closed and your work lost.
• Version drift between the split and the monorepo is the most common source of confusion. If the behaviour you see doesn't match the upstream docs, compare the source commit hash before debugging further.
• False positives are the main operational risk. Free-text fields, search boxes, rich-text editors, and anything accepting user-supplied JSON routinely trip naive pattern matching. Budget time for allowlisting, and consider scoping the guard to fields that are actually interpolated rather than every string in the request.
• This is defence in depth, not a replacement for parameterised queries. Keep using bindings, Eloquent, and proper escaping. A guard that silently normalises input can mask a genuine vulnerability rather than fix it.
• Remember php artisan config:cache. Config edits appear to do nothing in cached environments — a classic hour lost. Clear the cache after changing patterns or the strictness flag.
• Prefer log-and-allow mode when rolling out. Ship in observation mode for at least a release cycle, review the hits, then flip to rejecting. Flipping straight to strict on an existing app is how you take down checkout.
• The extension point is upstream. If you need a custom matcher or a new input source, implement it against the monorepo's interfaces so it survives the next split — and contribute it back rather than forking the split repo.
• v1.1.1 is a patch release with no migration steps. If you are already on a 1.1.x version, this is a safe in-place composer update; there are no breaking changes or deprecations signalled by the version bump.