Remove onePopulate() and allPopulate() methods (#380)

yiisoft · Aug 24, 2024 · 675deff · 675deff
1 parent 721cbf2
commit 675deff
Show file tree

Hide file tree

Showing 18 changed files with 129 additions and 153 deletions.
diff --git a/README.md b/README.md
@@ -144,7 +144,7 @@ use Yiisoft\ActiveRecord\ActiveQuery;
 
 $userQuery = new ActiveQuery(User::class);
 
-$user = $userQuery->where(['id' => 1])->onePopulate();
+$user = $userQuery->where(['id' => 1])->one();
 
 $username = $user->getAttribute('username');
 $email = $user->getAttribute('email');

diff --git a/docs/create-model.md b/docs/create-model.md
@@ -284,7 +284,7 @@ use Yiisoft\ActiveRecord\ActiveQuery;
 
 $userQuery = new ActiveQuery(User::class, $db);
 
-$user = $userQuery->where(['id' => 1])->onePopulate();
+$user = $userQuery->where(['id' => 1])->one();
 
 $profile = $user->getProfile();
 $orders = $user->getOrders();

diff --git a/src/ActiveQuery.php b/src/ActiveQuery.php
@@ -121,18 +121,6 @@ final public function __construct(
         parent::__construct($this->getARInstance()->db());
     }
 
-    /**
-     * Executes a query and returns all results as an array.
-     *
-     * If null, the db connection returned by {@see arClass} will be used.
-     *
-     * @throws Exception
-     * @throws InvalidConfigException
-     * @throws Throwable
-     *
-     * @psalm-suppress ImplementedReturnTypeMismatch
-     * @return ActiveRecordInterface[] The query results. If the query results in nothing, an empty array will be returned.
-     */
     public function all(): array
     {
         if ($this->shouldEmulateExecution()) {
@@ -213,11 +201,11 @@ public function prepare(QueryBuilderInterface $builder): QueryInterface
                     }
                 } else {
                     if ($viaCallableUsed) {
-                        $model = $viaQuery->onePopulate();
+                        $model = $viaQuery->one();
                     } elseif ($this->primaryModel->isRelationPopulated($viaName)) {
                         $model = $this->primaryModel->relation($viaName);
                     } else {
-                        $model = $viaQuery->onePopulate();
+                        $model = $viaQuery->one();
                         $this->primaryModel->populateRelation($viaName, $model);
                     }
                     $viaModels = $model === null ? [] : [$model];
@@ -337,43 +325,15 @@ private function removeDuplicatedModels(array $models): array
         return array_values(array_combine($hash, $models));
     }
 
-    /**
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidConfigException
-     * @throws NotSupportedException
-     * @throws ReflectionException
-     * @throws Throwable
-     */
-    public function allPopulate(): array
-    {
-        $rows = $this->all();
-
-        if ($rows !== []) {
-            $rows = $this->populate($rows, $this->indexBy);
-        }
-
-        return $rows;
-    }
-
-    /**
-     * @throws Exception
-     * @throws InvalidArgumentException
-     * @throws InvalidConfigException
-     * @throws NotSupportedException
-     * @throws ReflectionException
-     * @throws Throwable
-     */
-    public function onePopulate(): array|ActiveRecordInterface|null
+    public function one(): array|ActiveRecordInterface|null
     {
-        $row = $this->one();
+        $row = parent::one();
 
-        if ($row !== null) {
-            $activeRecord = $this->populate([$row], $this->indexBy);
-            $row = reset($activeRecord) ?: null;
+        if ($row === null) {
+            return null;
         }
 
-        return $row;
+        return $this->populate([$row])[0];
     }
 
     /**
@@ -883,7 +843,7 @@ public function getARClass(): string|ActiveRecordInterface|Closure
      */
     public function findOne(mixed $condition): array|ActiveRecordInterface|null
     {
-        return $this->findByCondition($condition)->onePopulate();
+        return $this->findByCondition($condition)->one();
     }
 
     /**

diff --git a/src/ActiveQueryInterface.php b/src/ActiveQueryInterface.php
@@ -10,6 +10,7 @@
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidArgumentException;
 use Yiisoft\Db\Exception\InvalidConfigException;
+use Yiisoft\Db\Exception\NotSupportedException;
 use Yiisoft\Db\Query\QueryInterface;
 use Yiisoft\Definitions\Exception\CircularReferenceException;
 use Yiisoft\Definitions\Exception\NotInstantiableException;
@@ -26,6 +27,19 @@
  */
 interface ActiveQueryInterface extends QueryInterface
 {
+    /**
+     * @inheritdoc
+     *
+     * @throws Exception
+     * @throws InvalidConfigException
+     * @throws Throwable
+     *
+     * @return ActiveRecordInterface[]|array[] All rows of the query result. Each array element is an `array` or
+     * instance of {@see ActiveRecordInterface} representing a row of data, depends on {@see isAsArray()} result.
+     * Empty array if the query results in nothing.
+     */
+    public function all(): array;
+
     /**
      * Sets the {@see asArray} property.
      *
@@ -544,24 +558,11 @@ public function link(array $value): self;
      *
      * @param bool $value Whether this query represents a relation to more than one record.
      * This property is only used in relational context. If true, this relation will populate all query results into AR
-     * instances using {@see Query::all()|all()}.
-     * If false, only the first row of the results will be retrieved using {@see Query::one()|one()}.
+     * instances using {@see all()}.
+     * If false, only the first row of the results will be retrieved using {@see one()}.
      */
     public function multiple(bool $value): self;
 
-    /**
-     * Executes the query and returns ActiveRecord instances populated with the query result.
-     *
-     * @return ActiveRecordInterface|array|null The query results. If the query results in nothing, an empty array will
-     * be returned.
-     */
-    public function allPopulate(): array|ActiveRecordInterface|null;
-
-    /**
-     * Executes the query and returns ActiveRecord instances populated with the query result.
-     */
-    public function onePopulate(): array|ActiveRecordInterface|null;
-
     /**
      * @return ActiveQueryInterface|array|null The query associated with the junction table.
      * Please call {@see Actiquery::via} to set this property instead of directly setting it.
@@ -599,9 +600,24 @@ public function getARInstance(): ActiveRecordInterface;
      * This property is only used in relational context.
      *
      * If `true`, this relation will populate all query results into active record instances using
-     * {@see ActiveQuery::all()}.
+     * {@see all()}.
      *
-     * If `false`, only the first row of the results will be retrieved using {@see ActiveQuery::one()}.
+     * If `false`, only the first row of the results will be retrieved using {@see one()}.
      */
     public function getMultiple(): bool;
+
+    /**
+     * @inheritdoc
+     *
+     * @throws Exception
+     * @throws InvalidArgumentException
+     * @throws InvalidConfigException
+     * @throws NotSupportedException
+     * @throws ReflectionException
+     * @throws Throwable
+     *
+     * @return ActiveRecordInterface|array|null The first row as an `array` or instance of {@see ActiveRecordInterface}
+     * of the query result, depends on {@see isAsArray()} result. `null` if the query results in nothing.
+     */
+    public function one(): array|ActiveRecordInterface|null;
 }
diff --git a/src/ActiveRecord.php b/src/ActiveRecord.php
@@ -204,7 +204,7 @@ public function refresh(): bool
 
         $query->where($pk);
 
-        return $this->refreshInternal($query->onePopulate());
+        return $this->refreshInternal($query->one());
     }
 
     /**

diff --git a/src/ActiveRelationTrait.php b/src/ActiveRelationTrait.php
@@ -185,7 +185,7 @@ public function inverseOf(string $relationName): static
      */
     public function relatedRecords(): ActiveRecordInterface|array|null
     {
-        return $this->multiple ? $this->all() : $this->onePopulate();
+        return $this->multiple ? $this->all() : $this->one();
     }
 
     /**
@@ -254,7 +254,7 @@ public function populateRelation(string $name, array &$primaryModels): array
         }
 
         if (!$this->multiple && count($primaryModels) === 1) {
-            $models = [$this->onePopulate()];
+            $models = [$this->one()];
             $this->populateInverseRelation($models, $primaryModels);
 
             $primaryModel = reset($primaryModels);

diff --git a/tests/ActiveQueryFindTest.php b/tests/ActiveQueryFindTest.php
@@ -77,19 +77,19 @@ public function testFindBySql(): void
 
         $customerQuery = new ActiveQuery(Customer::class);
 
-        /** find onePopulate */
-        $customers = $customerQuery->findBySql('SELECT * FROM {{customer}} ORDER BY [[id]] DESC')->onePopulate();
+        /** find one() */
+        $customers = $customerQuery->findBySql('SELECT * FROM {{customer}} ORDER BY [[id]] DESC')->one();
         $this->assertInstanceOf(Customer::class, $customers);
         $this->assertEquals('user3', $customers->getAttribute('name'));
 
-        /** find allPopulate */
-        $customers = $customerQuery->findBySql('SELECT * FROM {{customer}}')->allPopulate();
+        /** find all() */
+        $customers = $customerQuery->findBySql('SELECT * FROM {{customer}}')->all();
         $this->assertCount(3, $customers);
 
         /** find with parameter binding */
         $customers = $customerQuery
             ->findBySql('SELECT * FROM {{customer}} WHERE [[id]]=:id', [':id' => 2])
-            ->onePopulate();
+            ->one();
         $this->assertInstanceOf(Customer::class, $customers);
         $this->assertEquals('user2', $customers->getAttribute('name'));
     }
@@ -210,12 +210,12 @@ public function testFind(): void
         $this->assertInstanceOf(ActiveQueryInterface::class, $customerQuery);
 
         /** find one */
-        $customer = $customerQuery->onePopulate();
+        $customer = $customerQuery->one();
         $this->assertInstanceOf(Customer::class, $customer);
 
         /** find all */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customers = $customerQuery->allPopulate();
+        $customers = $customerQuery->all();
         $this->assertCount(3, $customers);
         $this->assertInstanceOf(Customer::class, $customers[0]);
         $this->assertInstanceOf(Customer::class, $customers[1]);
@@ -254,13 +254,13 @@ public function testFind(): void
 
         /** find by attributes */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customer = $customerQuery->where(['name' => 'user2'])->onePopulate();
+        $customer = $customerQuery->where(['name' => 'user2'])->one();
         $this->assertInstanceOf(Customer::class, $customer);
         $this->assertEquals(2, $customer->getId());
 
         /** scope */
         $customerQuery = new CustomerQuery(Customer::class);
-        $this->assertCount(2, $customerQuery->active()->allPopulate());
+        $this->assertCount(2, $customerQuery->active()->all());
         $this->assertEquals(2, $customerQuery->active()->count());
     }
 
@@ -397,48 +397,48 @@ public function testFindLimit(): void
 
         /** one */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customer = $customerQuery->orderBy('id')->onePopulate();
+        $customer = $customerQuery->orderBy('id')->one();
         $this->assertEquals('user1', $customer->getName());
 
         /** all */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customers = $customerQuery->allPopulate();
+        $customers = $customerQuery->all();
         $this->assertCount(3, $customers);
 
         /** limit */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customers = $customerQuery->orderBy('id')->limit(1)->allPopulate();
+        $customers = $customerQuery->orderBy('id')->limit(1)->all();
         $this->assertCount(1, $customers);
         $this->assertEquals('user1', $customers[0]->getName());
 
-        $customers = $customerQuery->orderBy('id')->limit(1)->offset(1)->allPopulate();
+        $customers = $customerQuery->orderBy('id')->limit(1)->offset(1)->all();
         $this->assertCount(1, $customers);
         $this->assertEquals('user2', $customers[0]->getName());
 
-        $customers = $customerQuery->orderBy('id')->limit(1)->offset(2)->allPopulate();
+        $customers = $customerQuery->orderBy('id')->limit(1)->offset(2)->all();
         $this->assertCount(1, $customers);
         $this->assertEquals('user3', $customers[0]->getName());
 
-        $customers = $customerQuery->orderBy('id')->limit(2)->offset(1)->allPopulate();
+        $customers = $customerQuery->orderBy('id')->limit(2)->offset(1)->all();
         $this->assertCount(2, $customers);
         $this->assertEquals('user2', $customers[0]->getName());
         $this->assertEquals('user3', $customers[1]->getName());
 
-        $customers = $customerQuery->limit(2)->offset(3)->allPopulate();
+        $customers = $customerQuery->limit(2)->offset(3)->all();
         $this->assertCount(0, $customers);
 
         /** offset */
         $customerQuery = new ActiveQuery(Customer::class);
-        $customer = $customerQuery->orderBy('id')->offset(0)->onePopulate();
+        $customer = $customerQuery->orderBy('id')->offset(0)->one();
         $this->assertEquals('user1', $customer->getName());
 
-        $customer = $customerQuery->orderBy('id')->offset(1)->onePopulate();
+        $customer = $customerQuery->orderBy('id')->offset(1)->one();
         $this->assertEquals('user2', $customer->getName());
 
-        $customer = $customerQuery->orderBy('id')->offset(2)->onePopulate();
+        $customer = $customerQuery->orderBy('id')->offset(2)->one();
         $this->assertEquals('user3', $customer->getName());
 
-        $customer = $customerQuery->offset(3)->onePopulate();
+        $customer = $customerQuery->offset(3)->one();
         $this->assertNull($customer);
     }
 
@@ -513,7 +513,7 @@ public function testFindEager(): void
         $customers[1]->resetRelation('orders');
         $this->assertFalse($customers[1]->isRelationPopulated('orders'));
 
-        $customer = $customerQuery->where(['id' => 1])->with('orders')->onePopulate();
+        $customer = $customerQuery->where(['id' => 1])->with('orders')->one();
         $this->assertTrue($customer->isRelationPopulated('orders'));
         $this->assertCount(1, $customer->getOrders());
         $this->assertCount(1, $customer->getRelatedRecords());
@@ -569,7 +569,7 @@ public function testFindNestedRelation(): void
         $this->assertCount(3, $customers[2]->getOrders()[0]->getItems());
         $this->assertCount(1, $customers[2]->getOrders()[1]->getItems());
 
-        $customers = $customerQuery->where(['id' => 1])->with('ordersWithItems')->onePopulate();
+        $customers = $customerQuery->where(['id' => 1])->with('ordersWithItems')->one();
         $this->assertTrue($customers->isRelationPopulated('ordersWithItems'));
         $this->assertCount(1, $customers->getOrdersWithItems());
 
@@ -667,15 +667,15 @@ public function testFindEagerIndexBy(): void
         $this->checkFixture($this->db(), 'order');
 
         $orderQuery = new ActiveQuery(Order::class);
-        $order = $orderQuery->with('itemsIndexed')->where(['id' => 1])->onePopulate();
+        $order = $orderQuery->with('itemsIndexed')->where(['id' => 1])->one();
         $this->assertTrue($order->isRelationPopulated('itemsIndexed'));
 
         $items = $order->getItemsIndexed();
         $this->assertCount(2, $items);
         $this->assertTrue(isset($items[1]));
         $this->assertTrue(isset($items[2]));
 
-        $order = $orderQuery->with('itemsIndexed')->where(['id' => 2])->onePopulate();
+        $order = $orderQuery->with('itemsIndexed')->where(['id' => 2])->one();
         $this->assertTrue($order->isRelationPopulated('itemsIndexed'));
 
         $items = $order->getItemsIndexed();