Nova Collection Field Laravel Package

Getting Started

• Install the package via Composer and let Laravel’s package discovery register the service provider; there is no config file to publish until you need to override defaults.
• First place to look is the decorator classes that wrap your form data objects. The package’s core value is mapping raw request arrays onto typed objects, so read those before touching anything else.
• Start with a single flat form: create one form-data class, populate it from $request->validated(), and pass it into your controller/action. Confirm the mapping works before introducing nesting.
• If you are on 0.3.0 or later, jump straight to the validation entry point rather than hand-rolling Validator::make() calls around the object — that is the newly supported path and the intended day-to-day workflow.

Implementation Patterns

• Request → decorated object → action. Keep controllers thin: validate, decorate the input into your form-data object, hand the object to a service or job. This keeps HTTP concerns out of your domain layer.
• Validation first, decoration second. With 0.3.0, validation is a first-class concern. Resolve rules from the form-data class, validate the raw payload, then feed the validated array into the decorator so unvalidated keys never reach your object.
• Nested forms as composition, not inheritance. Model child forms as their own form-data classes and let the parent decorator build them. After the 0.3.0 refactor, re-check how child instances are constructed — the wiring changed, so copy the pattern from the package’s own tests rather than from older blog posts.
• Reusable rule sets. Put rule definitions alongside the form-data class so validation and decoration cannot drift apart. A single source of truth for “what this form accepts” pays off once you have several endpoints accepting the same payload.
• Collections of children. For repeatable sections (line items, addresses), decorate arrays of nested objects and validate each element with wildcard rules (items.*.sku). Assert the count and index alignment in a feature test — this is where nested decorators historically get subtle.
• Integrate at the FormRequest boundary when you already use FormRequests: keep authorization there, and delegate data shape and rules to the package so both paths stay consistent.
• Bind in the container if your form-data classes need collaborators; resolve them through the container rather than new-ing them inside decorators so tests can swap dependencies.

Gotchas and Tips

• 0.x API instability. A “refactor” of the nested decorator in a minor release is normal at this version. Pin the exact version in composer.json and read the diff, not just the changelog, before upgrading in production.
• Nested decorator behavior is the regression hotspot. The 0.3.0 refactor of nested form data is the most likely place for silently changed behavior: missing keys, null children, and empty arrays are the usual edge cases. Write tests for absent nested keys and for empty child collections explicitly.
• Validation coverage gaps. “Validation support” is new, so don’t assume every rule type or nested wildcard is handled. Verify that nullable, conditional rules (sometimes, required_if), and nested wildcards behave as expected on your Laravel version before standardising on it.
• Don’t bypass validation. It is tempting to decorate the raw request directly. Resist — decoration does not sanitise, and unvalidated mass-assignment into a typed object is how unexpected properties slip through.
• Debugging tip: dump the validated array and the decorated object side by side. When a value looks wrong downstream, this immediately tells you whether the problem is validation, mapping, or your domain code.
• Extension point: if the built-in decorators don’t fit, subclass or compose your own decorator rather than modifying vendor code — at 0.x, forks diverge fast and you will want a clean upgrade path.
• Pin Laravel/PHP constraints in CI. Small packages at this stage often support a narrow range, and a framework bump can break reflection-based property mapping without an obvious error message.