Shift to Entity Focus

The decision has been made to change directions in the development of phpDataMapper and go with a more Entity-focused development approach. This will require significant non-backwards compatible changes to the codebase. As a result, the phpDataMapper project has been forked and renamed to “Spot”.

An Entity-based approach makes more sense for object-oriented code styles and for the ability to better support Document databases like MongoDB where multiple Entity types can be nested and combined into a single document. This approach also make more sense in general, because the code objects you work with and the data field definitions will now be in one place on the Entity instead of split across a Mapper and more generic Entity like the previous phpDataMapper code.

Requirements

New code and/or functional pieces that will have to be developed or significantly altered.

Entities

Field definitions will be moved to entities as public object properties (instead of the Mapper), and will be defined using the same native PHP array notation that is currently used in phpDataMapper. Entities will not have to extend a base class, but may choose to do so to gain extra functionality.

Config

A new “Config” will be created to manage named adapter connections for the user. This is needed so that an adapter name can be (optionally) defined on the Entity object that will tell it which connection to use (in the case of multiple database connections). This will enable data relations across connection types, like business or article records in MySQL that have related comments and ratings stored in MongoDB. Some exciting possibilities here.

Config setup:

$cfg = new Spot_Config();
$adapter = $cfg->addConnection('test_mysql', 'mysql://test:password@localhost/test');

Entity Manager

A new “Entity Manager” will be created that will store and track existing entity objects. It will also store meta-information on entity types, such as defined fields and entity relationships. Reflection will be used to get field definitions from entity classes and will be compared against any saved entity to determine which fields have data to save and/or update. Tracking will consist of caching entities that have been results from previous finders. The cache will provide a way to clear its entire contents and remove a single entity. This should easily provide support for not just rows modified through the finders and setters, but also on queries run directly by providing the ability to add an entity or set of entities to the cache.

Generic Mapper

A new “Generic Mapper” will be created that will be a the standard way for saving, updating, and finding entities. Insert, update, and save methods will accept an entity object as a first parameter, or an entity class name as a first parameter and an array of data as a second parameter.

Mapper object:

$mapper = new Spot_Mapper($cfg);

Entity object:

$post = new Post();
$post->title = "My new Blog Post";
$mapper->save($post);

Class name and data array:

$mapper->save('Post', array('title' => "My new Blog Post"));

Finders will require a class name first, and will keep the same finder syntax that already exists:

// ALL published blog posts (Collection of Post entities)
$posts = $mapper->all('Post', array('status' => "published"));

// FIRST published blog post (single Post entity)
$post = $mapper->first('Post', array('status' => "published"));

Single entity objects:

// New Post entity instance
$post = $mapper->get('Post');

// Post entity with primary key value of '42'
$post = $mapper->get('Post', 42);