Add 'postal_code' validation rule (#140)

Introduced a new validation rule to check the correctness of postal
codes based on country codes. This update also includes the addition of
PostalCode.php for functionality and PostalCodeTest.php for testing.
Schema examples and README file have been updated to reflect this
change.

README.md

@@ -11,11 +11,11 @@
 <!-- auto-update:/top-badges -->
 
 <!-- auto-update:rules-counter -->
-[![Static Badge](https://img.shields.io/badge/Rules-328-green?label=Total%20number%20of%20rules&labelColor=darkgreen&color=gray)](schema-examples/full.yml)
-[![Static Badge](https://img.shields.io/badge/Rules-114-green?label=Cell%20rules&labelColor=blue&color=gray)](src/Rules/Cell)
+[![Static Badge](https://img.shields.io/badge/Rules-329-green?label=Total%20number%20of%20rules&labelColor=darkgreen&color=gray)](schema-examples/full.yml)
+[![Static Badge](https://img.shields.io/badge/Rules-115-green?label=Cell%20rules&labelColor=blue&color=gray)](src/Rules/Cell)
 [![Static Badge](https://img.shields.io/badge/Rules-206-green?label=Aggregate%20rules&labelColor=blue&color=gray)](src/Rules/Aggregate)
 [![Static Badge](https://img.shields.io/badge/Rules-8-green?label=Extra%20checks&labelColor=blue&color=gray)](#extra-checks)
-[![Static Badge](https://img.shields.io/badge/Rules-21/54/9-green?label=Plan%20to%20add&labelColor=gray&color=gray)](tests/schemas/todo.yml)
+[![Static Badge](https://img.shields.io/badge/Rules-20/54/9-green?label=Plan%20to%20add&labelColor=gray&color=gray)](tests/schemas/todo.yml)
 <!-- auto-update:/rules-counter -->
 
 A console utility designed for validating CSV files against a strictly defined schema and validation rules outlined
@@ -527,6 +527,7 @@ columns:
       phone: ALL                        # Validates if the input is a phone number. Specify the country code to validate the phone number for a specific country. Example: "ALL", "US", "BR".".
       is_iban: true                     # IBAN - International Bank Account Number. See: https://en.wikipedia.org/wiki/International_Bank_Account_Number
       is_bic: true                      # Validates a Bank Identifier Code (BIC) according to ISO 9362 standards. See: https://en.wikipedia.org/wiki/ISO_9362
+      postal_code: US                   # Validate postal code by country code (alpha-2). Example: "02179". Extracted from https://www.geonames.org
 
       # Misc
       is_version: true                  # Validates the string as version numbers using Semantic Versioning. Example: "1.2.3".

schema-examples/full.json

@@ -149,6 +149,7 @@
                 "phone"                   : "ALL",
                 "is_iban"                 : true,
                 "is_bic"                  : true,
+                "postal_code"             : "US",
 
                 "is_version"              : true,
                 "is_punct"                : true,

schema-examples/full.php

@@ -166,9 +166,10 @@
                 'is_roman'        => true,
                 'is_luhn'         => true,
 
-                'phone'   => 'ALL',
-                'is_iban' => true,
-                'is_bic'  => true,
+                'phone'       => 'ALL',
+                'is_iban'     => true,
+                'is_bic'      => true,
+                'postal_code' => 'US',
 
                 'is_version'   => true,
                 'is_punct'     => true,

schema-examples/full.yml

@@ -230,6 +230,7 @@ columns:
       phone: ALL                        # Validates if the input is a phone number. Specify the country code to validate the phone number for a specific country. Example: "ALL", "US", "BR".".
       is_iban: true                     # IBAN - International Bank Account Number. See: https://en.wikipedia.org/wiki/International_Bank_Account_Number
       is_bic: true                      # Validates a Bank Identifier Code (BIC) according to ISO 9362 standards. See: https://en.wikipedia.org/wiki/ISO_9362
+      postal_code: US                   # Validate postal code by country code (alpha-2). Example: "02179". Extracted from https://www.geonames.org
 
       # Misc
       is_version: true                  # Validates the string as version numbers using Semantic Versioning. Example: "1.2.3".

schema-examples/full_clean.yml

@@ -177,6 +177,7 @@ columns:
       phone: ALL
       is_iban: true
       is_bic: true
+      postal_code: US
 
       is_version: true
       is_punct: true

src/Rules/Cell/PostalCode.php

@@ -0,0 +1,54 @@
+<?php
+
+/**
+ * JBZoo Toolbox - Csv-Blueprint.
+ *
+ * This file is part of the JBZoo Toolbox project.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license    MIT
+ * @copyright  Copyright (C) JBZoo.com, All rights reserved.
+ * @see        https://github.com/JBZoo/Csv-Blueprint
+ */
+
+declare(strict_types=1);
+
+namespace JBZoo\CsvBlueprint\Rules\Cell;
+
+use Respect\Validation\Validator;
+
+class PostalCode extends AbstractCellRule
+{
+    public function getHelpMeta(): array
+    {
+        return [
+            [],
+            [
+                self::DEFAULT => [
+                    'US',
+                    'Validate postal code by country code (alpha-2). ' .
+                    'Example: "02179". Extracted from https://www.geonames.org',
+                ],
+            ],
+        ];
+    }
+
+    public function validateRule(string $cellValue): ?string
+    {
+        if ($cellValue === '') {
+            return null;
+        }
+
+        $countryCode = $this->getOptionAsString();
+        if ($countryCode === '') {
+            return 'Country code is not defined. Please, set it in the rule options.';
+        }
+
+        if (!Validator::postalCode($countryCode)->validate($cellValue)) {
+            return "Value \"<c>{$cellValue}</c>\" is not a valid postal code for country \"{$countryCode}\".";
+        }
+
+        return null;
+    }
+}

tests/Rules/Cell/PostalCodeTest.php

@@ -0,0 +1,51 @@
+<?php
+
+/**
+ * JBZoo Toolbox - Csv-Blueprint.
+ *
+ * This file is part of the JBZoo Toolbox project.
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @license    MIT
+ * @copyright  Copyright (C) JBZoo.com, All rights reserved.
+ * @see        https://github.com/JBZoo/Csv-Blueprint
+ */
+
+declare(strict_types=1);
+
+namespace JBZoo\PHPUnit\Rules\Cell;
+
+use JBZoo\CsvBlueprint\Rules\Cell\PostalCode;
+use JBZoo\PHPUnit\Rules\TestAbstractCellRule;
+
+use function JBZoo\PHPUnit\isSame;
+
+final class PostalCodeTest extends TestAbstractCellRule
+{
+    protected string $ruleClass = PostalCode::class;
+
+    public function testPositive(): void
+    {
+        $rule = $this->create('BR');
+        isSame('', $rule->test(''));
+        isSame('', $rule->test('02179000'));
+        isSame('', $rule->test('02179-000'));
+    }
+
+    public function testNegative(): void
+    {
+        $rule = $this->create('BR');
+        isSame(
+            'Value "qwerty" is not a valid postal code for country "BR".',
+            $rule->test('qwerty'),
+        );
+
+        $rule = $this->create('QQ');
+        isSame(
+            '"postal_code" at line <red>1</red>, column "prop". ' .
+            'Unexpected error: Cannot validate postal code from "QQ" country.',
+            (string)$rule->validate('qwerty'),
+        );
+    }
+}

tests/schemas/todo.yml

@@ -53,7 +53,6 @@ columns:
       subdivision_code: [ ]           # https://github.com/Respect/Validation/blob/main/docs/rules/SubdivisionCode.md
 
       # ids
-      is_postal_code: country code       # https://github.com/Respect/Validation/blob/main/docs/rules/PostalCode.md
       is_bsn: true
       is_cnh: true
       is_cnpj: true