Static Data Importer Bundle Laravel Package

Getting Started

• Install the package with Composer and confirm Laravel auto-discovery registers its service provider. If the package ships a config file, publish it before relying on relational normalization defaults.
• Look first at the v1.0.6 changelog entry, the new Entity Normalizer class/contract, the package config, and any tests covering relationships. The release note is narrow: the meaningful change is relational value normalization, so verify how relations are selected, nested, and serialized.
• First use case: normalize a single Eloquent model with one relation — for example, an Order with its items or a User with a profile — and inspect the output shape before wiring it into an API response or audit payload.
• Confirm whether the normalizer expects relation names, relation paths, nested normalizer classes, or a configuration map. Start with the smallest possible relation graph and expand only after the output is predictable.

Implementation Patterns

• Use one normalizer per entity or aggregate and compose relation normalizers rather than building large ad-hoc arrays in controllers. This keeps relational output consistent across API responses, events, and logs.
• Treat the normalizer as the boundary between Eloquent models and transport/storage payloads. Return normalized arrays from your own action or resource layer instead of leaking models directly.
• For API responses, combine the normalizer with Laravel JsonResource or Responsable objects. Prefer explicit relation includes so endpoints control payload size and avoid accidental graph expansion.
• For audit logs and domain events, snapshot the normalized entity plus selected relations at the time of the event. This is where relational normalization is most useful, but it also makes payload size and schema stability important.
• Eager load every relation the normalizer will touch. If the package supports selective relation includes, pass only the relations needed by the current use case.
• For large relation sets, paginate or limit hasMany relations before normalization. Do not normalize an unbounded collection into a single response or event payload.
• Test normalizers with factories that create real relation states — missing relations, empty collections, nested relations, and circular back-references — not just top-level model attributes.

Gotchas and Tips

• Watch for N+1 queries. Relational normalization often triggers lazy loading if relations were not eager loaded; enable query logging in development and verify the relation graph is loaded up front.
• Circular relations are the main failure mode. Parent/child or bidirectional relations can recurse indefinitely; use a depth limit, exclude back-references, or normalize only the direction needed by the consumer.
• Check how the normalizer handles $hidden, $visible, casts, dates, enums, and appended attributes. Relational normalization may bypass or duplicate Eloquent serialization behavior, so assert the output shape in tests.
• Relation names versus method names can differ. Use the exact names the normalizer expects, and test nested relation paths rather than assuming dot notation works everywhere.
• If relation behavior is config-driven, run php artisan config:cache after changes and include the package config in deployment checks. Stale config is a common source of “it works locally” failures.
• Extension points to inspect: custom normalizer registration, normalizer contracts/interfaces, macros, and events around normalization. Prefer extending through the package’s documented contract rather than subclassing internals.
• Pin the package version and review output diffs when upgrading. v1.0.6 adds relational normalization, so existing payloads may change if relations were previously ignored or serialized differently; cover critical normalized payloads with snapshot or shape assertions.