aura/marshal

The Aura Marshal package is a data-object marshalling tool; it takes results from data sources and marshals those result sets into domain model objects of your own design, preserving data relationships along the way.

Aura Marshal

marshal (verb): to arrange in proper order; set out in an orderly manner; arrange clearly: to marshal facts; to marshal one's arguments. -- dictionary.com, _(*1)

The Aura Marshal package is a data-object marshalling tool. It takes results from data sources and marshals those result sets into domain model objects of your own design, preserving data relationships along the way., _(*2)

Foreword

Installation

This library requires PHP 7.2 or later; we recommend using the latest available version of PHP as a matter of principle. It has no userland dependencies., _(*3)

It is installable and autoloadable via Composer as aura/marshal., _(*4)

Alternatively, download a release or clone this repository, then require or include its autoload.php file., _(*5)

Quality

, _(*6)

To run the unit tests at the command line, issue composer install and then ./vendor/bin/phpunit at the package root. This requires Composer to be available as composer., _(*7)

This library attempts to comply with PSR-1, PSR-2, and PSR-4. If you notice compliance oversights, please send a patch via pull request., _(*8)

Community

To ask questions, provide feedback, or otherwise communicate with the Aura community, please join our Google Group, follow @auraphp on Twitter, or chat with us on #auraphp on Freenode., _(*9)

Overview

You can use any database access layer you like with Aura Marshal, such as ..., _(*10)

• mysql or the other PHP database function sets
• PDO
• Aura SQL
• Solar_Sql_Adapter
• Zend_Db_Adapter
• Doctrine2 DBAL

... or anything else. (In theory, you should be able to retrieve data from XML, CSV, Mongo, or anything else, and load it into Aura Marshal.), _(*11)

With Aura Marshal, you use the data retrieval tools of your choice and write your own queries to retrieve data from a data source. You then load that result data into an entity type object, and it creates entity and collection objects for you based on a mapping scheme you define for it., _(*12)

Aura Marshal makes it easy to avoid the N+1 problem when working with a domain model. It also uses an identity map (per type) to avoid retaining multiple copies of the same object., _(*13)

It is important to remember that Aura Marshal, despite resembling an ORM in many ways, it not an ORM proper:, _(*14)

• it does not have a query-building facility
• it will not issue queries on its own
• it will not handle persistence for you
• it will not lazy-load results from a data source
• it will not read metadata or schemas from the datasource

Those things are outside the scope of the Aura Marshal package. Their absence does provide a great amount of flexibility for power users who write their own hand-tuned SQL and need a way to marshal their result sets into a domain model, especially in legacy codebases., _(*15)

Aura Marshal works by using Type objects (which define the entity types in the domain model). Each Type has a definition indicating its identity field, how to build entities and collections, and the relationships to other Type objects. The Type objects are accessed through a type Manager. You load data into each Type in the Manager, then you retrieve entities and collections from each Type., _(*16)

Documentation

This package is fully documented here., _(*17)