Flat Mapper Bundle Laravel Package

Technical Evaluation

Architecture fit. Release 2.4.0 adds YAML mapping to Pixelshaped/flat-mapper-bundle via PR #28. First and most important architectural note: despite the framing as a "Laravel/PHP package," this is a Symfony bundle, not a Laravel package. It integrates through Symfony's bundle registration, DI container, and configuration system. It will not drop into a Laravel service provider cleanly and should be treated as a Symfony-only dependency until proven otherwise. For a Symfony-based estate, the fit is good: mapping is the kind of cross-cutting concern that benefits from being declared as configuration rather than scattered as PHP attributes, and YAML is the native idiom in Symfony projects already.

The substantive change is small and additive: a new mapping-definition format alongside whatever was previously supported (annotations/attributes or PHP config). That is a configuration-surface expansion, not a new runtime engine. The mapping semantics should be identical, which keeps the blast radius low but also means the value is ergonomic (declarative mappings in config, reviewable in diffs, editable by non-PHP staff) rather than functional.

Integration feasibility. Low-to-moderate. It is a minor version bump (2.3.1 → 2.4.0) with one contributor PR and no deprecation or breaking-change notes in the changelog. Assuming standard semantic versioning, existing PHP-attribute mappings continue to work untouched, so adoption is opt-in per mapping. The real work is not code — it is deciding where YAML mapping files live, how they are discovered, how they are validated in CI, and whether the app's config cache correctly invalidates when they change. Those are process and tooling questions that the release notes do not answer.

Technical risk. Predominantly low, with three caveats:

1. Thin release documentation. "Add yaml mapping" is the entire note. There is no documented YAML schema, no example, no statement of feature parity with the existing mapping format, and no guidance on precedence when both styles are present. We would be reverse-engineering the schema from the PR.
2. YAML as a new runtime input. YAML introduces a class of failure that PHP attributes cannot produce: malformed files, tab characters, duplicate keys, anchor/alias surprises, and implicit type coercion (e.g. yes → boolean, unquoted numerics in identifiers). Symfony's YAML parser is safe by default, but schema drift is a genuine ongoing cost.
3. Cache and warmup interaction. Mappings resolved from files can be caught out by container/config caching in ways attribute-based mappings are not. This needs verification before rollout, not after.

Key questions. What is the YAML schema, and is it expressive enough for every mapping pattern currently in use (nested, collections, custom transformers, conditional mapping)? Is there a documented precedence rule when YAML and attribute mappings target the same class? Are YAML files compiled into the container cache, and what invalidates that cache? Is there validation tooling (a lint command, a JSON Schema) or must we build our own? Does 2.4.0 have any transitive dependency changes pulled in by the PR? Who maintains this bundle — bus factor and release cadence matter more than usual for a one-PR release. And, critically: is there any Laravel path at all, or is this a hard Symfony-only adoption?

Integration Approach

Stack fit. Only viable if the target application is Symfony (5.4/6.x/7.x — confirm the supported matrix, since the notes don't state it). For a Laravel codebase this is a non-starter without an adapter layer, and I would not fund that adapter for a feature this small. Where the stack is Symfony, YAML mapping fits naturally alongside existing config/packages/*.yaml conventions and will feel familiar to the team.

Migration path. Strictly incremental and reversible. Recommended path: leave all existing mappings as-is; pick one low-risk, well-understood DTO mapping and re-express it in YAML as a pilot; verify byte-identical output against the existing implementation with a characterization test; then expand. Do not run a bulk conversion. There is no forced migration here — 2.4.0 is additive, so the correct posture is "adopt where it demonstrably helps," which likely means mappings that change often or that product/ops staff need to read and edit.

Compatibility. Confirm three things before writing any YAML: the minimum PHP version, the supported Symfony versions, and whether the bundle's extension needs explicit registration/configuration to enable YAML discovery. Since the changelog says nothing, treat compatibility as unverified until a spike confirms it in our pinned environment. Also confirm 2.3.1 → 2.4.0 is clean on our lockfile — a minor bump can still shift transitive constraints.

Sequencing.

1. Spike (1–2 days): read PR #28, extract the schema, get one YAML mapping working in a scratch branch.
2. Characterization test: assert YAML- and attribute-defined mappings produce identical results for the same DTO.
3. Standards decision: agree file location, naming, and whether mixed-mode is permitted. Write it down — mixed-mode ambiguity is how this becomes unmaintainable.
4. CI gate: add YAML lint + bundle validation to the pipeline before the first YAML mapping merges to main.
5. Pilot in production on one non-critical path; watch for cache-warmup issues across deploys.
6. Document and widen. Only then consider converting existing mappings, and only where there is a clear readability or ownership win.

Operational Impact

Maintenance. Net neutral-to-slightly-negative in the near term. The bundle itself is small and the change is small, but YAML mappings add a second source of truth for mapping behaviour. Two formats means contributors must know which one applies to the file they are editing, and reviewers must check both. Mitigate with a hard rule: a given DTO is defined in exactly one format, enforced in review and, if possible, by a CI check.

Support. Support burden shifts rather than shrinks. Fewer "how do I express this in attributes" questions, more "why is my YAML not being picked up" questions — discovery paths, cache state, and indentation are the usual suspects. The absence of upstream documentation means the first-line responder is our own README, so writing it is not optional; it is the deliverable that makes this release usable.

Scaling. YAML mappings scale well organisationally (readable, diffable, editable by people who don't write PHP) and adequately technically. Watch two things as the count grows: parse/resolve cost at container build time, which is real but almost certainly negligible at hundreds of mappings, and cognitive scale — hundreds of YAML files with no schema validation becomes a swamp. The CI lint gate from the integration plan is what keeps this linear.

Failure modes. Ranked by likelihood and impact:

• Silent misconfiguration (highest concern): a mapping that parses but doesn't mean what the author intended — implicit YAML type coercion turning an identifier into a boolean or integer. Mitigate with schema validation and strict typing in tests.
• Mapping not discovered: file in the wrong path, wrong extension, or not registered with the bundle. Fails loudly at first use, usually in a test — acceptable, provided the pilot is covered by tests.
• Stale cache after deploy: the classic Symfony operational hazard. Verify cache warmup handles YAML changes; make cache:clear part of the deploy as a belt-and-braces measure.
• Malformed YAML breaks container compilation: a broken file can take down the whole app rather than one mapping. This is the argument for the CI gate, not an argument against adoption.
• Upstream abandonment: a one-maintainer bundle with a terse changelog is a real long-term risk. YAML mapping is more portable than attribute-based mapping if we ever need to migrate off the bundle, which is a mild point in its favour.

Ramp-up. Low for anyone already comfortable with Symfony config — YAML is the format the team already reads daily. The ramp-up cost is not learning YAML; it is the half-day of reverse-engineering the schema from PR #28 and the ongoing cost of owning documentation the upstream project hasn't written. Budget roughly one engineer-week end-to-end for spike, pilot, CI gate, and docs. That is proportionate for an ergonomic improvement, and disproportionate if we attempt a wholesale conversion — which is why the recommendation is deliberate, incremental adoption rather than a migration.