[RFC]: Row Relations Feature for TableGateways

[simon-mundy]

Proposed Version

3.0.0

Basic Information

Create a new Feature for the Laminas\Db\TableGateway so that table relationships can be handled via rows.

Background

No response

Considerations

A light-weight solution aiming to provide limited functionality. Considerations will need to be given for issues like serialisation of rows, updating relation rows and perhaps tracking rows to prevent self-referential loops.

Proposal(s)

Row Relations

A new TableGateway Feature called RowRelationFeature which proposes to provide a lightweight ORM functionality and specify named lookups on table rows.

RowRelationInterface defines the methods loadRelation() and refreshRelation():

Laminas\Db\TableGateway\Feature;

interface RowRelationInterface
{
    public function loadRelation($relationName): ResultSetInterface;
}

Quick start

There would be several components required for this to work as intended:

RowRelationGateway
For convenience, a concrete class will be provided to implement both RowGatewayInterface and RowRelationInterface. However the implementation can be completely custom-configured by the developer if they wish.

RowRelationSpecification
An array-style config component for one or more named relations that provides the TableGateway with the necessary data in order to load rows on-demand. It is presumed a style of lazy-loading will take place so that these returned rows will not take up additional memory if not immediately required.

RowRelationFeature will be the configurable Feature added to a TableGateway. With this Feature, it will be possible to add one or more relations - either as a config to the constructor, or programmatically - before the TableGateway is used to retrieve rows. When a row is returned, the loadRelation($relationName) can be used to retrieve subsequent RowSets.

A basic use case:

$albumRepository = new TableGateway('album', $adapter);

$rowRelationFeature = new Feature\RowGatewayFeature([
    'album' => [
        'tableGateway' => $albumRepository,
        'column' => 'id',
        'referenceTable' => 'album',
        'referenceColumn' => 'id',
        'referenceLookup' => [
            'table' => 'lookup_artist_album',
            'column' => 'artist_id',
            'referenceColumn' => 'album_id',
        ],
        'condition' => [
            'album.status = "complete"'
        ]
    ]
])

$table   = new TableGateway('artist', $adapter, [$rowRelationFeature]);
$results = $table->select(['id' => 2]);

$artistRow = $results->current();
$albumRow  = $artistRow?->loadRelation('album')->current();

The array passed to the RowGatewayFeature constructor will be an array of RowRelationSpecification or an associative array which will be transformed to a RowRelationSpecification.

The meaning of the keys are:

column: (string|array) References the source table/row column(s)
referenceTable: (string|array|TableIdentifier) The reference table name
referenceColumn: (string|array) The reference column(s) - usually a primary key
referenceLookup: (array) A lookup table by which to reference relations
condition: (string|array) One or more conditions to apply to the reference table

Each $featureName must be unique (an exception will be thrown for duplicates when adding the specification).

Theory of operation

The RowRelationFeature will retrieve a RowSet using the existing functionality found in a TableGateway component. All that this feature will do is configure a prepared Select instance by which to return the results.

For the feature to be able to retrieve instances of the Table Gateway, it will be up to the developer to choose whether they wish to pass an instance of a Table Gateway to the RowRelationInstance to the tableGateway configuration, or a classname. In the latter situation, it would be necessary to pass a ServiceManager instance (or similar - perhaps a PluginManager?) for that to retrieve instances of a TableGatway.

It is then up to the developer to determine how they wish to use the loadRelation method within their row entities. They must, however, implement the RowRelationInterface.

Examples of a row:

class Album implements RowRelationInterface
{
    protected int $id;
    protected string $name;
    
    public function __construct(
        private $rowRelationManager
    ) {}
    
    public function getId(): int
    {
        return $this->id;
    }
    
    public function getName(): string
    {
        return $this->name;
    }
    
    public function loadRelation($relationName): ResultSetInterface
    {
        return $this->rowRelationManager->loadRelation($relationName);
    }
}

Appendix/Additional Info

No response