Symfony Precognition Laravel Package

Technical Evaluation

Architecture fit. Unchanged in kind: this is a Symfony bundle, not a Laravel package. It hooks Symfony's HTTP kernel (kernel.controller/short-circuit and kernel.exception listeners), the Symfony Validator/MapRequestPayload/MapQueryString argument resolvers, and the DI container to short-circuit or filter validation failures. None of these extension points map onto Laravel's HTTP kernel, FormRequest lifecycle, or Illuminate\Validation. For a Laravel-first portfolio the architectural fit remains poor-to-none — Laravel's native Precognition (HandlePrecognitiveRequests, Precognition / Precognition-Validate-Only headers) is a first-party feature and replacing it with a third-party bundle is a net negative. Its legitimate fit is the Symfony half of a hybrid estate (Symfony services, admin/back-office, API Platform endpoints), where no equivalent first-party primitive exists.

What v1.0.0 changes. This is the first stable release and it materially closes the "is this a sketch or a package?" question:

• Complete primitive set: request/header primitives, PrecognitiveForm attribute, short-circuit listener, validate-only listener, violation path filter, response listener, and bundle service registration. The API surface is now enumerable — which means the fork/vendor scope is finally estimable rather than speculative.
• Route opt-in is now explicit (require precognitive route opt in). This is the single most valuable safety control in the release: precognition cannot silently apply to an endpoint that has side effects.
• Support matrix is declared (require symfony components and declare supported versions), and the bug-fix list evidences real Symfony 6.4 ↔ 7.x dual support (new HttpException for 6.4, MapUploadedFile PHPStan ignore on 6.4, MapQueryString status preservation).
• MIT license committed, plus release-please automation, pre-commit hooks, and PHPStan gates. These are hygiene signals that raise confidence in maintainer competence, even though they say nothing about bus factor.

Architectural nuance worth flagging. The two listeners imply two precognitive paths with different risk profiles:

• Short-circuit path (PrecognitiveForm): controller is skipped, validation runs in the argument resolver. Low side-effect risk, but authorization performed in the controller is skipped too.
• Validate-only path (kernel.exception + violation path filter): the controller executes, throws a validation exception, and the listener filters violations down to the requested fields. If the controller performs work before validation (persistence, dispatch, external calls), a precognitive request can trigger side effects. This should be treated as the primary safety hazard in adoption.

Technical risk.

Key questions.

1. Does it emit/consume Laravel's header contract? Partially answered — primitives exist; confirm the exact header names and Precognition-Validate-Only semantics match Laravel's, or the gateway must translate.
2. How are rules declared (PrecognitiveForm attribute vs. Symfony constraints) and can that declaration be exported as a rule manifest shared with the Laravel side?
3. Sharper: on the validate-only path, what is the guaranteed ordering between the controller body, validation, and security voters? Is there a documented "no side effects before validation" contract?
4. Which Symfony versions are in the CI matrix, and what is the deprecation/support policy for 1.x? (Versions are declared; the policy is not.)
5. Is this FundraisingBox internal tooling published by-product, or a supported product with a maintainer commitment?
6. What is the success response contract (204 vs. partial payload) and is it stable enough to build a client against?
7. New: does the bundle document required listener priorities, and does it conflict with API Platform's own exception listener when both are installed?

Integration Approach

Stack fit. Unchanged: adopt only where a Symfony runtime is in the request path. Laravel remains the client-facing BFF/API gateway using native Precognition; Symfony services use this bundle. One UX, two implementations — acceptable only if headers and the 422 error envelope are normalized at the gateway.

Migration path. Do not migrate Laravel endpoints onto this package. Instead:

• Use the bundle to formalize validation for Symfony endpoints currently validating inside controllers — but only after auditing those controllers for pre-validation side effects, preferring migration to MapRequestPayload/PrecognitiveForm so the short-circuit path applies.
• Opt in route-by-route via the new explicit opt-in; treat the opt-in list as a reviewed artifact, not a default.
• Lift validation contracts into a shared schema (OpenAPI 3.1 + JSON Schema, or a generated rule manifest) so Laravel FormRequest rules and Symfony constraints derive from one source.
• Fork scope is now estimable. v1.0.0 enumerates the surface: two listeners, a response listener, a violation path filter, one attribute, one bundle class. A thin in-house fork is a known, bounded cost under MIT — document it now rather than at abandonment.

Compatibility. PHP 8.1+; Symfony 6.4 LTS and 7.x both exercised. No dependency conflict surface with Laravel packages (no shared deps) — the constraint remains operational (two validation stacks, two rule sources). Verify listener priorities against Security and API Platform in a realistic kernel before piloting.

Sequencing.

1. Spike (1–2 days): install in one Symfony service; confirm opt-in behavior and that precognitive requests are rejected/ignored on non-opted routes.
2. Listener-priority audit (new): dump the kernel's exception/controller listener order with Security and API Platform installed; confirm the validate-only path cannot run after side effects.
3. Contract decision: standardize headers and the 422 envelope across both stacks; publish as an internal spec with a named owner.
4. Pilot: one high-traffic form endpoint per stack; instrument rejection rate, latency, and — critically — any writes occurring on precognitive requests.
5. Authorization review before wider rollout.
6. Generalize only after the pilot shows measurable reduction in round-trips or invalid submissions.

Operational Impact

Maintenance. 1.0.0 is a semver commitment, which reduces churn risk, but you are still effectively the maintainer. Pin the version; do not float. Budget a quarterly review of Symfony major compatibility and keep the documented fork procedure current — the release automation suggests upstream will keep pace, but continuity is still one person deep.

Support. No vendor, no SLA, GitHub issues only. v1.0.0's hygiene (PHPStan, pre-commit, release-please, MIT) raises the floor on quality but not on availability. If Symfony endpoints are revenue-bearing, the fork remains plan, not insurance.

Scaling. Precognition roughly doubles request volume on opted-in validated endpoints while removing controller/DB work per rejected request — but only on the short-circuit path. Endpoints using the validate-only path still execute the controller, so the cost model is closer to "validate twice" than "skip the expensive part." Net benefit is favorable for write-heavy forms mapped to request DTOs, unfavorable for cheap endpoints or controllers with pre-validation work. Exclude precognitive requests from rate-limit accounting or give them a separate budget.

Failure modes.

• Side effects during validate-only — controller persists/dispatches before throwing; precognitive requests mutate state.
• Silent auth bypass — short-circuited requests never reach in-controller authorization; policies must live in the validation layer.
• Listener-order regression — a new bundle or a priority change reroutes validation errors; behavior shifts without any code change to your app.
• Contract drift — precognitive rules accept input the controller then rejects, producing confusing 500s or partial writes.
• Header spoofing — clients sending the precognition header on real submits; always revalidate on execution and treat the header as advisory.
• Enumeration — verbose field-level errors leak schema; gate behind authentication for sensitive resources.
• Abandonment — upstream stops tracking Symfony majors; the pinned 1.0.0 becomes a security liability.

Ramp-up. For a Symfony developer: half a day for the happy path; add a day to understand the two-listener split, opt-in semantics, and listener priorities. For a Laravel developer: near-zero conceptual ramp-up (it mirrors native Precognition), real ramp-up on Symfony kernel events and exception listeners if they must debug or fork. Document the two-stack split explicitly — and the short-circuit vs. validate-only distinction — or engineers will assume the native middleware covers Symfony routes and that the controller never runs.