Add hint to formatter, so a hint can be provided if postcode is invalid

Author: lisotton

src/CountryPostcodeFormatter.php

@@ -21,4 +21,11 @@ interface CountryPostcodeFormatter
      * @return string|null The formatted postcode, or NULL if the postcode is invalid.
      */
     public function format(string $postcode): ?string;
+
+    /**
+     * Returns a hint describing the expected postcode format for this country.
+     *
+     * @return string A hint describing the expected postcode format.
+     */
+    public function hint(): string;
 }

src/Formatter/ADFormatter.php

@@ -21,6 +21,11 @@
  */
 final class ADFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcodes consist of the letters AD, followed by 3 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (str_starts_with($postcode, 'AD')) {

src/Formatter/AFFormatter.php

@@ -23,6 +23,11 @@
  */
 final class AFFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcodes consist of 4 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {

src/Formatter/AIFormatter.php

@@ -16,6 +16,11 @@
  */
 final class AIFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Anguilla uses a single postcode for all addresses.';
+    }
+
     public function format(string $postcode): ?string
     {
         if ($postcode === '2640' || $postcode === 'AI2640') {

src/Formatter/ALFormatter.php

@@ -18,6 +18,11 @@
  */
 final class ALFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcodes consist of 4 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {

src/Formatter/AMFormatter.php

@@ -18,6 +18,11 @@
  */
 final class AMFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcodes consist of 4 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{4}$/', $postcode) !== 1) {

src/Formatter/AQFormatter.php

@@ -15,6 +15,11 @@
  */
 final class AQFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'This country uses a single postcode for all addresses.';
+    }
+
     public function format(string $postcode): ?string
     {
         if ($postcode === 'BIQQ1ZZ') {

src/Formatter/ARFormatter.php

@@ -18,6 +18,11 @@
  */
 final class ARFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'The postcode is either 4 digits, or 1 letter + 4 digits + 3 letters, with no separators.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^(([0-9]{4})|([A-Z][0-9]{4}[A-Z]{3}))$/', $postcode) !== 1) {

src/Formatter/ASFormatter.php

@@ -21,6 +21,11 @@
  */
 final class ASFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Mail service in American Samoa is fully integrated with the United States Postal Service.';
+    }
+
     public function format(string $postcode): ?string
     {
         $length = strlen($postcode);

src/Formatter/ATFormatter.php

@@ -21,6 +21,11 @@ final class ATFormatter implements CountryPostcodeFormatter
 {
     use StripPrefix;
 
+    public function hint(): string
+    {
+        return 'Postcodes consist of 4 digits, without separator. The first digit must be 1-9.';
+    }
+
     public function format(string $postcode): ?string
     {
         $postcode = $this->stripPrefix($postcode, 'A');