Add Model\UnionModel model

docs/index.md

@@ -22,6 +22,7 @@ static
 references
 expressions
 joins
+unions
 aggregates
 hooks
 deriving

docs/unions.md

@@ -0,0 +1,119 @@
+:::{php:namespace} Atk4\Data
+:::
+
+(Unions)=
+
+# Model Unions
+
+:::{php:class} Model\UnionModel
+:::
+
+In some cases data from multiple models need to be combined. In this case the UnionModel model comes very handy.
+In the case used below Client model schema may have multiple invoices and multiple payments. Payment is not related to the invoice.:
+
+```
+class Client extends \Atk4\Data\Model {
+ public $table = 'client';
+
+ protected function init(): void
+ {
+ parent::init();
+
+ $this->addField('name');
+
+ $this->hasMany('Payment');
+ $this->hasMany('Invoice');
+ }
+}
+```
+
+(see tests/ModelUnionTest.php, tests/Model/Client.php, tests/Model/Payment.php and tests/Model/Invoice.php files).
+
+## Union Model Definition
+
+Normally a model is associated with a single table. Union model can have multiple nested models defined and it fetches
+results from that. As a result, Union model will have no "id" field. Below is an example of inline definition of Union model.
+The Union model can be separated in a designated class and nested model added within the init() method body of the new class:
+
+```
+$unionPaymentInvoice = new \Atk4\Data\Model\UnionModel();
+
+$nestedInvoice = $unionPaymentInvoice->addNestedModel(new Invoice());
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Payment());
+```
+
+Next, assuming that both models have common fields "name" and "amount", `$unionPaymentInvoice` fields can be set:
+
+```
+$unionPaymentInvoice->addField('name');
+$unionPaymentInvoice->addField('amount', ['type' => 'atk4_money']);
+```
+
+Then data can be queried:
+
+```
+$unionPaymentInvoice->export();
+```
+
+## Define Fields
+
+Below is an example of 3 different ways to define fields for the UnionModel model:
+
+```
+// will link the "name" field with all the nested models
+$unionPaymentInvoice->addField('client_id');
+
+// Expression will not affect nested models in any way
+$unionPaymentInvoice->addExpression('name_capital', ['expr' => 'upper([name])']);
+
+// UnionModel model can be joined with extra tables and define some fields from those joins
+$unionPaymentInvoice
+ ->join('client', 'client_id')
+ ->addField('client_name', 'name');
+```
+
+{ref}`Expressions` and {ref}`Joins` are working just as they would on any other model.
+
+## Field Mapping
+
+Sometimes the field that is defined in the UnionModel model may be named differently inside nested models.
+E.g. Invoice has field "description" and payment has field "note".
+When defining a nested model a field map array needs to be specified:
+
+```
+$nestedInvoice = $unionPaymentInvoice->addNestedModel(new Invoice());
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Payment(), ['description' => '[note]']);
+$unionPaymentInvoice->addField('description');
+```
+
+The key of the field map array must match the UnionModel field. The value is an expression. (See {php:meth}`Model::addExpression`).
+This format can also be used to reverse sign on amounts. When we are creating "Transactions", then invoices would be
+subtracted from the amount, while payments will be added:
+
+```
+$nestedInvoice = $mUnion->addNestedModel(new Invoice(), ['amount' => '-[amount]']);
+$nestedPayment = $mUnion->addNestedModel(new Payment(), ['description' => '[note]']);
+$unionPaymentInvoice->addField('description');
+```
+
+Should more flexibility be needed, more expressions (or fields) can be added directly to nested models:
+
+```
+$nestedInvoice = $unionPaymentInvoice->addNestedModel(new Invoice(), ['amount' => '-[amount]']);
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Payment(), ['description' => '[note]']);
+
+$nestedInvoice->addExpression('type', ['expr' => '\'invoice\'']);
+$nestedPayment->addExpression('type', ['expr' => '\'payment\'']);
+$unionPaymentInvoice->addField('type');
+```
+
+A new field "type" has been added that will be defined as a static constant.
+
+## Referencing an UnionModel Model
+
+Like any other model, UnionModel model can be assigned through a reference. In the case here one Client can have multiple transactions.
+Initially a related union can be defined:
+
+```
+$client->hasMany('Transaction', new Transaction());
+```

src/Model/UnionInternalTable.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Atk4\Data\Model;
+
+use Atk4\Core\TrackableTrait;
+use Atk4\Data\Exception;
+use Atk4\Data\Model;
+use Atk4\Data\Persistence;
+
+/**
+ * Map self::action() to self::getOwner()->actionInnerTable().
+ *
+ * Called from https://github.com/atk4/data/blob/5.0.0/src/Persistence/Sql.php#L188.
+ *
+ * @method Model getOwner()
+ *
+ * @internal
+ */
+class UnionInternalTable
+{
+ use TrackableTrait;
+
+ /**
+ * @param array<mixed> $args
+ *
+ * @return Persistence\Sql\Query
+ */
+ public function action(string $mode, array $args = [])
+ {
+ if ($mode !== 'select' || $args !== []) {
+ throw new Exception('Only "select" action with empty arguments is expected');
+ }
+
+ $model = $this->getOwner();
+
+ $tableOrig = $model->table;
+ $model->table = '_tu';
+ try {
+ return $model->actionSelectInnerTable(); // @phpstan-ignore method.notFound
+ } finally {
+ $model->table = $tableOrig;
+ }
+ }
+}