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();
+
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Invoice());
+$nestedInvoice = $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:
+
+```
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Invoice());
+$nestedInvoice = $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:
+
+```
+$nestedPayment = $mUnion->addNestedModel(new Invoice(), ['amount' => '-[amount]']);
+$nestedInvoice = $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:
+
+```
+$nestedPayment = $unionPaymentInvoice->addNestedModel(new Invoice(), ['amount' => '-[amount]']);
+$nestedInvoice = $unionPaymentInvoice->addNestedModel(new Payment(), ['description' => '[note]']);
+
+$nestedPayment->addExpression('type', ['expr' => '\'payment\'']);
+$nestedInvoice->addExpression('type', ['expr' => '\'invoice\'']);
+$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-line
+        } finally {
+            $model->table = $tableOrig;
+        }
+    }
+}