README

zone

Important: A newer version of the zone functionality is now included directly in the commerceguys/addressing library. This library is deprecated.

A PHP 5.5+ zone management library. Requires commerceguys/addressing.

Zones are territorial groupings mostly used for shipping or tax purposes. For example, a set of shipping rates associated with a zone where the rates become available only if the customer's address matches the zone.

A zone can match other zones, countries, subdivisions (states/provinces/municipalities), postal codes. Postal codes can also be expressed using ranges or regular expressions.

Examples of zones:

• California and Nevada
• Belgium, Netherlands, Luxemburg
• European Union
• Germany and a set of Austrian postal codes (6691, 6991, 6992, 6993)
• Austria without specific postal codes (6691, 6991, 6992, 6993)

Data model

Each zone has zone members. A zone matches the provided address if one of its zone members matches the provided address.

The base interfaces don't impose setters, since they aren't needed by the service classes. Extended interfaces (ZoneEntityInterface, ZoneMemberEntityInterface) are provided for that purpose, as well as matching Zone and ZoneMember classes that can be used as examples or mapped by Doctrine.

The library contains two types of zone members:

• country (matches a country, its subdivisions, included/excluded postal codes)
• zone (matches a zone)

use CommerceGuys\Addressing\Address;
use CommerceGuys\Zone\Model\Zone;
use CommerceGuys\Zone\Model\ZoneMemberCountry;

$zone = new Zone();
$zone->setId('german_vat');
$zone->setName('German VAT');
$zone->setScope('tax');

// Create the German VAT zone (Germany and 4 Austrian postal codes).
$germanyZoneMember = new ZoneMemberCountry();
$germanyZoneMember->setCountryCode('DE');
$zone->addMember($germanyZoneMember);

$austriaZoneMember = new ZoneMemberCountry();
$austriaZoneMember->setCountryCode('AT');
$austriaZoneMember->setIncludedPostalCodes('6691, 6991:6993');
$zone->addMember($austriaZoneMember);

// Check if the provided austrian address matches the German VAT zone.
$austrianAddress = new Address();
$austrianAddress = $austrianAddress
    ->withCountryCode('AT')
    ->withPostalCode('6692');
echo $zone->match($austrianAddress); // true

Matcher

A matcher class is provided for the use case where an address should be matched against all zones in the system, with the matched zones ordered by priority.

use CommerceGuys\Addressing\Address;
use CommerceGuys\Zone\Matcher\ZoneMatcher;
use CommerceGuys\Zone\Repository\ZoneRepository;

// Initialize the default repository which loads zones from json files stored in
// resources/zone. A different repository might load them from the database, etc.
$repository = new ZoneRepository('resources/zone');
$matcher = new ZoneMatcher($repository);

$austrianAddress = new Address();
$austrianAddress = $austrianAddress
    ->withCountryCode('AT')
    ->withPostalCode('6692');

// Get all matching zones.
$zones = $matcher->matchAll($austrianAddress);
// Get all matching zones for the 'tax' scope.
$zones = $matcher->matchAll($austrianAddress, 'tax');

// Get the best matching zone.
$zone = $matcher->match($austrianAddress);
// Get the best matching zone for the 'shipping' scope.
$zone = $matcher->match($austrianAddress, 'shipping');