Drop Reference::refModel() and Model::refModel() methods (#1179)

Author: mvorisek

docs/advanced.md

@@ -622,21 +622,18 @@ persistence layer to load or save anything. Next I need a beforeSave handler:
 ```
 $this->onHookShort(Model::HOOK_BEFORE_SAVE, function () {
     if ($this->_isset('client_code') && !$this->_isset('client_id')) {
-        $cl = $this->refModel('client_id');
-        $cl->addCondition('code', $this->get('client_code'));
-        $this->set('client_id', $cl->action('field', ['id']));
+        $client = $this->ref('client_id');
+        $this->set('client_id', $client->getId());
     }
 
     if ($this->_isset('client_name') && !$this->_isset('client_id')) {
-        $cl = $this->refModel('client_id');
-        $cl->addCondition('name', 'like', $this->get('client_name'));
-        $this->set('client_id', $cl->action('field', ['id']));
+        $client = $this->ref('client_id');
+        $this->set('client_id', $client->getId());
     }
 
     if ($this->_isset('category') && !$this->_isset('category_id')) {
-        $c = $this->refModel('category_id');
-        $c->addCondition($c->titleField, 'like', $this->get('category'));
-        $this->set('category_id', $c->action('field', ['id']));
+        $category = $this->ref('category_id');
+        $this->set('category_id', $category->getId());
     }
 });
 ```
@@ -647,43 +644,6 @@ differently from PHP's default behavior. See documentation for Model::isset
 This technique allows you to hide the complexity of the lookups and also embed
 the necessary queries inside your "insert" query.
 
-### Fallback to default value
-
-You might wonder, with the lookup like that, how the default values will work?
-What if the user-specified entry is not found? Lets look at the code:
-
-```
-if ($m->_isset('category') && !$m->_isset('category_id')) {
-    $c = $this->refModel('category_id');
-    $c->addCondition($c->titleField, 'like', $m->get('category'));
-    $m->set('category_id', $c->action('field', ['id']));
-}
-```
-
-So if category with a name is not found, then sub-query will return "NULL".
-If you wish to use a different value instead, you can create an expression:
-
-```
-if ($m->_isset('category') && !$m->_isset('category_id')) {
-    $c = $this->refModel('category_id');
-    $c->addCondition($c->titleField, 'like', $m->get('category'));
-    $m->set('category_id', $this->expr('coalesce([], [])', [
-        $c->action('field', ['id']),
-        $m->getField('category_id')->default,
-    ]));
-}
-```
-
-The beautiful thing about this approach is that default can also be defined
-as a lookup query:
-
-```
-$this->hasOne('category_id', 'Model_Category');
-$this->getField('category_id')->default =
-    $this->refModel('category_id')->addCondition('name', 'Other')
-        ->action('field', ['id']);
-```
-
 ## Inserting Hierarchical Data
 
 In this example I'll be building API that allows me to insert multi-model

docs/persistence.md

@@ -746,10 +746,10 @@ executing:
 ```
 $m = Model_Product($db);
 $m->addCondition('name', $productName);
-$action = $m->action('getOne', ['id']);
+$productIdAction = $m->action('field', ['id']);
 
 $m = Model_Invoice($db);
-$m->insert(['qty' => 20, 'product_id' => $action]);
+$m->insert(['qty' => 20, 'product_id' => $productIdAction]);
 ```
 
 Insert operation will check if you are using same persistence.
@@ -759,14 +759,6 @@ result instead.
 Being able to embed actions inside next query allows Agile Data to reduce number
 of queries issued.
 
-The default action type can be set when executing action, for example:
-
-```
-$a = $m->action('field', 'user', 'getOne');
-
-echo $a(); // same as $a->getOne();
-```
-
 ### SQL Actions
 
 Currently only read-only actions are supported by `Persistence\Sql`:

docs/references.md

@@ -95,7 +95,7 @@ If you are worried about performance you can keep 2 models in memory:
 
 ```
 $order = new Order($db);
-$client = $order->refModel('client_id');
+$client = $order->ref('client_id');
 
 foreach ($order as $o) {
     $c = $client->load($o->get('client_id'));
@@ -267,7 +267,7 @@ Alternatively you may also specify either 'aggregate':
 ```
 $book->hasMany('Pages', ['model' => [Page::class]])
     ->addField('page_list', [
-        'aggregate' => $book->refModel('Pages')->expr('group_concat([number], [])', ['-']),
+        'aggregate' => $book->getReference('Pages')->createTheirModel()->expr('group_concat([number], [])', ['-']),
     ]);
 ```
 
@@ -281,7 +281,7 @@ or 'field':
 as of 1.3.4 count's field defaults to `*` - no need to specify explicitly.
 :::
 
-## hasMany / refLink / refModel
+## hasMany / refLink
 
 :::{php:method} refLink($link)
 :::
@@ -315,13 +315,6 @@ from user
 where is_vip = 1
 ```
 
-:::{php:method} refModel($link)
-:::
-
-There are many situations when you need to get referenced model instead of
-reference itself. In such case refModel() comes in as handy shortcut of doing
-`$model->refLink($link)->getModel()`.
-
 ## hasOne reference
 
 :::{php:method} hasOne($link, ['model' => $model])
@@ -530,15 +523,7 @@ While {php:meth}`Model::ref()` returns a related model, {php:meth}`Model::getRef
 gives you the reference object itself so that you could perform some changes on it,
 such as import more fields with {php:meth}`Model::addField()`.
 
-Or you can use {php:meth}`Model::refModel()` which will simply return referenced
-model and you can do fancy things with it.
-
-```
-$refModel = $model->refModel('owner_id');
-```
-
-You can also use {php:meth}`Model::hasReference()` to check if particular reference
-exists in model:
+{php:meth}`Model::hasReference()` can be used to check if particular reference exists in model:
 
 ```
 if ($model->hasReference('owner_id')) {

src/Model/ReferencesTrait.php

@@ -147,7 +147,7 @@ public function getReferences(): array
     }
 
     /**
-     * Traverse to related model.
+     * Traverse reference and create their model.
      *
      * @param array<string, mixed> $defaults
      */
@@ -159,19 +159,7 @@ public function ref(string $link, array $defaults = []): Model
     }
 
     /**
-     * Return related model.
-     *
-     * @param array<string, mixed> $defaults
-     */
-    public function refModel(string $link, array $defaults = []): Model
-    {
-        $reference = $this->getModel(true)->getReference($link);
-
-        return $reference->refModel($this, $defaults);
-    }
-
-    /**
-     * Returns model that can be used for generating sub-query actions.
+     * Traverse reference and create their model but keep condition not materialized (for subquery actions).
      *
      * @param array<string, mixed> $defaults
      */

src/Reference.php

@@ -327,8 +327,7 @@ protected function getDefaultPersistence(Model $theirModel)
     }
 
     /**
-     * Returns referenced model without any extra conditions. However other
-     * relationship types may override this to imply conditions.
+     * Create their model. May be overridden to imply traversal conditions.
      *
      * @param array<string, mixed> $defaults
      */
@@ -337,18 +336,6 @@ public function ref(Model $ourModel, array $defaults = []): Model
         return $this->createTheirModel($defaults);
     }
 
-    /**
-     * Returns referenced model without any extra conditions. Ever when extended
-     * must always respond with Model that does not look into current record
-     * or scope.
-     *
-     * @param array<string, mixed> $defaults
-     */
-    public function refModel(Model $ourModel, array $defaults = []): Model
-    {
-        return $this->createTheirModel($defaults);
-    }
-
     /**
      * @return array<string, mixed>
      */

src/Reference/HasOneSql.php

@@ -79,7 +79,7 @@ public function addField(string $fieldName, string $theirFieldName = null, array
         $ourModel = $this->getOurModel(null);
 
         // if caption/type is not defined in $defaults -> get it directly from the linked model field $theirFieldName
-        $refModel = $ourModel->refModel($this->link);
+        $refModel = $ourModel->getReference($this->link)->createTheirModel();
         $refModelField = $refModel->getField($theirFieldName);
         $defaults['type'] ??= $refModelField->type;
         $defaults['enum'] ??= $refModelField->enum;

src/Util/DeepCopy.php

@@ -250,7 +250,7 @@ protected function _copy(Model $source, Model $destination, array $references, a
                     $this->debug('Proceeding with ' . $refKey);
 
                     // load destination model through $source
-                    $refSourceTable = $source->refModel($refKey)->table;
+                    $refSourceTable = $source->getModel()->getReference($refKey)->createTheirModel()->table;
 
                     if (isset($this->mapping[$refSourceTable])
                         && array_key_exists($source->get($refKey), $this->mapping[$refSourceTable])
@@ -273,7 +273,7 @@ protected function _copy(Model $source, Model $destination, array $references, a
                                 $refKey,
                                 $this->_copy(
                                     $source->ref($refKey),
-                                    $destination->refModel($refKey),
+                                    $destination->getModel()->getReference($refKey)->createTheirModel(),
                                     $refVal,
                                     $exclusions[$refKey] ?? [],
                                     $transforms[$refKey] ?? []

tests/ContainsManyTest.php

@@ -63,7 +63,7 @@ public function testModelCaption(): void
 
         // test caption of containsMany reference
         self::assertSame('My Invoice Lines', $i->getField($i->fieldName()->lines)->getCaption());
-        self::assertSame('My Invoice Lines', $i->refModel($i->fieldName()->lines)->getModelCaption());
+        self::assertSame('My Invoice Lines', $i->getReference($i->fieldName()->lines)->createTheirModel()->getModelCaption());
         self::assertSame('My Invoice Lines', $i->lines->getModelCaption());
     }
 

tests/ContainsOneTest.php

@@ -62,7 +62,7 @@ public function testModelCaption(): void
 
         // test caption of containsOne reference
         self::assertSame('Secret Code', $a->getField($a->fieldName()->door_code)->getCaption());
-        self::assertSame('Secret Code', $a->refModel($a->fieldName()->door_code)->getModelCaption());
+        self::assertSame('Secret Code', $a->getReference($a->fieldName()->door_code)->createTheirModel()->getModelCaption());
         self::assertSame('Secret Code', $a->door_code->getModelCaption());
     }
 

tests/ReferenceTest.php

@@ -65,7 +65,7 @@ public function testModelCaption(): void
         $user->getModel()->hasMany('Orders', ['model' => $order, 'caption' => 'My Orders']);
 
         // test caption of containsOne reference
-        self::assertSame('My Orders', $user->refModel('Orders')->getModelCaption());
+        self::assertSame('My Orders', $user->getModel()->getReference('Orders')->createTheirModel()->getModelCaption());
         self::assertSame('My Orders', $user->ref('Orders')->getModelCaption());
     }