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

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');

src/Formatter/AUFormatter.php

@@ -18,6 +18,11 @@
  */
 final class AUFormatter 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/AXFormatter.php

@@ -22,6 +22,11 @@
  */
 final class AXFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcodes consist of 5 digits, starting with 22.';
+    }
+
     public function format(string $postcode): ?string
     {
         $length = strlen($postcode);

src/Formatter/AZFormatter.php

@@ -21,6 +21,11 @@
  */
 final class AZFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'The postcode format is AZ NNNN, where N represents a digit.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (str_starts_with($postcode, 'AZ')) {

src/Formatter/BAFormatter.php

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

src/Formatter/BBFormatter.php

@@ -21,6 +21,11 @@
  */
 final class BBFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postal codes in Barbados are 5 digit numeric, with BB prefix.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (str_starts_with($postcode, 'BB')) {

src/Formatter/BDFormatter.php

@@ -18,6 +18,11 @@
  */
 final class BDFormatter 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/BEFormatter.php

@@ -21,6 +21,11 @@ final class BEFormatter implements CountryPostcodeFormatter
 {
     use StripPrefix;
 
+    public function hint(): string
+    {
+        return 'Postcodes consist of 4 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         $postcode = $this->stripPrefix($postcode, 'B');

src/Formatter/BGFormatter.php

@@ -18,6 +18,11 @@
  */
 final class BGFormatter 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/BHFormatter.php

@@ -18,6 +18,11 @@
  */
 final class BHFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Valid post code numbers are 101 to 1216 with gaps in the range. Known as block number formally.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^(1?[0-9])([0-9]{2})$/', $postcode, $matches) !== 1) {

src/Formatter/BLFormatter.php

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

src/Formatter/BMFormatter.php

@@ -18,6 +18,11 @@
  */
 final class BMFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcode formats are AA NN for street addresses, AA AA for P.O. Box addresses (A=letter, N=digit).';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^([A-Z]{2})([A-Z]{2}|[0-9]{2})$/', $postcode, $matches) !== 1) {

src/Formatter/BNFormatter.php

@@ -18,6 +18,11 @@
  */
 final class BNFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postcode format is two letters followed by 4 digits, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[A-Z]{2}[0-9]{4}$/', $postcode, $matches) !== 1) {

src/Formatter/BRFormatter.php

@@ -20,6 +20,11 @@
  */
 final class BRFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Format is 5 digits, hyphen, 3 digits.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{8}$/', $postcode) !== 1) {

src/Formatter/BTFormatter.php

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

src/Formatter/BYFormatter.php

@@ -17,6 +17,11 @@
  */
 final class BYFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postal codes in Belarus are 6 digit numeric.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{6}$/', $postcode) !== 1) {

src/Formatter/CAFormatter.php

@@ -21,6 +21,11 @@
  */
 final class CAFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'The format is ANA NAN, where A is a letter and N is a digit.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^([ABCEGHJ-NPRSTV-Z][0-9]){3}$/', $postcode) !== 1) {

src/Formatter/CCFormatter.php

@@ -17,6 +17,11 @@
  */
 final class CCFormatter 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/CHFormatter.php

@@ -18,6 +18,11 @@
  */
 final class CHFormatter 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/CLFormatter.php

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

src/Formatter/CNFormatter.php

@@ -19,6 +19,11 @@
  */
 final class CNFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'China Post uses a six-digit all-numerical system, without separator.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]{6}$/', $postcode) !== 1) {

src/Formatter/COFormatter.php

@@ -33,6 +33,11 @@ final class COFormatter implements CountryPostcodeFormatter
         '99',
     ];
 
+    public function hint(): string
+    {
+        return 'Postal codes in Colombia are 6 digit numeric.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^\d{2}(?!0000)\d{4}$/', $postcode) !== 1) {

src/Formatter/CRFormatter.php

@@ -21,6 +21,11 @@
  */
 final class CRFormatter implements CountryPostcodeFormatter
 {
+    public function hint(): string
+    {
+        return 'Postal codes in Costa Rica are 5 digit numeric.';
+    }
+
     public function format(string $postcode): ?string
     {
         if (preg_match('/^[0-9]+$/', $postcode) !== 1) {

src/Formatter/CUFormatter.php

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