Download the PHP package pixelshaped/flat-mapper-bundle without Composer

Flat Mapper Bundle

Object mapper for denormalized data. Transform flat arrays (like database JOIN results) into nested, typed DTOs without the overhead of a full ORM.

The Problem

When you write efficient SQL JOINs, you get back flat, denormalized rows where parent data repeats across child records:

But you want clean, nested DTOs for your application:

FlatMapper does this transformation automatically, handling:

• Deduplication (one AuthorDTO per unique author despite repeated rows)
• Relationship reconstruction (grouping books under their authors)
• Nested object hierarchies (DTOs containing arrays of other DTOs)
• Type safety (strongly-typed DTOs with PHP attributes)

And it's fast. FlatMapper outperforms Doctrine entity hydration for read operations—even without N+1 queries. See benchmarks comparing FlatMapper to Doctrine entities, partial objects, and manual mapping.

Quick Start

Installation

Basic Usage

1. Define your DTOs with attributes:

2. Map your flat results:

That's it! You now have properly structured AuthorDTO objects with nested BookDTO arrays.

How It Works

Mapping Attributes

FlatMapper uses PHP attributes to define how flat data maps to your DTOs:

#[Identifier] - Required

Every DTO needs exactly one identifier to track unique instances:

#[Scalar("column_name")] - Optional

Maps a column from your result set to a scalar property. Omit if property names match column names:

#[ReferenceArray(NestedDTO::class)] - For nested objects

Creates an array of nested DTOs from the denormalized data:

#[ScalarArray("column_name")] - For arrays of scalars

Collects scalar values (like IDs) into an array:

#[NameTransformation] - Class-level attribute

Apply consistent naming rules to avoid repeating #[Scalar] on every property:

Individual #[Scalar] or #[Identifier] attributes override class-level transformations.

YAML Mappings

You can also define mappings in YAML (or any PHP array) and FlatMapper will parse them through the same mapping logic as attributes.

If both YAML and PHP attributes are defined for the same DTO/property attribute, PHP attributes take precedence.

YAML attribute arguments support:

• null for no argument (example: Identifier: ~)
• scalar value for one positional argument (example: Scalar: author_id)
• array for positional or named arguments (example: NameTransformation: { columnPrefix: 'book_', snakeCaseColumns: true })

Complete Examples

Nested DTOs Example

DTOs:

• AuthorDTO
• BookDTO

Input (denormalized):

Output (nested objects):

Scalar Arrays Example

DTO: ScalarArrayDTO

Input:

Output:

Framework Integration

Symfony

FlatMapper works out of the box with Symfony. Optionally configure for better performance:

Doctrine

Use with DQL queries:

Pagination

FlatMapper works with Doctrine's Paginator:

Standalone (No Framework)

Performance Optimization

Mapping Cache

Mapping metadata is created once per DTO and cached across requests when a cache service is configured. The first call analyzes your DTO attributes; subsequent calls use the cached mapping.

Pre-cache Mappings

Avoid creating mappings on hot paths by pre-caching during deployment:

This is optional. Mappings are created automatically when calling map() if not already cached.

Disable Validation in Production

Validation checks ensure your DTOs are configured correctly but add a little overhead. Disable in production:

Or in Symfony:

Why Not Just Use...?

Doctrine Entities

FlatMapper is significantly faster for read operations (see benchmarks):

• ~2x faster execution time
• 40-60% less memory usage
• No lazy-loading surprises

Using full Doctrine entities for reads also:

• Risks coupling your templates/views to your domain model
• Loads entity metadata and change tracking overhead
• Can trigger lazy-loading and N+1 queries (even with proper JOINs, proxies add overhead)

FlatMapper gives you lightweight, read-only DTOs optimized for queries.

Doctrine's NEW Operator

Doctrine can create DTOs directly in DQL:

Limitation: Only supports scalar properties. You can't have:

• Arrays of nested DTOs (#[ReferenceArray])
• Arrays of IDs or other scalar arrays (#[ScalarArray])
• Complex object graphs

FlatMapper solves this by handling denormalized data at any nesting level.

Other Object Mappers

Most object mappers transform nested arrays (like JSON) to objects:

• mark-gerarts/automapper-plus - Maps entities to DTOs (normalized data)
• jolicode/automapper - Maps normalized objects/arrays
• sunrise-php/hydrator - Maps normalized arrays to objects

These don't handle denormalized data where:

• Parent information repeats across multiple rows
• Relationships need to be reconstructed from flat results
• One row doesn't equal one object

PARTIAL Objects + Manual Mapping

You could use Doctrine's PARTIAL objects then map to DTOs, but:

• No indication whether an object is fully loaded
• Two-step process (entity hydration + DTO mapping)
• Higher complexity than direct flat-to-DTO mapping

Contributing

Found a bug or have a suggestion? Please open an issue or submit a pull request.

Know of an alternative that solves similar problems? Let us know—we'd love to reference it here!

License

This bundle is released under the MIT License. See the LICENSE file for details.