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.
Installs: 131 001
Dependents: 1
Suggesters: 0
Security: 0
Stars: 116
Watchers: 16
Forks: 18
Open Issues: 0
Type:aura-package
Requires
- php: ^7.2 || ^8.0
Requires (Dev)
- yoast/phpunit-polyfills: ^1.0.0
README
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
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.
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.
It is installable and autoloadable via Composer as aura/marshal.
Alternatively, download a release or clone this repository, then require or include its autoload.php file.
Quality
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
.
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.
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.
Overview
You can use any database access layer you like with Aura Marshal, such as ...
mysql
or the other PHP database function setsPDO
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.)
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.
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.
It is important to remember that Aura Marshal, despite resembling an ORM in many ways, it not an ORM proper:
- 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.
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
.
Documentation
This package is fully documented here.