black/address

PHP 5.4+ library to make working with Address safer, easier, and fun

v1.0.1 2014-11-08 13:04 UTC

Requires

• php: >=5.4.0

Requires (Dev)

• phpspec/phpspec: ~2.0

Suggests

• black/geo: ~1.0
• willdurand/geocoder: ~2.8

MIT

• Alexandre 'pocky' Balmes

• address
• libary
• black-project
• value-object

README

PHP 5.4+ library to make working with Addresses safer, easier, and fun!

Installation

The recommended way to install Address is through Composer:

{
    "require": {
        "black/address": "@stable"
    }
}

Protip: You should browse the black/address page to choose a stable version to use, avoid the @stable meta constraint.

Usage

Usage of this class is simple. A complete Postal address is based on a street (number and name), a postal code and a locality. But we also need region, post office box number and country so a complete Postal address should use all this fields.

We have 3 value objects for a complete Postal Address.

Country

A country is composed by a code and a name. This code is an ISO 3166-1 alpha-2 code and the name is in english.

Exemple

$country = new Address\Country("France", "FR");
echo $country->getName(); // return (string) France

It is possible to create a Country object with two static functions.

$country = Address\Country::buildFromISOCode("FR");

$country = Address\Country::buildFromName("France");

Available functions

• ::buildFromISOCode($code)
• ::buildFromName($name)
• ->getName()
• ->getCode()
• ->getValue()
• ->getValueAsArray()
• ->isEqualTo($country)

Exception

An Address\InvalidCountryException() will be thrown if code or name is not found in Resources\countries.php

Street

A street is composed by a number and a name.

Exemple

$street = new Address\Street(1600, "Amphitheatre Pkwy");
$street->getValue(','); // return (string) 1600, Amphitheatre Pkwy

Available functions

• ->getNumber()
• ->getName()
• ->getValue($separator)
• ->getValueAsArray()
• ->isEqualTo($street)

PostalAddress

PostalAddress is the main Value Object. He needs all the informations but an empty string is allowed.

$street  = new Address\Street(1600, "Amphitheatre Pkwy");
$country = new Address\Country("United States", "US");

$postalAddress = new Address\PostalAddress(
    $street,
    94043,
    "Mountain View",
    "CA",
    23,
    $country
);

Available functions

• ->getStreet()
• ->getStreetName()
• ->getStreetNumber()
• ->getPostalCode()
• ->getLocality()
• ->getRegion()
• ->getPostOfficeBoxNumber()
• ->getCountry()
• ->getCountryCode()
• ->getCountryName()
• ->getValue() Return an array

Formatters

Ok now, you have a complete Postal Address but somewhere in your brain, you say:

Oh fuck, sometimes I don't have any region or post-office box and addresses are not written in France or in US with the same order and...

Don't panic, there is a formatter for that!

Three formatters are available with the same ->format() function:

• Address\Formatter\CountryFormatter
• Address\Formatter\StreetFormatter
• Address\Formatter\PostalAddressFormatter

Here is the mapping:

• Street: %S
• Street name: %n
• Street number: %u
• Postal code: %P
• Locality: %L
• Region: %R
• Post Office Box Number: %B
• Country: %C
• Country code: %C
• Country name: %a

And how to use it:

$street  = new Address\Street(1600, "Amphitheatre Pkwy");
$country = new Address\Country("United States", "US");

$postalAddress = new Address\PostalAddress(
    $street,
    94043,
    "Mountain View",
    "CA",
    23,
    $country
);

$formatter = new Address\PostalAddressFormatter($postalAddress);
echo $formatter->format("%u %n %P %a"); // return 1600 Amphitheatre Pkwy 94043 United States

License

Address is released under the MIT License. See the bundled LICENSE file for details.

Contributing

See CONTRIBUTING file.

Credits

This README is heavily inspired by Geocoder library by the great @willdurand. This guy needs your [PR][3] for the sake of the REST in PHP.

Alexandre "pocky" Balmes [e-mail]. Send me Flattrs if you love my work, buy me gift or hire me!