black/address

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

Address

PHP 5.4+ library to make working with Addresses safer, easier, and fun!, _(*1)

, _(*2)

Installation

The recommended way to install Address is through Composer:, _(*3)

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

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

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., _(*5)

We have 3 value objects for a complete Postal Address., _(*6)

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., _(*7)

Exemple, _(*8)

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

It is possible to create a Country object with two static functions., _(*9)

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

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

Available functions, _(*10)

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

Exception, _(*11)

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

Street

A street is composed by a number and a name., _(*13)

Exemple, _(*14)

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

Available functions, _(*15)

• ->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., _(*16)

$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, _(*17)

• ->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:, _(*18)

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..., _(*19)

Don't panic, there is a formatter for that!, _(*20)

Three formatters are available with the same ->format() function:, _(*21)

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

Here is the mapping:, _(*22)

• 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:, _(*23)

$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., _(*24)

Contributing

See CONTRIBUTING file., _(*25)

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., _(*26)

Alexandre "pocky" Balmes alexandre@lablackroom.com. Send me Flattrs if you love my work, buy me gift or hire me!, _(*27)