Correct handling of localized addresses

[ahukkanen]

Background

Concrete5 has shipped with the address attribute for as long as I can remember. As good as the default attribute works for the North American countries, or any other countries that have states/provinces, it does not currently consider countries that do not generally use the states provinces for the address fields. It also does not consider country specific formatting of addresses.

Every time we've needed the address attribute anywhere, we've always needed to customize it for each and every project. This just does not feel correct as many other things work well out of the box. We just recently finished a project where we then noticed it was not possible to enter location data because of the required state/province field (well, it's possible but requires to put something unnecessary in that field which we are not even displaying).

Problem

The main problems I want to solve with the current address attribute:

• The state/province field should be optional for countries that do not require it.
• The state/province field should be hidden for countries that do not use it at all.
• The address output formatting should be specific to the country for which that address is.

For example, the following US address would format correctly with the default address attribute, as this is the format it is currently designed for:

1234 SE Street View
Suite 301
Portland, Oregon 98101
United States

But the following address would format incorrectly with the default address attribute (correct formatting below):

Veneentekijäntie 4 A
00210 Helsinki
Finland

Solution

Google has been kind enough to open their address validation metadata for public and they themselves are using it in all sorts of applications, including Chrome.

With this metadata, it is possible to:

• Define which address fields are used for each country
• Define which address fields are required for each country
• Define what the address output should look like for each country

This has also been nicely packaged together for PHP in the commerceguys/addressing project. People from Google have particularly noted that there are no restrictions on the data and it can be included in this particular PHP library.

My suggestion is to integrate this library to concrete5 and let the address attribute get the necessary information from that library. I have a reference implementation ready that I will be shortly opening a PR for.

I believe this would fit well with the other localization functionality already baked in (such as CLDR through Punic).

Further Information

This is something that I would believe bothers everyone needing to deal with addresses and who is outside of the North American countries (or any other place without states/provinces, where the output formatting could still differ).

Just for reference, some information how many people may get annoyed by modifying the address attribute that currently ships with concrete5:

• Countries/territories with the state/province field required: 36
• Countries/territories with the state/province field used (required + optional): 73 (including the 36 listed above)
• Countries/territories without either one: 132

This data was extracted using the PHP library linked above.

[ahukkanen]

PR available at #7944.

[ahukkanen]

Here's also some documentation on how to use the new feature if you are using it outside of the address attribute. The address attribute itself works out of the box preserving the backwards compatibility with the components it was using before as well as preserving the same address output format as was defined previously by concrete5.

Documentation

With all of the documentation examples you will need the address format service to be available:

<?php
$af = Core::make('Concrete\Core\Localization\Service\AddressFormat');
?>

Format an address with HTML

<p>Our address is:</p>
<?php
echo $af->format([
    'address1' => '123 Fake St.',
    'city' => 'Portland',
    'state_province' => 'OR',
    'country' => 'US',
    'postal_code' => '90000',
]);
?>

Output will be:

<p>Our address is:</p>
<div class="ccm-address-text">
<span class="address-line1">123 Fake St.</span><br>
<span class="locality">Portland</span>, <span class="administrative-area">Oregon</span> <span class="postal-code">90000</span><br>
<span class="country">United States</span>
</div>

Format an address with text

<?php
echo 'Our address is:' . "\n";
echo $af->format([
    'address1' => '123 Fake St.',
    'city' => 'Portland',
    'state_province' => 'OR',
    'country' => 'US',
    'postal_code' => '90000',
], 'text');
?>

Output will be:

Our address is:
123 Fake St.
Portland, Oregon 90000
United States

Format an address outside of US

<?php
echo 'Our address is:' . "\n";
echo $af->format([
    'address1' => 'Olematonkatu 1 A',
    'city' => 'Helsinki',
    'country' => 'FI',
    'postal_code' => '00100',
], 'text');
?>

Output will be:

Our address is:
Olematonkatu 1 A
00100 Helsinki
Finland

Format the address country with a specific locale

<?php
echo 'Our address is:' . "\n";
echo $af->format([
    'address1' => '123 Fake St.',
    'city' => 'Portland',
    'state_province' => 'OR',
    'country' => 'US',
    'postal_code' => '90000',
], 'text', 'fi_FI');
?>

Output will be:

Our address is:
123 Fake St.
Portland, Oregon 90000
Yhdysvallat

Default locale is the currently active locale.

Get used address fields for a country

<?php
echo 'Used fields in the US:' . "\n";
foreach ($af->getCountryAddressUsedFields('US') as $field) {
    echo $field . "\n";
}
?>

Output will be:

Used fields in the US:
address1
address2
city
postal_code
state_province

Get required address fields for a country

<?php
echo 'Required fields in the US:' . "\n";
foreach ($af->getCountryAddressRequiredFields('US') as $field) {
    echo $field . "\n";
}
?>

Output will be:

Required fields in the US:
address1
city
postal_code
state_province

[ahukkanen]

Here's also few screenshots to illustrate how this affects the users who are filling the addresses:

[aembler]

Thanks!

[hissy]

I'm very happy to hear address format localization improved.
However, there's one more issue exists in address format in Japan.

<?php
echo 'Our address is:' . "\n";
echo $af->format([
    'address1' => '１丁目１３番地',
    'city' => '千代田区',
    'state_province' => '東京都',
    'country' => 'JP',
    'postal_code' => '101-0054',
], 'text');
?>

Output should be:

Our address is:
日本
〒101-0054
東京都千代田区１丁目１３番地

Yes, the order of address segments is reversed in Japan.
Can we fix this issue also?

[ahukkanen]

@hissy #8030 should fix that issue.

However, the Google metadata suggests the address line should be on its own line as defined by:
https://www.gstatic.com/chrome/autofill/libaddressinput/chromium-i18n/ssl-address/data/JP

So the output format of the example address you gave would be:

日本
〒101-0054
東京都千代田区
１丁目１３番地

If you think this is incorrect, you'll need to report this issue upstream to:
https://github.com/google/libaddressinput/issues

That is actually the repo for the C++/Java implementation of the same thing but it seems to be the only "official" place to report these issues (as other people have done as well).

[hissy]

日本
〒101-0054
東京都千代田区
１丁目１３番地

This format is really nice for us. Super cool! Thank you!