[feature] add ModelFactory::random() and randomSet($min, ?$max)

README.md

@@ -563,6 +563,9 @@ $repository->assertNotExists(['title' => 'My Title']);
 $repository->getCount(); // number of rows in the database table
 $repository->first(); // get the first object (wrapped in a object proxy)
 $repository->truncate(); // delete all rows in the database table
+$repository->random(); // get a random object
+$repository->randomSet(5); // get 5 random objects
+$repository->randomSet(0, 5); // get 0-5 random objects
 
 // instance of ObjectRepository (all returned objects are proxied)
 $repository->find(1);                               // Proxy|Post|null
@@ -603,6 +606,8 @@ use Zenstruck\Foundry\Proxy;
 
 /**
  * @method static Post|Proxy findOrCreate(array $attributes)
+ * @method static Post|Proxy random()
+ * @method static Post[]|Proxy[] randomSet(int $min, ?int $max = null)
  * @method static PostRepository|RepositoryProxy repository(bool $proxy = true)
  * @method Post instantiate($attributes = [])
  * @method Post[] instantiateMany(int $number, $attributes = [])
@@ -646,6 +651,15 @@ PostFactory::new(['title' => 'My Title'])->create(); // alternative to above
 // find a persisted object for the given attributes, if not found, create with the attributes
 PostFactory::findOrCreate(['title' => 'My Title']); // instance of Proxy|Post
 
+// get a random object that has been persisted
+PostFactory::random(); // instance of Proxy|Post
+
+// get a random set of objects that have been persisted
+PostFactory::randomSet(4); // array containing 4 instances of Proxy|Post's
+
+// random set of persisted objects with min/max
+PostFactory::randomSet(0, 5); // array containing 0-5 instances of Proxy|Post's
+
 PostFactory::repository(); // Instance of RepositoryProxy|PostRepository
 
 // instantiate objects (without persisting)

src/Bundle/Resources/skeleton/Factory.tpl.php

@@ -11,6 +11,8 @@
 
 /**
  * @method static <?= $entity->getShortName() ?>|Proxy findOrCreate(array $attributes)
+ * @method static <?= $entity->getShortName() ?>|Proxy random()
+ * @method static <?= $entity->getShortName() ?>[]|Proxy[] randomSet(int $min, ?int $max = null)
 <?php if ($repository): ?> * @method static <?= $repository->getShortName() ?>|RepositoryProxy repository(bool $proxy = true)
 <?php endif ?>
  * @method <?= $entity->getShortName() ?> instantiate($attributes = [])

src/ModelFactory.php

@@ -59,6 +59,27 @@ final public static function findOrCreate(array $attributes): object
         return self::new()->create($attributes);
     }
 
+    /**
+     * Get a random persisted object.
+     *
+     * @return Proxy|object
+     */
+    final public static function random(): object
+    {
+        return self::repository(true)->random();
+    }
+
+    /**
+     * @param int      $min The minimum number of objects to return (if max is null, will always return this amount)
+     * @param int|null $max The max number of objects to return
+     *
+     * @return Proxy[]|object[]
+     */
+    final public static function randomSet(int $min, ?int $max = null): array
+    {
+        return self::repository(true)->randomSet($min, $max);
+    }
+
     /**
      * @return RepositoryProxy|ObjectRepository
      */

tests/Functional/ModelFactoryTest.php

@@ -56,4 +56,46 @@ public function initialize_must_return_a_value(): void
 
         PostFactoryWithNullInitialize::new();
     }
+
+    public function can_find_random_object(): void
+    {
+        CategoryFactory::new()->createMany(5);
+
+        $ids = [];
+
+        while (5 !== \count(\array_unique($ids))) {
+            $ids[] = CategoryFactory::random()->getId();
+        }
+
+        $this->assertCount(5, \array_unique($ids));
+    }
+
+    public function can_find_random_set_of_objects(): void
+    {
+        CategoryFactory::new()->createMany(5);
+
+        $objects = CategoryFactory::randomSet(3);
+
+        $this->assertCount(3, $objects);
+        $this->assertCount(3, \array_unique(\array_map(fn($category) => $category->getId(), $objects)));
+    }
+
+    public function can_find_random_set_of_objects_with_min_and_max(): void
+    {
+        CategoryFactory::new()->createMany(5);
+
+        $counts = [];
+
+        while (4 !== \count(\array_unique($counts))) {
+            $counts[] = \count(CategoryFactory::randomSet(0, 3));
+        }
+
+        $this->assertCount(4, \array_unique($counts));
+        $this->assertContains(0, $counts);
+        $this->assertContains(1, $counts);
+        $this->assertContains(2, $counts);
+        $this->assertContains(3, $counts);
+        $this->assertNotContains(4, $counts);
+        $this->assertNotContains(5, $counts);
+    }
 }