From 4256c45b6b9c96400b8f372b289be1127495ac56 Mon Sep 17 00:00:00 2001
From: Asko Nomm <asko@bien.ee>
Date: Tue, 22 Feb 2022 18:32:14 +0100
Subject: Swap rules and validators, makes more sense now

---
 src/Validator.php | 88 +++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 62 insertions(+), 26 deletions(-)

(limited to 'src/Validator.php')

diff --git a/src/Validator.php b/src/Validator.php
index e5167ea..72ae8ee 100644
--- a/src/Validator.php
+++ b/src/Validator.php
@@ -6,39 +6,75 @@ namespace Askonomm\Validator;
 
 /**
  * The Validator takes in an array of fields, an array of  
- * validators and optionally an array of rules. If no rules 
- * are provided, default rules will be used instead, which are:
+ * rules and optionally an array of validators. If no validators 
+ * are provided, default validators will be used instead, which are:
  * 
- * - `ValidatorRules::len()`
- * - `ValidatorRules::email()`
- * - `ValidatorRules::required()`
+ * - `Validators::len()`
+ * - `Validators::email()`
+ * - `Validators::required()`
  * 
  * The key of each item in the `$fields` array must correspond to the 
- * the key of each item in the `$validators` array, so that Validator 
+ * the key of each item in the `$rules` array, so that Validator 
  * would know how to connect the two to each other.
  * 
- * The `$validators` must have a value that is a string where the rules
+ * The `$rules` must have a value that is a string where the rules
  * are separated by a `|` character, and each rule must match the key of
- * the rule. Additionally, each rule can take in a modifier, where the name
- * of the rule and the modifier is separated by a `:` character.
+ * the implemented validator, such as `len`, `email` or one that you have 
+ * implemented yourself. Additionally, each rule can take in a modifier, 
+ * where the name of the rule and the modifier is separated by a `:` character.
  * 
- * For example, say we have a rule called `len` which takes a modifier that
- * lets that rule validate the length of a string, in such a case we'd write
- * that rule as `len:8`, which would indicate using a `len` rule and passing 
+ * For example, say we have a validator called `len` which takes a modifier that
+ * lets that validator validate the length of a string, in such a case we'd write
+ * that rule as `len:8`, which would indicate using a `len` validator and passing 
  * a modifier with the value `8` to it. 
  * 
  * Example usage of Validator: 
  * 
  * ```php
  * $fields = ['email' => 'asko@bien.ee'];
- * $validators = ['email' => 'required|email'];
- * $validator = new Validator($fields, $validators);
+ * $rules = ['email' => 'required|email'];
+ * $validator = new Validator($fields, $rules);
  * 
  * if ($validator->fails()) {
  *  return $validator->errors();
  * }
  * ```
  * 
+ * If you want to implement your own validators then simply create 
+ * a data structure that looks like this:
+ * 
+ * ```php
+ * // Create the validator
+ * $validator = [
+ *  'error' => function(string $field, $modifier): string {
+ *      return "${field} had some sort of an error.";
+ *  },
+ *  'validates' => function(string $value, $modifier): bool {
+ *      // validate your $value here and return true if 
+ *      // the validation succeeded, or false if there was
+ *      // an error, in which case the rule's error will be
+ *      // added to the array of errors used by Validator.
+ *  }
+ * ];
+ * 
+ * // Add validator to Validator
+ * $validator = new Validator($fields, $rules, [
+ *  'rule-name' => $validator
+ * ]);
+ * ```
+ * 
+ * If you want to also use the default validators, and add yours as an extra, 
+ * simply join the array of your validators with the array that you get from 
+ * `$validator->defaultValidators()`, for example:
+ * 
+ * ```php
+ * $validators = [
+ *  ...$this->defaultValidators(),
+ *  'rule-name' => $validator,
+ * ]);
+ * 
+ * $validator = new Validator($fields, $rules, $validators);
+ * ```
  * @author Asko Nomm <asko@bien.ee>
  */
 class Validator
@@ -47,32 +83,32 @@ class Validator
 
     public function __construct(
         private array $fields,
-        private array $validators,
-        array $rules = [],
+        private array $rules,
+        array $validators = [],
     ) {
-        if (empty($rules)) {
-            $this->rules = $this->defaultRules();
+        if (empty($validators)) {
+            $this->validators = $this->defaultValidators();
         }
 
         $this->validate();
     }
 
     /**
-     * Returns the default, built-in validation rules.
+     * Returns the default, built-in validators.
      *
      * @return array
      */
-    public function defaultRules(): array
+    public function defaultValidators(): array
     {
         return [
-            'len' => ValidatorRules::len(),
-            'email' => ValidatorRules::email(),
-            'required' => ValidatorRules::required(),
+            'len' => Validators::len(),
+            'email' => Validators::email(),
+            'required' => Validators::required(),
         ];
     }
 
     /**
-     * Runs `$this->validators` over `$this->fields` to construct 
+     * Runs `$this->rules` over `$this->fields` to construct 
      * potential errors that will be stored as an array of strings 
      * in `$this->errors`.
      *
@@ -80,10 +116,10 @@ class Validator
      */
     private function validate(): void
     {
-        foreach ($this->validators as $field => $validator) {
+        foreach ($this->rules as $field => $rule) {
             $value = $this->fields[$field];
 
-            foreach (explode('|', $validator) as $item) {
+            foreach (explode('|', $rule) as $item) {
                 if (str_contains($item, ':')) {
                     [$name, $modifier] = explode(':', $item);
 
-- 
cgit v1.2.3