Enhancements to exceptions and BE, LU formatters (#13)

Author: rubentebogt

src/FormatHelper/StripPrefix.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\Postcode\FormatHelper;
+
+/**
+ * Strip country code prefix from postalcode if it is valid.
+ *
+ * In some countries like Belgium or Luxembourg its common to provide a country code prefix in a postalcode,
+ * Although the format is incorrect, many government agencies, businesses and people still use this.
+ * Rather than failing this format into an exception, this helper class strips the prefix off before validating it,
+ * Thus providing you with the correct format without the country code prefix in it.
+ *
+ * @see https://en.wikipedia.org/wiki/Postal_codes_in_Belgium
+ *
+ * @internal
+ */
+trait StripPrefix
+{
+    /**
+     * @param string $postcode
+     * @param string $prefix
+     * @return string
+     */
+    public function stripPrefix(string $postcode, string $prefix): string
+    {
+        $prefixLength = strlen($prefix);
+
+        if (substr($postcode, 0, $prefixLength) === $prefix) {
+            $postcode = substr($postcode, $prefixLength);
+        }
+
+        return $postcode;
+    }
+}

src/Formatter/ATFormatter.php

@@ -5,6 +5,7 @@
 namespace Brick\Postcode\Formatter;
 
 use Brick\Postcode\CountryPostcodeFormatter;
+use Brick\Postcode\FormatHelper\StripPrefix;
 
 /**
  * Validates and formats postcodes in Austria.
@@ -16,8 +17,12 @@
  */
 class ATFormatter implements CountryPostcodeFormatter
 {
+    use StripPrefix;
+
     public function format(string $postcode) : ?string
     {
+        $postcode = $this->stripPrefix($postcode, 'A');
+
         if (preg_match('/^[1-9][0-9]{3}$/', $postcode) !== 1) {
             return null;
         }

src/Formatter/BEFormatter.php

@@ -5,6 +5,7 @@
 namespace Brick\Postcode\Formatter;
 
 use Brick\Postcode\CountryPostcodeFormatter;
+use Brick\Postcode\FormatHelper\StripPrefix;
 
 /**
  * Validates and formats postcodes in Belgium.
@@ -16,8 +17,12 @@
  */
 class BEFormatter implements CountryPostcodeFormatter
 {
+    use StripPrefix;
+
     public function format(string $postcode) : ?string
     {
+        $postcode = $this->stripPrefix($postcode, 'B');
+
         if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {
             return null;
         }

src/Formatter/LUFormatter.php

@@ -5,6 +5,7 @@
 namespace Brick\Postcode\Formatter;
 
 use Brick\Postcode\CountryPostcodeFormatter;
+use Brick\Postcode\FormatHelper\StripPrefix;
 
 /**
  * Validates and formats postcodes in Luxembourg.
@@ -16,8 +17,12 @@
  */
 class LUFormatter implements CountryPostcodeFormatter
 {
+    use StripPrefix;
+
     public function format(string $postcode) : ?string
     {
+        $postcode = $this->stripPrefix($postcode, 'L');
+
         if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {
             return null;
         }

src/InvalidPostcodeException.php

@@ -9,4 +9,39 @@
  */
 class InvalidPostcodeException extends \Exception
 {
+    protected string $postcode;
+    protected string $country;
+
+    /**
+     * Construct exception thrown when trying to format an invalid postcode.
+     *
+     * @param string $postcode
+     * @param string $country
+     */
+    public function __construct(string $postcode, string $country)
+    {
+        parent::__construct('Invalid postcode: ' . $postcode);
+        $this->postcode = $postcode;
+        $this->country = $country;
+    }
+
+    /**
+     * Get the invalid postcode associated with this exception.
+     *
+     * @return string
+     */
+    public function getPostcode(): string
+    {
+        return $this->postcode;
+    }
+
+    /**
+     * Get the country ISO2 code associated with this exception.
+     *
+     * @return string
+     */
+    public function getCountry(): string
+    {
+        return $this->country;
+    }
 }

src/PostcodeFormatter.php

@@ -38,17 +38,17 @@ public function format(string $country, string $postcode) : string
         $formatter = $this->getFormatter($country);
 
         if ($formatter === null) {
-            throw new UnknownCountryException('Unknown country: ' . $country);
+            throw new UnknownCountryException($country);
         }
 
         if (preg_match('/^[A-Z0-9]+$/', $postcode) !== 1) {
-            throw new InvalidPostcodeException('Invalid postcode: ' . $postcode);
+            throw new InvalidPostcodeException($postcode, $country);
         }
 
         $formatted = $formatter->format($postcode);
 
         if ($formatted === null) {
-            throw new InvalidPostcodeException('Invalid postcode: ' . $postcode);
+            throw new InvalidPostcodeException($postcode, $country);
         }
 
         return $formatted;

src/UnknownCountryException.php

@@ -9,4 +9,26 @@
  */
 class UnknownCountryException extends \Exception
 {
+    protected string $country;
+
+    /**
+     * Construct exception thrown when an unknown country code is provided.
+     *
+     * @param string $country
+     */
+    public function __construct(string $country)
+    {
+        parent::__construct('Unknown country: ' . $country);
+        $this->country = $country;
+    }
+
+    /**
+     * Get the unknown country ISO2 code associated with this exception.
+     *
+     * @return string
+     */
+    public function getCountry(): string
+    {
+        return $this->country;
+    }
 }

tests/Formatter/ATFormatterTest.php

@@ -37,6 +37,9 @@ public function providerFormat() : array
             ['ABCD', null],
             ['ABCDE', null],
             ['ABCDEF', null],
+
+            ['A8084', '8084'],
+            ['X8084', null],
         ];
     }
 }

tests/Formatter/BEFormatterTest.php

@@ -36,6 +36,9 @@ public function providerFormat() : array
             ['ABCD', null],
             ['ABCDE', null],
             ['ABCDEF', null],
+
+            ['B8084', '8084'],
+            ['X8084', null],
         ];
     }
 }

tests/Formatter/LUFormatterTest.php

@@ -34,6 +34,9 @@ public function providerFormat() : array
             ['ABC', null],
             ['ABCD', null],
             ['ABCDE', null],
+
+            ['L8084', '8084'],
+            ['X8084', null],
         ];
     }
 }