Add VIN validation rule

README.md

@@ -327,6 +327,18 @@ minus chars are not allowed at the beginning or end.
 
     public Intervention\Validation\Rules\Username::__construct()
 
+### VIN (Vehicle Identification Number)
+
+The field under validation must be a valid Vehicle identification number according to ISO-3779.
+
+    public Intervention\Validation\Rules\Vin::__construct(bool $checkDigit = false)
+
+#### Parameters
+
+**checkDigit**
+
+Optional verification according to the North American check system. Default `false`.
+
 ## Development & Testing
 
 With this package comes a Docker image to build a test suite container. To

phpunit.dist.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/10.5/phpunit.xsd"
+  backupGlobals="false"
+  backupStaticProperties="false"
+  beStrictAboutTestsThatDoNotTestAnything="false"
+  bootstrap="vendor/autoload.php"
+  colors="true"
+  cacheDirectory=".phpunit.cache"
+  displayDetailsOnTestsThatTriggerNotices="true"
+  displayDetailsOnTestsThatTriggerDeprecations="true"
+  displayDetailsOnPhpunitDeprecations="true"
+  displayDetailsOnTestsThatTriggerWarnings="true"
+  processIsolation="false"
+  stopOnFailure="false">
+  <testsuites>
+    <testsuite name="Package Test Suite">
+      <directory>./tests/</directory>
+    </testsuite>
+  </testsuites>
+  <source>
+    <include>
+      <directory>./src/Intervention/Validation/Validator.php</directory>
+    </include>
+  </source>
+</phpunit>

src/Rules/Vin.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Intervention\Validation\Rules;
+
+use Intervention\Validation\AbstractRegexRule;
+
+class Vin extends AbstractRegexRule
+{
+    /**
+     * Create new rule.
+     */
+    public function __construct(protected bool $checkDigit = false)
+    {
+        //
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see AbstractRegexRule::pattern()
+     */
+    protected function pattern(): string
+    {
+        return "/^[A-HJ-NPR-Z0-9]{17}$/";
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see Rule::isValid()
+     */
+    public function isValid(mixed $value): bool
+    {
+        if (!parent::isValid($value)) {
+            return false;
+        }
+
+        if ($this->checkDigit) {
+            return $this->validateCheckDigit((string) $value);
+        }
+
+        return true;
+    }
+
+    /**
+     * Validate the VIN check digit using the North American standard.
+     */
+    private function validateCheckDigit(string $vin): bool
+    {
+        // weights for each position (position 8 has weight 0 as it's the check digit)
+        $weights = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];
+
+        // transliteration values for letters
+        $transliteration = [
+            'A' => 1, 'B' => 2, 'C' => 3, 'D' => 4, 'E' => 5, 'F' => 6, 'G' => 7, 'H' => 8,
+            'J' => 1, 'K' => 2, 'L' => 3, 'M' => 4, 'N' => 5, 'P' => 7, 'R' => 9, 'S' => 2,
+            'T' => 3, 'U' => 4, 'V' => 5, 'W' => 6, 'X' => 7, 'Y' => 8, 'Z' => 9,
+        ];
+
+        $sum = 0;
+        foreach (str_split($vin) as $i => $char) {
+            $value = is_numeric($char) ? (int) $char : $transliteration[$char];
+            $sum += $value * $weights[$i];
+        }
+
+        $checkDigit = $sum % 11;
+        $expectedCheckDigit = $checkDigit === 10 ? 'X' : (string) $checkDigit;
+
+        return $vin[8] === $expectedCheckDigit;
+    }
+}

tests/Rules/VinTest.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Intervention\Validation\Tests\Rules;
+
+use Generator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use Intervention\Validation\Rules\Vin;
+use PHPUnit\Framework\TestCase;
+
+final class VinTest extends TestCase
+{
+    #[DataProvider('dataProvider')]
+    public function testValidation(bool $result, string $value): void
+    {
+        $valid = (new Vin())->isValid($value);
+        $this->assertEquals($result, $valid);
+    }
+
+    #[DataProvider('dataProviderCheckDigit')]
+    public function testValidationCheckDigit(bool $result, string $value): void
+    {
+        $valid = (new Vin(true))->isValid($value);
+        $this->assertEquals($result, $valid);
+    }
+
+    public static function dataProvider(): Generator
+    {
+        yield [true, 'WP0ZZZ99ZTS392124'];
+        yield [true, '5GZCZ43D13S812715'];
+        yield [true, 'KLATF08Y1VB363636'];
+        yield [true, 'SGZCZ43D13S812715'];
+        yield [true, 'W0L000051T2123456'];
+        yield [true, 'WDD1690071J236589'];
+        yield [true, 'WVWZZZ1JZ3W386752'];
+        yield [false, 'WVWZZZ1OZ3W386752'];
+    }
+
+    public static function dataProviderCheckDigit(): Generator
+    {
+        yield [true, '5GZCZ43D13S812715'];
+        yield [false, 'WP0ZZZ99ZTS392124'];
+        yield [false, 'KLATF08Y1VB363636'];
+        yield [false, 'SGZCZ43D13S812715'];
+        yield [false, 'W0L000051T2123456'];
+        yield [false, 'WDD1690071J236589'];
+        yield [false, 'WVWZZZ1JZ3W386752'];
+        yield [false, 'WVWZZZ1OZ3W386752'];
+    }
+}