Refactor exception handling and update comments in code (#159)

This commit refactors exception handling across the code by replacing
generic exception throwing with specific Exception subclasses. It also
includes updates to comments to improve clarity and readability.

README.md

@@ -433,12 +433,12 @@ columns:
       # Format:    https://www.php.net/manual/en/datetime.format.php
       # Parsing:   https://www.php.net/manual/en/function.strtotime.php
       # Timezones: https://www.php.net/manual/en/timezones.php
-      date_min: -100 years              # Example of relative formats
+      date_min: -100 years              # Example of relative past date
       date_greater: -99 days            # Example of relative formats
       date_not: 2006-01-02 15:04:05 -0700 Europe/Rome
       date: 01 Jan 2000                 # You can use any string that can be parsed by the strtotime function
       date_less: now                    # Example of current date and time
-      date_max: +1 day                  # Example of relative formats
+      date_max: +1 day                  # Example of relative future date
       date_format: Y-m-d                # Check strict format of the date.
       is_date: true                     # Accepts arbitrary date format. Is shows error if failed to convert to timestamp.
       is_timezone: true                 # Allow only timezone identifiers. Case-insensitive. Example: "Europe/London", "utc".

docker/build-preloader.php

@@ -14,8 +14,7 @@
 
 declare(strict_types=1);
 
-$require = __DIR__ . '/../vendor/composer/autoload_classmap.php';
-$classes = require $require;
+$classes = include_once __DIR__ . '/../vendor/composer/autoload_classmap.php';
 
 $header = <<<'TEXT'
     <?php

schema-examples/full.yml

@@ -144,12 +144,12 @@ columns:
       # Format:    https://www.php.net/manual/en/datetime.format.php
       # Parsing:   https://www.php.net/manual/en/function.strtotime.php
       # Timezones: https://www.php.net/manual/en/timezones.php
-      date_min: -100 years              # Example of relative formats
+      date_min: -100 years              # Example of relative past date
       date_greater: -99 days            # Example of relative formats
       date_not: 2006-01-02 15:04:05 -0700 Europe/Rome
       date: 01 Jan 2000                 # You can use any string that can be parsed by the strtotime function
       date_less: now                    # Example of current date and time
-      date_max: +1 day                  # Example of relative formats
+      date_max: +1 day                  # Example of relative future date
       date_format: Y-m-d                # Check strict format of the date.
       is_date: true                     # Accepts arbitrary date format. Is shows error if failed to convert to timestamp.
       is_timezone: true                 # Allow only timezone identifiers. Case-insensitive. Example: "Europe/London", "utc".

src/Commands/AbstractValidate.php

@@ -17,7 +17,6 @@
 namespace JBZoo\CsvBlueprint\Commands;
 
 use JBZoo\Cli\CliCommand;
-use JBZoo\CsvBlueprint\Exception;
 use JBZoo\CsvBlueprint\Schema;
 use JBZoo\CsvBlueprint\Utils;
 use JBZoo\CsvBlueprint\Validators\ErrorSuite;

src/Commands/Exception.php

@@ -0,0 +1,21 @@
+<?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\Commands;
+
+class Exception extends \JBZoo\CsvBlueprint\Exception
+{
+}

src/Commands/ValidateCsv.php

@@ -17,7 +17,6 @@
 namespace JBZoo\CsvBlueprint\Commands;
 
 use JBZoo\CsvBlueprint\Csv\CsvFile;
-use JBZoo\CsvBlueprint\Exception;
 use JBZoo\CsvBlueprint\Schema;
 use JBZoo\CsvBlueprint\Utils;
 use JBZoo\CsvBlueprint\Validators\ErrorSuite;

src/Csv/CsvFile.php

@@ -36,7 +36,7 @@ final class CsvFile
     public function __construct(string $csvFilename, null|array|string $csvSchemaFilenameOrArray = null)
     {
         if (\realpath($csvFilename) !== false && \file_exists($csvFilename) === false) {
-            throw new \InvalidArgumentException('File not found: ' . $csvFilename);
+            throw new Exception('File not found: ' . $csvFilename);
         }
 
         $this->csvFilename = $csvFilename;

src/Rules/AbstarctRule.php

@@ -84,7 +84,7 @@ public function validate(array|string $cellValue, int $line = ValidatorColumn::F
                 );
             }
         } else {
-            throw new \RuntimeException('Method "validateRule" not found in ' . static::class);
+            throw new Exception('Method "validateRule" not found in ' . static::class);
         }
 
         return null;

src/Rules/AbstarctRuleCombo.php

@@ -92,28 +92,28 @@ protected static function compare(float $expected, float $actual, string $mode):
             self::EQ      => $expected === $actual,
             self::LESS    => $expected > $actual,
             self::MAX     => $expected >= $actual,
-            default       => throw new \InvalidArgumentException("Unknown mode: {$mode}"),
+            default       => throw new Exception("Unknown mode: {$mode}"),
         };
     }
 
     private function validateCombo(array|string $cellValue): ?string
     {
         if ($this instanceof AbstractCellRuleCombo) {
             if (!\is_string($cellValue)) {
-                throw new \InvalidArgumentException('The value should be a string');
+                throw new Exception('The value should be a string');
             }
 
             return $this->validateComboCell($cellValue, $this->mode);
         }
 
         if ($this instanceof AbstractAggregateRuleCombo) {
             if (!\is_array($cellValue)) {
-                throw new \InvalidArgumentException('The value should be an array of numbers/strings');
+                throw new Exception('The value should be an array of numbers/strings');
             }
 
             return $this->validateComboAggregate($cellValue, $this->mode);
         }
 
-        throw new \LogicException('Unknown rule type: ' . static::class);
+        throw new Exception('Unknown rule type: ' . static::class);
     }
 }

src/Rules/Aggregate/AbstractAggregateRuleCombo.php

@@ -33,7 +33,7 @@ public function getRuleCode(?string $mode = null): string
     protected function getActual(array|string $value): float
     {
         if (\is_string($value)) {
-            throw new \InvalidArgumentException('The value should be an array of numbers/strings');
+            throw new Exception('The value should be an array of numbers/strings');
         }
 
         $result = $this->getActualAggregate($value);

src/Rules/Aggregate/ComboNthNum.php

@@ -67,7 +67,7 @@ protected function getActualAggregate(array $colValues): ?float
         $actual = $colValues[$arrayInd] ?? null;
 
         if ($actual === null) {
-            throw new \RuntimeException(
+            throw new Exception(
                 "The column does not have a line {$realLine}, so the value cannot be checked.",
             );
         }
@@ -79,7 +79,7 @@ private function getParams(): array
     {
         $params = $this->getOptionAsArray();
         if (\count($params) !== self::ARGS) {
-            throw new \RuntimeException(
+            throw new Exception(
                 'The rule expects exactly two arguments: ' .
                 'the first is the line number (without header), the second is the expected value',
             );

src/Rules/Aggregate/ComboPercentile.php

@@ -74,7 +74,7 @@ private function getParams(): array
     {
         $params = $this->getOptionAsArray();
         if (\count($params) !== self::ARGS) {
-            throw new \RuntimeException(
+            throw new Exception(
                 'The rule expects exactly two params: ' .
                 'the first is percentile (P is beet 0.0 and 100.0), the second is the expected value (float)',
             );

src/Rules/Aggregate/ComboQuartiles.php

@@ -85,7 +85,7 @@ private function getType(): string
         $type = $this->getParams()[self::TYPE];
 
         if (!\in_array($type, self::TYPES, true)) {
-            throw new \RuntimeException(
+            throw new Exception(
                 "Unknown quartile type: \"{$type}\". Allowed: " . Utils::printList(self::TYPES, 'green'),
             );
         }
@@ -98,7 +98,7 @@ private function getMethod(): string
         $method = $this->getParams()[self::METHOD];
 
         if (!\in_array($method, self::METHODS, true)) {
-            throw new \RuntimeException(
+            throw new Exception(
                 "Unknown quartile method: \"{$method}\". Allowed: " . Utils::printList(self::METHODS, 'green'),
             );
         }
@@ -110,7 +110,7 @@ private function getParams(): array
     {
         $params = $this->getOptionAsArray();
         if (\count($params) !== self::ARGS) {
-            throw new \RuntimeException(
+            throw new Exception(
                 'The rule expects exactly three params: ' .
                 'method ' . Utils::printList(self::METHODS) . ', ' .
                 'type ' . Utils::printList(self::TYPES) . ', ' .

src/Rules/Aggregate/Exception.php

@@ -0,0 +1,21 @@
+<?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\Aggregate;
+
+class Exception extends \JBZoo\CsvBlueprint\Rules\Exception
+{
+}

src/Rules/Aggregate/Sorted.php

@@ -59,7 +59,7 @@ public function validateRule(array $columnValues): ?string
         try {
             $dir = $this->getDir();
             $method = $this->getMethod();
-        } catch (\RuntimeException $e) {
+        } catch (\Throwable $e) {
             return $e->getMessage();
         }
 
@@ -84,7 +84,7 @@ private function getDir(): string
         $dir = $this->getParams()[self::DIR];
 
         if (!\in_array($dir, self::DIRS, true)) {
-            throw new \RuntimeException(
+            throw new Exception(
                 "Unknown sort direction: \"{$dir}\". Allowed: " . Utils::printList(self::DIRS, 'green'),
             );
         }
@@ -97,7 +97,7 @@ private function getMethod(): int
         $method = $this->getParams()[self::METHOD];
 
         if (!\in_array($method, \array_keys(self::METHODS), true)) {
-            throw new \RuntimeException(
+            throw new Exception(
                 "Unknown sort method: \"{$method}\". Allowed: " . Utils::printList(\array_keys(self::METHODS), 'green'),
             );
         }
@@ -109,7 +109,7 @@ private function getParams(): array
     {
         $params = $this->getOptionAsArray();
         if (\count($params) !== self::ARGS) {
-            throw new \RuntimeException(
+            throw new Exception(
                 'The rule expects exactly two params: ' .
                 'direction ' . Utils::printList(self::DIRS) . ' and ' .
                 'method ' . Utils::printList(\array_keys(self::METHODS)),

src/Rules/Cell/AbstractCellRuleCombo.php

@@ -25,7 +25,7 @@ abstract protected function getActualCell(string $cellValue): float;
     protected function getActual(array|string $value): float
     {
         if (\is_array($value)) {
-            throw new \InvalidArgumentException('This method should not be called with an array');
+            throw new Exception('This method should not be called with an array');
         }
 
         return $this->getActualCell($value);

src/Rules/Cell/ComboDate.php

@@ -35,12 +35,12 @@ public function getHelpMeta(): array
                 'Timezones: https://www.php.net/manual/en/timezones.php',
             ],
             [
-                self::MIN     => ['-100 years', 'Example of relative formats'],
+                self::MIN     => ['-100 years', 'Example of relative past date'],
                 self::GREATER => ['-99 days', 'Example of relative formats'],
                 self::EQ      => ['01 Jan 2000', 'You can use any string that can be parsed by the strtotime function'],
                 self::NOT     => ['2006-01-02 15:04:05 -0700 Europe/Rome'],
                 self::LESS    => ['now', 'Example of current date and time'],
-                self::MAX     => ['+1 day', 'Example of relative formats'],
+                self::MAX     => ['+1 day', 'Example of relative future date'],
             ],
         ];
     }

src/Rules/Cell/ComboDateInterval.php

@@ -98,12 +98,12 @@ private static function dateIntervalToSeconds(string $dateIntervalOrAsString): i
             try {
                 $interval = \DateInterval::createFromDateString($dateIntervalOrAsString);
             } catch (\Exception) {
-                throw new \RuntimeException("Can't parse date interval: {$dateIntervalOrAsString}");
+                throw new Exception("Can't parse date interval: {$dateIntervalOrAsString}");
             }
         }
 
         if (!$interval instanceof \DateInterval) {
-            throw new \RuntimeException("Can't parse date interval: {$dateIntervalOrAsString}");
+            throw new Exception("Can't parse date interval: {$dateIntervalOrAsString}");
         }
 
         $daysPerYear = 365.25;  // Average considering leap years

src/Rules/Cell/ComboPasswordStrength.php

@@ -59,7 +59,7 @@ public static function passwordScore(string $password): int
         }
 
         // Numbers: +1 point if at least one
-        if (\preg_match('/[0-9]/', $password) !== 0) {
+        if (\preg_match('/\d/', $password) !== 0) {
             $score++;
         }
 
@@ -82,8 +82,8 @@ public static function passwordScore(string $password): int
         $deductions += \preg_match_all('/01|12|23|34|45|56|67|78|89|90/', $password);
 
         $deductions += \preg_match_all(
-            '/ab|bc|cd|de|ef|fg|gh|hi|ij|jk|kl|lm|mn|no|op|pq|qr|rs|st|tu|uv|vw|wx|xy|yz/i',
-            $password,
+            '/abc|bcd|cde|def|efg|fgh|ghi|hij|ijk|jkl|klm|lmn|mno|nop|opq|pqr|qrs|rst|stu|tuv|uvw|vwx|wxy|xyz/',
+            \strtolower($password),
         );
 
         if (\preg_match('/qwerty|pass|password/i', $password) !== 0) {

src/Rules/Cell/Exception.php

@@ -0,0 +1,21 @@
+<?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;
+
+class Exception extends \JBZoo\CsvBlueprint\Rules\Exception
+{
+}

src/Rules/Cell/IsHex.php

@@ -34,8 +34,8 @@ public function getHelpMeta(): array
     public function validateRule(string $cellValue): ?string
     {
         if (
-            \preg_match('/^[0-9a-fA-F]+$/i', $cellValue) === 0
-            && \preg_match('/^0x[0-9a-fA-F]+$/i', $cellValue) === 0
+            \preg_match('/^[0-9a-f]+$/i', $cellValue) === 0
+            && \preg_match('/^0x[0-9a-f]+$/i', $cellValue) === 0
         ) {
             return "Value \"<c>{$cellValue}</c>\" is not a valid hexadecimal number. Example: \"0x1A\" or \"1A\"";
         }

src/Rules/Cell/IsTime.php

@@ -39,12 +39,12 @@ public function validateRule(string $cellValue): ?string
         }
 
         $regexs = [
-            '1:59'        => '/^([1-9]|1[0-2]):[0-5][0-9]$/',
-            '23:59'       => '/^(?:2[0-3]|[01][0-9]):[0-5][0-9]$/',
-            '23:59:59'    => '/^(?:2[0-3]|[01]?[0-9]):[0-5][0-9]:[0-5][0-9]$/',
-            '1:59 am'     => '/^([1-9]|1[0-2]):[0-5][0-9]\s?(am|pm)$/i',
-            '12:59 am'    => '/^(1[0-2]|0?[1-9]):[0-5][0-9]\s?(am|pm)$/i',
-            '12:59:59 am' => '/^(1[0-2]|0?[1-9]):[0-5][0-9]:[0-5][0-9]\s?(am|pm)$/i',
+            '1:59'        => '/^([1-9]|1[0-2]):[0-5]\d$/',
+            '23:59'       => '/^(?:2[0-3]|[01]\d):[0-5]\d$/',
+            '23:59:59'    => '/^(?:2[0-3]|[01]?\d):[0-5]\d:[0-5]\d$/',
+            '1:59 am'     => '/^([1-9]|1[0-2]):[0-5]\d\s?(am|pm)$/i',
+            '12:59 am'    => '/^(1[0-2]|0?[1-9]):[0-5]\d\s?(am|pm)$/i',
+            '12:59:59 am' => '/^(1[0-2]|0?[1-9]):[0-5]\d:[0-5]\d\s?(am|pm)$/i',
         ];
 
         foreach ($regexs as $regex) {

src/Rules/Cell/IsTimezoneOffset.php

@@ -34,7 +34,7 @@ public function validateRule(string $cellValue): ?string
             return null;
         }
 
-        if (Utils::testRegex('/^[\+\-](0[0-9]|1[0-4]):([0-5][0-9])$/', $cellValue)) {
+        if (Utils::testRegex('/^[\+\-](0\d|1[0-4]):([0-5]\d)$/', $cellValue)) {
             return "Value \"<c>{$cellValue}</c>\" is not a valid timezone offset. " .
                 'Example: "<green>+03:00</green>".';
         }