From 717a2a99c988d3612c90dd243cec812f245428f3 Mon Sep 17 00:00:00 2001
From: neznaika0 <ozornick.ks@gmail.com>
Date: Sat, 9 Nov 2024 23:06:59 +0300
Subject: [PATCH] docs: Improve Validation docs

---
 .../source/libraries/validation.rst           | 54 +++++++++++++++++++
 .../source/libraries/validation/048.php       |  8 +++
 .../source/libraries/validation/049.php       | 25 +++++++++
 .../source/libraries/validation/050.php       | 16 ++++++
 .../source/libraries/validation/051.php       | 27 ++++++++++
 .../source/libraries/validation/052.php       | 29 ++++++++++
 6 files changed, 159 insertions(+)
 create mode 100644 user_guide_src/source/libraries/validation/048.php
 create mode 100644 user_guide_src/source/libraries/validation/049.php
 create mode 100644 user_guide_src/source/libraries/validation/050.php
 create mode 100644 user_guide_src/source/libraries/validation/051.php
 create mode 100644 user_guide_src/source/libraries/validation/052.php

diff --git a/user_guide_src/source/libraries/validation.rst b/user_guide_src/source/libraries/validation.rst
index 2d3b75297ce0..a3d56b55454a 100644
--- a/user_guide_src/source/libraries/validation.rst
+++ b/user_guide_src/source/libraries/validation.rst
@@ -203,6 +203,60 @@ Then add validation rules in the controller (**Form.php**):
 
 If you submit the form you should see the success page or the form with error messages.
 
+****************************
+Working with different types
+****************************
+
+Since the input value is not limited to scalar types, you can check various objects, enumerations or global data (see :ref:`rules-for-file-uploads`).
+Working with the validator is no different, you only need to add custom rules.
+This behavior can be useful when creating entities.
+
+An example for validation can be ``DateTime`` for the creation date, ``URI`` for the profile link, ``SplFileInfo`` for the avatar file.
+
+Let's check the input data before creating a new user, with a file structure:
+
+.. code-block:: text
+
+    app/
+    ├── Config
+    │   └── Validation.php:
+    ├── Controllers
+    │   └── UserController.php
+    ├── Entity
+    │   └── User.php
+    ├── Validation
+    │   └── UserRules.php
+    └── ValueObject
+        └── Name.php
+
+Add custom value-object ``Name``. It is required when working with the ``User``:
+
+.. literalinclude:: validation/048.php
+    :lines: 2-
+
+Create rule. We want to make sure that the username will be of the specified type and have a non-empty value:
+
+.. literalinclude:: validation/049.php
+    :lines: 2-
+
+Add rule to list in **app/Config/Validation.php**:
+
+.. literalinclude:: validation/050.php
+   :lines: 2-
+
+We can check the data manually. It looks more efficiently with the ``Validator``:
+
+
+.. literalinclude:: validation/051.php
+   :lines: 2-
+
+.. note:: Additionally, some basic rules can be applied, such as ``required``, ``permit_empty``, ``field_exists``, ``if_exist``.
+
+Try to create a ``User`` in the controller. Depending on the result, we can throw an exception or handle errors:
+
+.. literalinclude:: validation/052.php
+   :lines: 2-
+
 *********************
 Config for Validation
 *********************
diff --git a/user_guide_src/source/libraries/validation/048.php b/user_guide_src/source/libraries/validation/048.php
new file mode 100644
index 000000000000..f0b72f339436
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/048.php
@@ -0,0 +1,8 @@
+<?php
+
+namespace App\ValueObject;
+
+class Name
+{
+    public $value = '';
+}
diff --git a/user_guide_src/source/libraries/validation/049.php b/user_guide_src/source/libraries/validation/049.php
new file mode 100644
index 000000000000..9a735c4c9d7e
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/049.php
@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Validation;
+
+use App\ValueObject\Name;
+
+class UserRules
+{
+    public function valid_name($name, ?string &$error = null)
+    {
+        if (! $name instanceof Name) {
+            $error = 'The name should be Name::class.';
+
+            return false;
+        }
+
+        if ($name->value === '') {
+            $error = 'The name should not be empty.';
+
+            return false;
+        }
+
+        return true;
+    }
+}
diff --git a/user_guide_src/source/libraries/validation/050.php b/user_guide_src/source/libraries/validation/050.php
new file mode 100644
index 000000000000..8e2385e940f3
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/050.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Config;
+
+use App\Validation\UserRules;
+use CodeIgniter\Config\BaseConfig;
+
+class Validation extends BaseConfig
+{
+    public array $ruleSets = [
+        // ...
+        UserRules::class,
+    ];
+
+    // ...
+}
diff --git a/user_guide_src/source/libraries/validation/051.php b/user_guide_src/source/libraries/validation/051.php
new file mode 100644
index 000000000000..bb3fd5183960
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/051.php
@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Entity;
+
+use App\ValueObject\Name;
+use DomainException;
+
+class User
+{
+    public Name $name;
+    public string $createdAt;
+
+    public function __construct(array $data = [])
+    {
+        if (! service('validation')->validateData($data, [
+            'name'       => 'required|valid_name',
+            'created_at' => 'valid_date[d/m/Y]',
+        ])) {
+            // The validation failed
+            throw new DomainException('Invalid data for "User"');
+        }
+
+        // Working with allowed data
+        $this->name      = $data['name'];
+        $this->createdAt = $data['created_at'];
+    }
+}
diff --git a/user_guide_src/source/libraries/validation/052.php b/user_guide_src/source/libraries/validation/052.php
new file mode 100644
index 000000000000..234f9ae5557b
--- /dev/null
+++ b/user_guide_src/source/libraries/validation/052.php
@@ -0,0 +1,29 @@
+<?php
+
+namespace App\Controllers;
+
+use App\Entity\User;
+use App\ValueObject\Name;
+use DomainException;
+
+class UserController
+{
+    public function index(): string
+    {
+        $data = [
+            'name'       => new Name('Ivan'),
+            'created_at' => '01/01/2000',
+        ];
+
+        try {
+            $user = new User($data);
+
+            // Hi, Ivan
+            return 'Hi, ' . $user->name->value;
+        } catch (DomainException $e) {
+            echo 'Found errors: ';
+
+            print_r(service('validation')->getErrors());
+        }
+    }
+}