Laravel Flowfield Laravel Package

Getting Started

• Install: composer require schtzie/laravel-flowfield. The package auto-discovers its service provider; publish any config with php artisan vendor:publish --tag=flowfield-config if the README lists one.
• Where to look first: README.md for the field-definition API, then src/ for the base trait/concern and src/Scopes/ (that's where scopeWithFlowFields lives — the method named in the v1.0.1 changelog). Check tests/ for the canonical usage examples before reading the source.
• Confirm your runtime first: v1.0.1 explicitly targets Laravel 10.x compatibility via a fallback path, while Laravel 11/12 use the native Builder::afterQuery() hook. Verify your framework version so you know which code path your app exercises.
• First use case: add the package's trait/concern to a model, declare one derived field (e.g. a concatenated display name or a computed status label), then call the scope on a query: User::query()->withFlowFields()->get(). Confirm the attribute appears in toArray() output, which is the fastest sanity check that hydration wiring works.
• Baseline upgrade check: run php artisan test and any feature tests that serialize models to JSON immediately after installing, so you can distinguish package behaviour from your own accessor logic.

Implementation Patterns

• Query-scoped computation: treat withFlowFields as the entry point for "add computed columns to this result set only." Prefer it over $appends for fields that are expensive or only needed on specific endpoints — appending globally pays the cost on every serialization.
• Endpoint-level opt-in: apply the scope in a controller/query-builder/API resource rather than in a global scope, so list endpoints and detail endpoints can request different field sets. This keeps payloads intentional and makes caching predictable.
• Model-level declaration, query-level activation: define the field logic once on the model (closures/accessors/config array per the README) and activate per query. This avoids duplicating computation logic across controllers.
• Combine with eager loading deliberately: if a flow field reads a relation, eager-load that relation in the same query (->with('profile')->withFlowFields()). Ordering matters less than coverage — a missing eager load turns a computed field into a silent N+1.
• Pagination and resources: because fields are hydrated onto models, they flow naturally into JsonResource/toArray(). If you use API resources with explicit $this->only([...]) mappings, add the new keys there or they'll be dropped even though hydration succeeded.
• Testing pattern: assert on the serialized shape (assertJsonPath('data.0.full_name', ...)) rather than on the model property alone — that catches both hydration failures and resource-layer omissions. Add one test that runs the scope over a paginated result and one over ->find().
• Matrix awareness in CI: if your app spans multiple Laravel versions (common in package/app monorepos), run the flow-field tests against each supported version. v1.0.1's fallback means behaviour differs by framework version, so a green Laravel 11 build doesn't prove Laravel 10 works.

Gotchas and Tips

• Laravel 10 uses the retrieved event fallback: without Builder::afterQuery(), the package attaches flow fields per-model on retrieval. This is functionally correct but fires an event per hydrated model — expect measurably more overhead on large result sets than the Laravel 11+ path. Benchmark any endpoint returning thousands of rows, and prefer chunked/cursor iteration over a single giant get().
• retrieved listeners are global: if your app (or another package) already listens to retrieved, ordering and side effects can interact. Keep your own retrieved handlers idempotent and free of writes; avoid assuming flow fields are populated at the moment your listener runs.
• Serialization surprises: computed fields can leak into logs, queue payloads, and cache entries if you toArray() broadly. Use makeHidden() or explicit resource mappings on models that get serialized for non-API purposes.
• Debugging a missing field: check in this order — (1) scope actually applied to the builder, (2) trait present on the model, (3) field name registered in config/declaration, (4) resource layer not filtering it out, (5) on Laravel 10, whether a retrieved listener or withoutEvents() call suppressed hydration.
• withoutEvents() and Model::withoutEvents() will break the Laravel 10 path: since the fallback depends on the retrieved event, silencing model events silently drops your flow fields. Same risk with saveQuietly-style helpers around retrieval and with test setups that disable events globally.
• Aggregates and raw queries bypass hydration: ->count(), ->sum(), ->pluck(), and DB::table() calls never hydrate models, so flow fields won't exist. Don't design a code path that expects them there.
• Upgrade hygiene: pin the package version in composer.json and read the changelog on each bump — the Laravel 10 fallback was added reactively, which suggests the framework-support matrix is still settling. Treat minor bumps as worth a test run rather than a blind composer update.
• CI notes are for the package, not you: the Node 24/action-version and COMPOSER_NO_AUDIT changes in v1.0.1 affect the package's own pipeline. They're a signal that maintainer CI is actively tuned, but they require no action in your application.