From 5c28c203cd8c12b7394eabb153f54b5fb2a01a3f Mon Sep 17 00:00:00 2001
From: Sergei Tigrov <rrr-r@ya.ru>
Date: Tue, 21 May 2024 11:26:43 +0700
Subject: [PATCH] Add `resetRelation()` method to `ActiveRecordInterface`
 (#332)

---
 src/ActiveRecordInterface.php      | 81 ++++++++++++++++--------------
 src/Trait/MagicPropertiesTrait.php |  2 +-
 2 files changed, 45 insertions(+), 38 deletions(-)

diff --git a/src/ActiveRecordInterface.php b/src/ActiveRecordInterface.php
index c81139a04..f72a3c70d 100644
--- a/src/ActiveRecordInterface.php
+++ b/src/ActiveRecordInterface.php
@@ -184,43 +184,6 @@ public function getOldPrimaryKey(bool $asArray = false): mixed;
      */
     public function getPrimaryKey(bool $asArray = false): mixed;
 
-    /**
-     * Returns the relation object with the specified name.
-     *
-     * @param string $name The relation name, for example `orders` (case-sensitive).
-     *
-     * @return ActiveRecordInterface|array|null The relation object.
-     */
-    public function relation(string $name): self|array|null;
-
-    /**
-     * Returns the relation query object with the specified name.
-     *
-     * A relation is defined by a getter method which returns an object implementing the {@see ActiveQueryInterface}
-     * (normally this would be a relational {@see ActiveQuery} object).
-     *
-     * Relations can be defined using {@see hasOne()} and {@see hasMany()} methods. For example:
-     *
-     * ```php
-     * public function relationQuery(string $name, bool $throwException = true): ActiveQueryInterface
-     * {
-     *     return match ($name) {
-     *         'orders' => $this->hasMany(Order::class, ['customer_id' => 'id']),
-     *         'country' => $this->hasOne(Country::class, ['id' => 'country_id']),
-     *         default => parent::relationQuery($name),
-     *     };
-     * }
-     * ```
-     *
-     * @param string $name The relation name, for example `orders` (case-sensitive).
-     * @param bool $throwException Whether to throw exception if the relation doesn't exist.
-     *
-     * @throws InvalidArgumentException
-     *
-     * @return ActiveQueryInterface|null The relational query object.
-     */
-    public function relationQuery(string $name, bool $throwException = true): ActiveQueryInterface|null;
-
     /**
      * Return the name of the table associated with this AR class.
      *
@@ -345,6 +308,50 @@ public function populateRelation(string $name, array|self|null $records): void;
      */
     public function primaryKey(): array;
 
+    /**
+     * Returns the relation object with the specified name.
+     *
+     * @param string $name The relation name, for example `orders` (case-sensitive).
+     *
+     * @return ActiveRecordInterface|array|null The relation object.
+     */
+    public function relation(string $name): self|array|null;
+
+    /**
+     * Returns the relation query object with the specified name.
+     *
+     * A relation is defined by a getter method which returns an object implementing the {@see ActiveQueryInterface}
+     * (normally this would be a relational {@see ActiveQuery} object).
+     *
+     * Relations can be defined using {@see hasOne()} and {@see hasMany()} methods. For example:
+     *
+     * ```php
+     * public function relationQuery(string $name, bool $throwException = true): ActiveQueryInterface
+     * {
+     *     return match ($name) {
+     *         'orders' => $this->hasMany(Order::class, ['customer_id' => 'id']),
+     *         'country' => $this->hasOne(Country::class, ['id' => 'country_id']),
+     *         default => parent::relationQuery($name),
+     *     };
+     * }
+     * ```
+     *
+     * @param string $name The relation name, for example `orders` (case-sensitive).
+     * @param bool $throwException Whether to throw exception if the relation doesn't exist.
+     *
+     * @throws InvalidArgumentException
+     *
+     * @return ActiveQueryInterface|null The relational query object.
+     */
+    public function relationQuery(string $name, bool $throwException = true): ActiveQueryInterface|null;
+
+    /**
+     * Resets relation data for the specified name.
+     *
+     * @param string $name The relation name, for example `orders` (case-sensitive).
+     */
+    public function resetRelation(string $name): void;
+
     /**
      * Saves the current record.
      *
diff --git a/src/Trait/MagicPropertiesTrait.php b/src/Trait/MagicPropertiesTrait.php
index 04c8c8368..df2d854f3 100644
--- a/src/Trait/MagicPropertiesTrait.php
+++ b/src/Trait/MagicPropertiesTrait.php
@@ -41,7 +41,7 @@
  * @see AbstractActiveRecord::resetDependentRelations()
  *
  * @method void resetRelation(string $name)
- * @see AbstractActiveRecord::resetRelation()
+ * @see ActiveRecordInterface::resetRelation()
  *
  * @method ActiveRecordInterface|array|null retrieveRelation(string $name)
  * @see AbstractActiveRecord::retrieveRelation()