Adds addRestoreOrCreate extension to SoftDeletingScope (#5338)

CHANGELOG-3.0.md

@@ -2,6 +2,7 @@
 
 ## Added
 
+- [#5338](https://github.com/hyperf/hyperf/pull/5338) Added `addRestoreOrCreate` extension to `SoftDeletingScope`.
 - [#5349](https://github.com/hyperf/hyperf/pull/5349) Added `ResumeExitCoordinatorListener`.
 - [#5355](https://github.com/hyperf/hyperf/pull/5355) Added `System::getCpuCoresNum()`.
 

docs/en/db/model.md

@@ -528,6 +528,16 @@ class User extends Model
 }
 ```
 
+The `restoreOrCreate` method will match the data in the database with the given column/value. If the corresponding model is found in the database, execute the `restore` method to restore the model, otherwise a record will be created from the attributes of the first parameter and even the attributes of the second parameter and inserted into the database.
+
+```php
+// Look up users by name, create them with name and gender, age attributes if they don't exist...
+$user = User::restoreOrCreate(
+    ['name' => 'Hyperf'],
+    ['gender' => 1, 'age' => 20]
+);
+```
+
 ## Bit 类型
 
 默认情况下，Hyperf 中的数据库模型转 SQL 过程中，会将参数值统一转为 String 类型，以解决 int 在大数问题和使值类型更容易匹配索引，若想要使 `ORM` 支持 `bit` 类型，只需要增加以下事件监听器代码即可。

docs/zh-cn/db/model.md

@@ -528,6 +528,16 @@ class User extends Model
 }
 ```
 
+`restoreOrCreate` 方法会通过给定的 列 / 值 来匹配数据库中的数据。如果在数据库中找到对应的模型，即执行 `restore` 方法恢复模型，否则会从第一个参数的属性乃至第二个参数的属性中创建一条记录插入到数据库。
+
+```php
+// 通过 name 查找用户，不存在则使用 name 和 gender, age 属性创建...
+$user = User::restoreOrCreate(
+    ['name' => 'Hyperf'],
+    ['gender' => 1, 'age' => 20]
+);
+```
+
 ## Bit 类型
 
 默认情况下，Hyperf 中的数据库模型转 SQL 过程中，会将参数值统一转为 String 类型，以解决 int 在大数问题和使值类型更容易匹配索引，若想要使 `ORM` 支持 `bit` 类型，只需要增加以下事件监听器代码即可。

docs/zh-hk/db/model.md

@@ -528,6 +528,16 @@ class User extends Model
 }
 ```
 
+`restoreOrCreate` 方法會通過給定的 列 / 值 來匹配數據庫中的數據。如果在數據庫中找到對應的模型，即執行 `restore` 方法恢復模型，否則會從第一個參數的屬性乃至第二個參數的屬性中創建一條記錄插入到數據庫。
+
+```php
+// 通過 name 查找用户，不存在則使用 name 和 gender, age 屬性創建...
+$user = User::restoreOrCreate(
+    ['name' => 'Hyperf'],
+    ['gender' => 1, 'age' => 20]
+);
+```
+
 ## Bit 類型
 
 默認情況下，Hyperf 中的數據庫模型轉 SQL 過程中，會將參數值統一轉為 String 類型，以解決 int 在大數問題和使值類型更容易匹配索引，若想要使 `ORM` 支持 `bit` 類型，只需要增加以下事件監聽器代碼即可。

docs/zh-tw/db/model.md

@@ -528,6 +528,16 @@ class User extends Model
 }
 ```
 
+`restoreOrCreate` 方法會通過給定的 列 / 值 來匹配資料庫中的資料。如果在資料庫中找到對應的模型，即執行 `restore` 方法恢復模型，否則會從第一個參數的屬性乃至第二個參數的屬性中建立一條記錄插入到資料庫。
+
+```php
+// 通過 name 查詢使用者，不存在則使用 name 和 gender, age 屬性建立...
+$user = User::restoreOrCreate(
+    ['name' => 'Hyperf'],
+    ['gender' => 1, 'age' => 20]
+);
+```
+
 ## Bit 型別
 
 預設情況下，Hyperf 中的資料庫模型轉 SQL 過程中，會將引數值統一轉為 String 型別，以解決 int 在大數問題和使值型別更容易匹配索引，若想要使 `ORM` 支援 `bit` 型別，只需要增加以下事件監聽器程式碼即可。

src/database/src/Model/SoftDeletes.php

@@ -14,6 +14,7 @@ namespace Hyperf\Database\Model;
 use Psr\EventDispatcher\StoppableEventInterface;
 
 /**
+ * @method static static|\Hyperf\Database\Model\Builder|\Hyperf\Database\Query\Builder restoreOrCreate(array $attributes = [], array $values = [])
  * @method static static|\Hyperf\Database\Model\Builder|\Hyperf\Database\Query\Builder withTrashed(bool $withTrashed = true)
  * @method static static|\Hyperf\Database\Model\Builder|\Hyperf\Database\Query\Builder onlyTrashed()
  * @method static static|\Hyperf\Database\Model\Builder|\Hyperf\Database\Query\Builder withoutTrashed()

src/database/src/Model/SoftDeletingScope.php

@@ -16,7 +16,7 @@ class SoftDeletingScope implements Scope
     /**
      * All the extensions to be added to the builder.
      */
-    protected array $extensions = ['Restore', 'WithTrashed', 'WithoutTrashed', 'OnlyTrashed'];
+    protected array $extensions = ['Restore', 'RestoreOrCreate', 'WithTrashed', 'WithoutTrashed', 'OnlyTrashed'];
 
     /**
      * Apply the scope to a given Model query builder.
@@ -78,6 +78,22 @@ class SoftDeletingScope implements Scope
         });
     }
 
+    /**
+     * Add the restore-or-create extension to the builder.
+     *
+     * @param \Hyperf\Database\Model\Builder $builder
+     */
+    protected function addRestoreOrCreate(Builder $builder)
+    {
+        $builder->macro('restoreOrCreate', function (Builder $builder, array $attributes = [], array $values = []) {
+            $builder->withTrashed();
+
+            return tap($builder->firstOrCreate($attributes, $values), function ($instance) {
+                $instance->restore();
+            });
+        });
+    }
+
     /**
      * Add the with-trashed extension to the builder.
      *