PHP 5.4+ library to make working with Addresses safer, easier, and fun!
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 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.
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
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 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 arrayOk 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:
Here is the mapping:
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
Address is released under the MIT License. See the bundled LICENSE file for details.
See CONTRIBUTING file.
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 [email protected]. Send me Flattrs if you love my work, buy me gift or hire me!