Flat Mapper Bundle Laravel Package

Product Decisions This Supports

• Field-mapping is now configuration, not code. 2.4.0 adds YAML mapping alongside the existing mapping approach, which turns "source column → target property" rules into declarative files. That is the single most reusable primitive in any integration product, and it unlocks decisions that were previously blocked on engineering time.
• Build vs. buy for ingestion work. If the roadmap contains CSV imports, SFTP/ERP feeds, legacy DB extracts, or spreadsheet uploads, you are otherwise paying for bespoke mapping classes on every new source. Adopting a mapper shifts that cost to config and keeps the domain model clean of fromArray() noise.
• Per-tenant / per-customer schema variation. YAML mapping makes it credible to ship customer-specific or partner-specific field mappings as data, versioned alongside the integration, rather than as forked PHP. This is a prerequisite for any "configure your own import" or onboarding-wizard feature.
• A path to a self-serve mapping UI. Declarative mapping files are the natural backing store for an admin screen where ops or implementation engineers map columns without a deploy. Not delivered by this release, but this release is what makes it a roadmap item rather than a rewrite.
• Where it does not move the needle: it is a flat-array→object mapper, so it does not help with nested JSON:API payloads, recursive object graphs, or hydration of rich aggregates. Do not let it be pitched as a general serializer replacement.

Ecosystem caveat to resolve before committing: this release is from pixelshaped/flat-mapper-bundle, which is a Symfony bundle, not a Laravel package. The YAML feature itself is container-agnostic, but the bundle's wiring is Symfony-specific. Treat Laravel adoption as "use the underlying mapper library directly, skip the bundle" and confirm that path with engineering before it lands on a roadmap.

When to Consider This Package

Consider it when:

• Your inputs are genuinely flat and tabular — SQL result rows, CSV/spreadsheet exports, fixed-width files, flat API responses — and your outputs are DTOs/value objects.
• You have, or expect, more than a handful of mappings. Below that threshold the dependency costs more than the boilerplate it saves.
• Mapping rules change on a cadence set by customers or partners rather than by your release train. This is exactly the case YAML is for.
• You want mappings reviewable in a diff, testable as fixtures, and editable by people who are not comfortable in PHP.
• You need mapping definitions to live outside the application container — shipped per-tenant, per-integration, or per-deployment.

Look elsewhere when:

• Sources are nested or irregular. Reach for Symfony Serializer, JMS Serializer, or a dedicated normalizer instead.
• You need validation, coercion policy, and error reporting as first-class concerns. A mapper maps; it does not validate. Plan to pair it with a validator and be explicit about which layer owns type coercion failures.
• The team is Laravel-first and unwilling to maintain non-Laravel wiring. The bundle will not slot in; only the core mapper will.
• Concentration risk matters to you. This is a small, single-maintainer package. For a revenue-critical ingestion path, that is a real assessment item — ask about release cadence, test coverage, and whether you are prepared to vendor or fork.
• The YAML layer's operational story is unproven for you: confirm how mapping files are discovered and whether parsed mappings are cached in production, what happens on a malformed mapping file, and whether invalid YAML fails at boot/deploy or at request time. A config layer that fails on the first customer import at 2am is worse than the PHP you replaced.

On this specific release: 2.4.0 is purely additive — new YAML mapping capability, no removals, no deprecations, no migration implied from 2.3.1. It is a low-risk upgrade and a meaningful capability gain, but it is also the first release of a new config surface, so pin the version and put a malformed-mapping test in your suite rather than assuming the error paths are mature.

How to Pitch It (Stakeholders)

For executives — one paragraph: We are standardising how we translate incoming customer and partner data into our own models. Today each new data source means bespoke engineering work; the 2.4.0 release of this library lets us express those translations as configuration files instead. The commercial effect is that a new customer integration or a changed partner file format becomes a configuration change reviewed like any other content, not a development project. It lowers the marginal cost of each new integration and shortens time-to-onboard, which is the metric that actually gates revenue in our segment. Cost of adoption is low and reversible: the release is additive, requires no migration, and the library is small enough to replace if it disappoints. The two risks to acknowledge are that it is maintained by a single author, and that it handles flat/tabular data only — it is an integration accelerator, not a platform bet.

For engineering — the ask:

1. Spike one real import end-to-end using YAML mapping; measure lines of code removed versus the current approach.
2. Confirm the framework story — the bundle is Symfony; we want the underlying mapper used directly in Laravel, with our own thin service-provider wrapper if needed.
3. Decide and document where the boundary sits: mapper owns shape translation, validator owns correctness. No implicit coercion.
4. Establish the operational contract for mapping files: location, caching, fail-fast validation in CI, and a clear error surface in production.
5. Pin to 2.4.x and wrap the dependency behind a small internal interface so a future swap is a contained change.

Recommendation: adopt behind an internal abstraction for flat-source ingestion, contingent on the spike and on a documented answer to the caching/fail-fast question. Do not adopt for nested payload hydration, and do not market this internally as a general serialization strategy.