add output groups behavior

[mringler]

Allows declaring output groups on columns and foreign key relations in schema.xml. Passing a group name to the toOutputGroup() method on the model or ObjectCollection returns an array holding all values defined by the group name.

Usage

Declare groups in schema.xml:

<table name="le_table">
  <column name="col1" outputGroup="foo,bar" />
  <column name="col2" />
  <foreign-key phpName="fk" outputGroup="foo">
    ...

Serialize objects by output group:

leTableObject->toOutputGroup('foo'); // will return ['Col1' => ..., 'Fk' => ...]
leTableObject->toOutputGroup('bar'); // will return ['Col1' => ...]

Instead of a group name, an array with model class names can also be used. In this form, multiple groups can be given in an array:

leTableObject->toOutputGroup([
  LeTable::class => ['foo', 'bar'],
  'default' => 'bar'
]);

Default output groups per table

Default output groups can be defined on the table, columns and relations can opt-out with ignoreGroup or refIgnoreGroup:

<table name="le_table" outputGroup="foo,bar">
  <column name="col1" ignoreGroup="foo" />
  <column name="col2" />
  <foreign-key phpName="fk" ignoreGroup="foo" refIgnoreGroup="bar">
    ...

Avoids recursion

Related model instances are linked in both directions, leading to recursive output when using toArray(). Output groups skip relations that were already handled:

toArray()	toOutputGroup()
[ 'event' => [ 'event_type' => [ 'events' => [[*RECURSION*]] ] ] ]	[ 'event' => [ 'event_type' => [ ] ] ]

Implementation

Changes are implemented as a behavior, so this is an opt-in, and the code does not interfere with Propel code.

To enable output groups, the behavior has to be declared in schema.xml:

<database>
    <behavior name="output_group"/>

The behavior adds functionality to table map, model and query classes:

TableMap classes:

• Add output groups from schema into TableMap classes and a method to access them.
• Override TableMap::getCollectionClassName(), so queries use a subclass of ObjectCollection with a toOutputGroup() method. If necessary, the class can be set manually through the behavior's object_collection_class parameter.

Model classes:

• Add toOutputGroup() method to generated model classes.
• Add imlements interface declaration.

Query classes:

• Add @method declarations with updated return type for the findX() methods to header doc.

I find this much easier than using a serializer as I don't have to re-iterate all columns in another file.