RelatedTable Feature

[tyrsson]

This thread is for brainstorming around a RelatedTable feature. I would really like to get the ideas of some others before posting my own thoughts and ideas on this topic.

[simon-mundy]

Hey @tyrsson I can post my current methodology.

I use a Table and Entity model to handle tables/rows. In an abstracted Entity model, I'll use something like the following (this example describes a 'Resource' which can be linked to many graphic 'Asset' entities):-

class ResourceEntity extends AbstractEntity
{
    protected array $primaryKeys = [
        'id'
    ];

    protected array $columns = [
        'id',
        'title',
        'description',
        'url',
        'created',
        'updated',
        'status',
    ];

    protected array $relations = [
        'image'      => [ // aliased field name for relation
            'column' => ['resource_id'], // the primary column to match against
            'table'  => [ // related table information
                'class'  => AssetRepository::class, // related Table Model
                'column' => ['asset_id'] // related Primary Key
            ],
            'via'    => [
                'table' => 'lookup_resource_asset' // JOIN table
                'relationColumn' => 'resource_id',
                'JoinColumn' => 'resource_id',
            ],
            'order'  => [
                'lookup_resource_asset.sequence ASC' // Allows auto-sorting of returned rows
            ],
            'where'  => [
                'resource.resource_type_id' => 'feature' // Add additional conditions to the lookup query
            ]
        ]
    ];

I use a custom Hydrator which is linked to a Row Factory that passes the relation data to the Hydrator and allows on-the-fly lookups on the Row Entity.

E.g. $resourceEntity->image would be either NULL or a ResultSet of related Row Entities of the Asset model.

I can provide a more detailed setup, including base Abstract Rows, Tables and Hydrators if you like the sound of this approach.

I decided not to use an ActiveRecord pattern for this because of the hassle of connecting/reconnecting the DB adapter if a row was serialized. However I guess it would be straightforward enough to add this feature if needed using some of the existing Laminas DB Row FeatureSet code.

[tyrsson]

Very similar to code I have ended up with in the testing I have been doing. I am trying to stay very far away from active record. With that said I have had a lot of success with returning Rowgateway instances as Repository prototype entities. Which I usually model as extensions of Laminas\Stdlib\ArrayObject.

The primary reason I asked those here to post up their ideas is because what I am really looking into at the moment is how we build a robust mechanism for defining the relationships between the Repository/Entity pairs and have the cli tooling write that on the fly as the pairs are generated.

One of implementations that worked out very well (just for testing). I'll just post the highlights.
The RelatedTable Feature you will see references too can be found here:
https://github.com/axleus/axleus-db/tree/master/src/Feature/RelatedTable

Really the most interesting part I suppose would just be the factory for the Repository. I just feel its overly complicated.

<?php

declare(strict_types=1);

namespace Cm\Storage;

use Axleus\Db;
use Laminas\Db\Adapter\AdapterInterface;
use Laminas\Db\TableGateway\Feature\FeatureSet;
use Laminas\Db\TableGateway\Feature\RowGatewayFeature;
use Psr\Container\ContainerInterface;

final class PageRepositoryFactory
{
    public function __invoke(ContainerInterface $container): PageRepository
    {
        $adapter = $container->get(AdapterInterface::class);
        $ref = new Db\Feature\RelatedTable\RelatedTableReference();
        $ref->addReference([
            'dependent_table' => $container->get(PageDataRepository::class),
            'ref_type'        => Db\Feature\RelatedTable\AbstractTableReference::REF_DEPENDENT,
            'column_map'      => ['local' => 'id', 'fk' => 'pageId'],
        ]);
        $rowGatewayPrototype = new PageEntity('id', 'page', $adapter);
        $rowGatewayPrototype->setReferenceProvider($ref);
        return new PageRepository(
            new Db\TableGateway(
                'page',
                $adapter,
                new FeatureSet([
                    new Db\Feature\ScrollablePdoResultFeature(),
                    new RowGatewayFeature($rowGatewayPrototype)
                ]),
            )
        );
    }
}

[tyrsson]

@simon-mundy we really need to plan and create a proper RFC for this feature and a project plan for accomplishing it. I would very much like to see it make 3.0.0 but we all need to come to a consensus if we are going to include "new features" in the 3.0.0 or cut it off at deps, ci/cd upgrades, language features and satellite packages. Its already a huge amount of work without new features in 3.0. I just do not want to get bogged down in a really large feature when folks could already be making the move to 3.0. User will be dependent on our release if they are to continue using stuff like the related validators etc once they need to update SM to v4.