This package uses Composer, please checkout the composer website for more information.

The following command will install zip-code-validator into your project. It will also add a new entry in your composer.json and update the composer.lock as well.

$ composer require barbieswimcrew/zip-code-validator

This package follows the PSR-4 convention names for its classes, which means you can easily integrate zip-code-validator classes loading in your own autoloader.

For validating a zip code you need to instantiate a new ZipCode class provided by this package to set it as a constraint to your form field, for example:

<?php
//...
$form = $this->createFormBuilder($address)
    ->add('zipcode', TextType::class, [
        'constraints' => [
            new ZipCodeValidator\Constraints\ZipCode([
                'iso' => 'DE'
            ])
        ]
    ])
    ->add('save', SubmitType::class, ['label' => 'Create Task'])
    ->getForm();

Another way would be to use the constraint as an annotation of a class property, for example:

<?php

use ZipCodeValidator\Constraints\ZipCode;

class Address
{
    /**
     * @ZipCode(iso="DE")
     */
    protected $zipCode;
}

You can also use it as a PHP8 Attribute, with parameters passed as an array of options, for example:

<?php

use ZipCodeValidator\Constraints\ZipCode;

class Address
{
    #[ZipCode(['iso'=>'DE'])
    protected $zipCode;
}

Please consider to inject a valid ISO 3166 2-letter country code (e.g. DE, US, FR)!

NOTE: This library validates against known zip code regex patterns and does not validate the existence of a zipcode.

If you have a form, in which the user can select a country, you may want to validate the zip code dynamically. In this case you can use the getter option instead:

<?php

use ZipCodeValidator\Constraints\ZipCode;

class Address
{
    /**
     * @ZipCode(getter="getCountry")
     */
    protected $zipCode;

    protected $country;

    public function getCountry()
    {
        return $this->country;
    }
}

To disable that the validator throws an exception, when the zip code pattern is not available for a country, you can set the strict option to FALSE.

/**
 * @ZipCode(getter="getCountry", strict=false)
 */
protected $zipCode;

The validator will not validate empty strings and null values. To disallow them use the Symfony stock NotNull or NotBlank constraint in addition to ZipCode.

/**
 * @ZipCode(getter="getCountry")
 * @NotBlank 
 */
protected $zipCode;

In case you want to match the zip code in a case insensitive way you have to pass a caseSensitiveCheck parameter with false value via the constructor:

$constraint = new ZipCode([
    'iso' => 'GB', 
    'caseSensitiveCheck' => false
]);

By the default the library is using case sensitive zip code matching.

This repository is distributed under the MIT License (MIT). You can find the whole license text in the LICENSE file.