Add documentation

Author: paulbalandan

user_guide_src/source/testing/fabricator.rst

@@ -62,6 +62,23 @@ a child class in your test support folder:
 
 .. literalinclude:: fabricator/006.php
 
+Setting Modifiers
+=================
+
+Faker provides three special providers, ``unique()``, ``optional()``, and ``valid()``,
+to be called before any provider. Fabricator fully supports these modifiers by providing
+dedicated methods.
+
+.. literalinclude:: fabricator/022.php
+
+The arguments passed after the field name are passed directly to the modifiers as-is. You can refer
+to Faker's documentation on these modifiers for details.
+
+Instead of calling each method on Fabricator, you may use Faker's modifiers directly if you are using
+the ``fake()`` method on your models.
+
+.. literalinclude:: fabricator/023.php
+
 Localization
 ============
 

user_guide_src/source/testing/fabricator/022.php

@@ -0,0 +1,11 @@
+<?php
+
+use App\Models\UserModel;
+use CodeIgniter\Test\Fabricator;
+
+$fabricator = new Fabricator(UserModel::class);
+$fabricator->setUnique('email'); // sets generated emails to be always unique
+$fabricator->setOptional('group_id'); // sets group id to be optional, with 50% chance to be `null`
+$fabricator->setValid('age', static fn (int $age): bool => $age >= 18); // sets age to be 18 and above only
+
+$users = $fabricator->make(10);

user_guide_src/source/testing/fabricator/023.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Models;
+
+use CodeIgniter\Test\Fabricator;
+use Faker\Generator;
+
+class UserModel
+{
+    protected $table = 'users';
+
+    public function fake(Generator &$faker)
+    {
+        return [
+            'first'    => $faker->firstName(),
+            'email'    => $faker->unique()->email(),
+            'group_id' => $faker->optional()->passthrough(mt_rand(1, Fabricator::getCount('groups'))),
+        ];
+    }
+}