Respect\Relational Abstract Collections

[alganet]

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

[alganet]

I've implemented Filtered, Mixed and Typed collections. Essentially:

<?php

use Respect\Data\Collections as c;

$mapper->postsTitles = c\Filtered::by('title')->post();
$mapper->postsTitles->fetchAll(); //Hydrates Post entities only by title and id

$mapper->postsTitles = c\Filtered::by('title', 'text')->post();
$mapper->postsTitles->fetchAll(); //Hydrates Post entities only by title, text and id

$mapper->allUsers = c\Mixed::with('premium_users')->users();
$mapper->allUsers->fetchAll(); //Bring User entities mixed with premium_user table data, multi table inheritance

$mapper->allUsers = c\Mixed::with('premium_users', 'blocked_users')->users();
$mapper->allUsers->fetchAll(); //Bring User entities mixed with premium_users and blocked_useers tables, multi table inheritance

$mapper->issues = c\Typed::with('category')->issues();
$mapper->issues->fetchAll(); //Uses column category to find out the issue entity, single table inheritance

//Assigned collections can be reused in the chain
$mapper->comments->postsTitles(); //Bring all comments but only titles from posts

It's all sort of tested. I didn't finished persisting back these hydrated collections in the database.

[nickl-]

@alganet Somehow this slipped past me, not to get distracted and continue going through all notifications, I will mark this to return to it and give it some proper attention..

Smells good so far =)

[williamespindola]

@alganet this is related to what we talked at Intercon?

[alganet]

@williamespindola yeah it is!