Laravel Flowfield Laravel Package

Technical Evaluation

Scope of evidence. No prior assessment exists and no internal repository data (composer.json, model inventory, test coverage) was supplied. This evaluation is derived solely from the v1.0.1 release notes for schtzie/laravel-flowfield and should be treated as a pre-discovery position, not a committed architectural decision.

Architecture fit. The package extends Eloquent via a query scope (scopeWithFlowFields) that decorates model hydration with derived "flow field" data. This is an in-ORM concern, which is the correct layer for a package of this shape but the highest-coupling layer in a Laravel application. It is a viable fit only for teams already comfortable with model-level side effects on read. It is a poor fit for codebases that treat Eloquent models as thin persistence objects, or that already have an equivalent derived-attribute mechanism (accessors, $appends, API resources, view models). Adoption is effectively a per-model, incremental decision rather than a platform-wide one — that is a favorable property and should drive how we scope a pilot.

Integration feasibility. Low friction on the happy path: composer require, publish config (if any), add a trait or scope to a small number of models. There is no infrastructure, queue, or datastore dependency implied. However, v1.0.1 is the first version where Laravel 10 executes correctly — v1.0.0 shipped with a hard failure (BadMethodCallException: Call to undefined method Builder::afterQuery()), meaning the package's stated compatibility surface was not actually validated at first release. Feasibility is therefore confirmed for "can be installed," unconfirmed for "behaves identically across our supported framework versions."

Technical risk. The dominant risk is version-dependent behavioral divergence, not installation failure. The fix is not a bug fix in the conventional sense — it is two different execution paths for the same feature: the afterQuery() builder hook on newer Laravel, and the model retrieved event as fallback on Laravel 10. These are not semantically equivalent. retrieved fires per model during hydration; afterQuery operates at query granularity. The practical consequences a TPM must anticipate:

• Flow fields may not be populated on models instantiated in memory (e.g. the return value of create() or save()), only on models re-fetched from the database — producing "works after refresh" bug reports.
• Per-model event dispatch introduces a scaling cliff on large result sets and in chunked/queued jobs where other packages or observers also listen on retrieved.
• Ordering relative to other retrieved listeners is unspecified; a competing observer could read partially-populated flow fields.

Secondary risk: reliance on a framework-internal builder method is a recurring maintenance tax. Any future Laravel change to afterQuery semantics reopens this class of defect.

Key questions for the maintainer / spike.

1. Do flow fields behave identically on create(), update(), firstOrCreate(), and refresh() across Laravel 10 vs 11/12, or is the fallback path only correct post-refetch?
2. Is the compatibility matrix in CI backed by an actual per-version assertion on flow-field output, or only by "the suite does not throw"?
3. What is the per-model cost of the retrieved fallback at scale (1k / 10k row result sets), and is there a documented bulk/bypass mode?
4. What is the package's supported-version policy, and is Laravel 10 a maintained target or a one-off accommodation?
5. Does the package write to the database, or is it strictly read-time derivation? This determines whether it belongs in our write path at all.

Integration Approach

Stack fit. Requires a Laravel application with standard Eloquent usage; the release notes confirm Laravel 10 is now supported, and the CI matrix work implies 11/12 are already targets. PHP version floor is not stated in the notes and must be read from composer.json before we commit — do not assume. The package is additive and stateless from an infrastructure standpoint, so it fits any hosting model (monolith, API service, queue worker) without platform work.

Migration path. Straightforward and reversible. v1.0.1 is a patch release over v1.0.0 with no breaking changes, no deprecations, no schema changes, and no public API changes — the afterQuery → retrieved fallback is internal. Two paths:

• Greenfield: adopt v1.0.1 directly, skip v1.0.0 entirely.
• Existing v1.0.0 adopters on Laravel 10: this is a required upgrade, not an optional one — v1.0.0 is non-functional there. Treat it as a defect remediation with a regression test, not a routine bump.

Compatibility. Pin to ^1.0.1 explicitly rather than ^1.0, since 1.0.0 is known-broken on Laravel 10 and a stale lockfile could resolve to it. Confirm our framework version actually appears in the package's CI matrix — the notes describe matrix plumbing improvements (Node 24 actions, --dev flags, COMPOSER_NO_AUDIT/COMPOSER_NO_BLOCKING) but do not enumerate the versions tested. Verify, don't infer.

Sequencing.

1. Read composer.json and the package source (30 min) — confirm PHP/Laravel constraints, confirm whether flow fields are read-only, and inspect the retrieved fallback to understand where it attaches.
2. Define our supported-version contract — decide whether we support Laravel 10 at all. If we do not, the fallback path is dead code for us and the risk profile drops materially.
3. Pilot on one low-traffic model that already exposes derived/API-facing attributes, behind a feature flag if the package supports it.
4. Write parity tests covering create-then-read, direct-fetch, and bulk-fetch, executed against every Laravel version we claim to support. This is the deliverable that closes the semantic-divergence risk.
5. Measure query counts and hydration time on a representative large result set before expanding beyond the pilot.
6. Expand model-by-model, or abandon after the pilot — the per-model adoption shape makes exit cheap.

Operational Impact

Maintenance. Low ongoing effort, but non-zero and concentrated in a single failure class: framework upgrades. The package sits directly on Eloquent's hydration path, so every Laravel major is a potential regression point, and the maintainer's demonstrated pattern is to patch compatibility reactively (v1.0.1 exists precisely because v1.0.0 did not work on Laravel 10). Budget a compatibility check into every framework upgrade runbook — specifically, re-run the flow-field parity tests before and after any Laravel bump. Dependency ownership should sit with the team that owns the models, not a central platform group, since adoption is per-model.

Support. Support surface is internal developers, not end users, and the questions will be of the form "why is this field null on a freshly created record?" — which is the predictable artifact of the dual execution path. Mitigate with a short internal note documenting that flow fields are populated on retrieval and may require a refetch on Laravel 10. The CI changes in this release (Node 24 action upgrades, --dev in matrix installs, audit/blocking flags) are housekeeping that improves upstream reliability but deliver no operational capability to us; do not read them as maturity signals. Assess maintainer responsiveness separately — a single-maintainer package on the Eloquent internals is a concentration risk worth naming in the vendor register.

Scaling. Primary concern is the retrieved fallback on Laravel 10, which dispatches per hydrated model. At moderate result-set sizes this is likely acceptable; on reporting queries, exports, or chunked batch jobs returning tens of thousands of rows it can become a measurable cost, and it compounds with any other retrieved observers in the application. Mitigations: scope the trait only to models that need it, prefer the newer-Laravel path where available, and avoid calling withFlowFields in bulk/export contexts unless a bypass exists. Confirm with measurement in step 5 rather than assuming.

Failure modes. Ranked by likelihood:

1. Silent nulls on freshly created models (Laravel 10 fallback) — highest likelihood, degrades gracefully but produces confusing downstream logic and support load.
2. Observer ordering conflicts — another retrieved listener reads flow fields before they are populated; surfaces as intermittent, hard-to-reproduce wrong values.
3. Hard failure on framework upgrade — BadMethodCallException-class errors if the underlying builder API shifts again; caught immediately at deploy, low blast radius if the pilot is scoped tightly.
4. Performance degradation in bulk paths — gradual, detectable via query/hydration metrics, easily missed without instrumentation.

None of these are data-corruption or availability risks given the package appears to be read-time derivation. That materially lowers the severity ceiling and supports a pilot-first, expand-later posture rather than a formal architecture review gate.

Ramp-up. Half a day for an experienced Laravel engineer to read the source, wire up one model, and write the parity tests. Effectively zero for the wider team, since the package is invisible to anyone not touching adopted models. The real ramp-up cost is organizational: establishing the convention about which models are allowed to carry flow fields, so adoption does not sprawl into a de facto framework dependency that is hard to unwind later.

Recommendation. Proceed to a scoped pilot on v1.0.1 pinned at ^1.0.1. Gate expansion on parity tests passing across our supported Laravel versions and on measured hydration cost in bulk paths. Do not adopt on Laravel 10 without the create-then-read parity test, and do not treat this release's CI housekeeping as evidence of compatibility coverage — verify the matrix contents directly.