Respect\Relational Abstract Collections

Respect\Relational Abstract Collections

Respect\Relational uses Respect\Data collections to express two things:

1 - How tables are related

This is done by the very nature of Collection compositing:

  <?php
  $comments = new Collection('comments');
  $comments->stack($posts   = new Collection('posts');
  $comments->stack($authors = new Collection('authors');
  $authors->setCondition(7);

This is telling that each comment has a post and each post has an author. Also tells that authors have a condition of being 7, which Relational abstracts as the primary key identified by the chosen SQL style (for example, the default is comments.id).

For luck, this building, stacking and configuring can be more straightforward by using the magic layer that produces the same object as the previous sample:

  <?php
  $comments = Collection::comments()->posts()->authors[7];

1 - How tables are hydrated

Since the collection knows who is inside who, they have all necessary information to inform Relational about which objects goes inside another objects. The above operation used in Relational could bring a result similar to:

  <?php
  array(
     (object) array(
         'id' => 1,
         'text' => 'Some Comment',
         'post_id' => (object) array (
             'id' => 1,
             'title' => 'Some Post',
             'author' => (object) array(
                  'id' => 7,
                  'name' => 'Gaigalas'
             )
         )
    )
  )

This has some limitations. Collections can't filter columns nor Relational can hydrate results differently.

Proposal

The idea is now is to separate how Collections handle hydration and relation by abstracting them into separate strategies:

<?php
$mapper->serverStatus = new DictionaryCollection('servers', 'status'); //Servers table, status column.
$mapper->serverStatus->fetchAll(); //Array key/pair using PK and status column

$mapper->dictionary('server', 'status')->fetchAll(); //Same as above

Some other samples:

Named Collections

Normal hydration brings a numeric array of hydrated objects. Named Collections brings an array with keys as primary keys:

<?php
$mapper->onlineUsersByPk = new NamedCollection('users');
$mapper->onlineUsersByPk->setCondition(array('online' => 1));

$mapper->named('users', array('online' => 1)); //Same as above

Mixed Collection Inheritance (Joined Table Inheritance)

Uses two tables to form a result.

<?php
$mapper->premiumAndNormalUsers = new MixedCollection('users', 'user_type');

$mapper->mixed('users', 'premium_users')->fetchAll(); //Same as above

Typed Collections (Single Table Inheritance)

Uses a discriminator column as the collection name.

<?php 
$mapper->bugs = new TypedCollection('bugs', 'bug_type'); //Single Table Inheritance

$mapper->typed('bugs', 'bug_type')->fetchAll(); //Same as above

Filtered Collections (Specific SELECT conditions)

Brings only specified columns. Two notations possible:

• name to bring all columns from the collection matching this name
• name.column to bring a specific column

Note that the identifier for a collection will always be brought in normal collections. Named and dictionary collections can override this behavior.

<?php 
$mapper->posts = new FilteredCollection('posts', 'authors.name');
$mapper->comments = Collection::comments(array('moderated'=>1))
                              ->posts()->authors();

class_alias('FilteredCollection', 'SelectCollection');

$mapper->select('posts', 'authors.name')
       ->comments(array('moderated'=>1))
       ->posts
       ->authors
       ->fetchAll(); //Same as above

This all came into mind when I was working on Template and though that we could be more open on how Relational brings it's results back, so we can change these results less when passing to another libraries =)

I would like some feedback on this before putting my hands to work!

@augustohp @nickl- @henriquemoody @wesleyvicthor @iannsp

Start by reviewing the existing Collection composition, relation handling, and hydration behavior described in the issue, then compare the proposed DictionaryCollection, NamedCollection, MixedCollection, TypedCollection, and FilteredCollection strategies. Done would require an agreed design and implementation that separates relation handling from hydration while supporting the illustrated collection forms.