<?php

namespace CommerceGuys\Addressing\AddressFormat;

/**

* Provides metadata for storing and presenting a country's addresses.

*/

class AddressFormat

{

protected string $countryCode;

protected ?string $locale = null;

protected string $format;

protected ?string $localFormat = null;

protected array $usedFields = [];

/**

* The used fields, grouped by line.

*/

protected array $groupedFields = [];

protected mixed $requiredFields = [];

/**

* The fields that need to be uppercased.

*/

protected array $uppercaseFields = [];

protected array $defaultValues = [];

protected ?string $administrativeAreaType = null;

protected ?string $localityType = null;

protected ?string $dependentLocalityType = null;

protected ?string $postalCodeType = null;

protected ?string $postalCodePattern = null;

protected ?string $postalCodePrefix = null;

/**

* The subdivision depth.

*

* @deprecated Use $subdivisionDataFields instead.

*/

protected int $subdivisionDepth = 0;

/**

* The subdivision data fields.

*

* An array of field names for which there is predefined subdivision data.

* For example: ['administrativeArea', 'locality']

*/

protected array $subdivisionDataFields = [];

/**

* @throws \ReflectionException

*/

public function __construct(array $definition)

{

// Validate the presence of required properties.

foreach (['country_code', 'format'] as $requiredProperty) {

if (empty($definition[$requiredProperty])) {

throw new \InvalidArgumentException(sprintf('Missing required property %s.', $requiredProperty));

}

}

$this->countryCode = $definition['country_code'];

$this->locale = $definition['locale'] ?? null;

$this->format = $definition['format'];

$this->localFormat = $definition['local_format'] ?? null;

if (isset($definition['required_fields'])) {

AddressField::assertAllExist($definition['required_fields']);

$this->requiredFields = $definition['required_fields'];

}

if (isset($definition['default_values'])) {

AddressField::assertAllExist(array_keys($definition['default_values']));

$this->defaultValues = $definition['default_values'];

}

if (isset($definition['uppercase_fields'])) {

AddressField::assertAllExist($definition['uppercase_fields']);

$this->uppercaseFields = $definition['uppercase_fields'];

}

if (isset($definition['subdivision_data_fields'])) {

AddressField::assertAllExist($definition['subdivision_data_fields']);

$this->subdivisionDataFields = $definition['subdivision_data_fields'];

// Set subdivision depth based on the count of data fields present in the format.

$this->subdivisionDepth = count(array_intersect($this->subdivisionDataFields, $this->getUsedSubdivisionFields()));

} elseif (isset($definition['subdivision_depth'])) {

// Backwards compatibility: convert subdivision_depth to subdivision_data_fields.

$this->subdivisionDepth = $definition['subdivision_depth'];

$availableFields = [

AddressField::ADMINISTRATIVE_AREA,

AddressField::LOCALITY,

AddressField::DEPENDENT_LOCALITY,

];

$this->subdivisionDataFields = array_slice($availableFields, 0, $this->subdivisionDepth);

}

$usedFields = $this->getUsedFields();

if (in_array(AddressField::ADMINISTRATIVE_AREA, $usedFields)) {

if (isset($definition['administrative_area_type'])) {

AdministrativeAreaType::assertExists($definition['administrative_area_type']);

$this->administrativeAreaType = $definition['administrative_area_type'];

}

}

if (in_array(AddressField::LOCALITY, $usedFields)) {

if (isset($definition['locality_type'])) {

LocalityType::assertExists($definition['locality_type']);

$this->localityType = $definition['locality_type'];

}

}

if (in_array(AddressField::DEPENDENT_LOCALITY, $usedFields)) {

if (isset($definition['dependent_locality_type'])) {

DependentLocalityType::assertExists($definition['dependent_locality_type']);

$this->dependentLocalityType = $definition['dependent_locality_type'];

}

}

if (in_array(AddressField::POSTAL_CODE, $usedFields)) {

if (isset($definition['postal_code_type'])) {

PostalCodeType::assertExists($definition['postal_code_type']);

$this->postalCodeType = $definition['postal_code_type'];

}

$this->postalCodePattern = $definition['postal_code_pattern'] ?? null;

$this->postalCodePrefix = $definition['postal_code_prefix'] ?? null;

}

}

/**

* Gets the two-letter country code.

*

* This is a CLDR country code, since CLDR includes additional countries

* for addressing purposes, such as Canary Islands (IC).

*

* @return string The two-letter country code.

*/

public function getCountryCode(): string

{

return $this->countryCode;

}

/**

* Gets the locale.

*

* Only defined if the country has a local format.

*

* @return string|null The locale, if defined.

*/

public function getLocale(): ?string

{

return $this->locale;

}

/**

* Gets the format string.

*

* Defines the layout of an address, and consists of tokens (address fields

* prefixed with a '%') separated by unix newlines (\n).

* Example:

* <code>

* %givenName %familyName

* %organization

* %addressLine1

* %addressLine2

* %addressLine3

* %locality %administrativeArea %postalCode

* </code>

*

* @return string The format string.

*/

public function getFormat(): string

{

return $this->format;

}

/**

* Gets the local format string.

*

* Defined for countries that use a different ordering of fields when the

* address is entered in the native script. For example, China uses a

* major-to-minor format (country first, name last) when the address

* is entered in Chinese.

*

* @return string|null The local format string, if defined.

*/

public function getLocalFormat(): ?string

{

return $this->localFormat;

}

/**

* Gets the list of used fields.

*

* @return array An array of address fields.

* @throws \ReflectionException

*/

public function getUsedFields(): array

{

if (empty($this->usedFields)) {

$this->usedFields = [];

foreach (AddressField::getAll() as $field) {

if (str_contains($this->format, '%' . $field)) {

$this->usedFields[] = $field;

}

}

}

return $this->usedFields;

}

/**

* Gets the list of used subdivision fields.

*

* @throws \ReflectionException

*/

public function getUsedSubdivisionFields(): array

{

$fields = [

AddressField::ADMINISTRATIVE_AREA,

AddressField::LOCALITY,

AddressField::DEPENDENT_LOCALITY,

];

// Remove fields not used by the format, and reset the keys.

$fields = array_intersect($fields, $this->getUsedFields());

return array_values($fields);

}

/**

* Gets the subdivision data fields.

*

* Returns the list of subdivision fields for which there is predefined data.

* This is more precise than getUsedSubdivisionFields() which returns all

* subdivision fields used by the format, regardless of whether data exists.

*

* @return array An array of subdivision field names, such as:

* ['administrativeArea']

* ['administrativeArea', 'locality']

* ['administrativeArea', 'locality', 'dependentLocality']

*/

public function getSubdivisionDataFields(): array

{

return $this->subdivisionDataFields;

}

/**

* Gets the list of required fields.

*

* @return AddressField[]

*/

public function getRequiredFields(): array

{

return $this->requiredFields;

}

/**

* Gets the list of fields that need to be uppercased.

*

* @return AddressField[]

*/

public function getUppercaseFields(): array

{

return $this->uppercaseFields;

}

/**

* Gets the default values.

*

* @return array The default values, keyed by field name.

*/

public function getDefaultValues(): array

{

return $this->defaultValues;

}

/**

* Gets the administrative area type.

*

* Used for presenting the correct label to the end-user.

*

* @return string|null The administrative area type, or null if the

* administrative area field isn't used.

*/

public function getAdministrativeAreaType(): ?string

{

return $this->administrativeAreaType;

}

/**

* Gets the locality type.

*

* Used for presenting the correct label to the end-user.

*

* @return string|null The locality type, or null if the locality field

* isn't used.

*/

public function getLocalityType(): ?string

{

return $this->localityType;

}

/**

* Gets the dependent locality type.

*

* Used for presenting the correct label to the end-user.

*

* @return string|null The dependent locality type, or null if the

* dependent locality field isn't used.

*/

public function getDependentLocalityType(): ?string

{

return $this->dependentLocalityType;

}

/**

* Gets the postal code type.

*

* Used for presenting the correct label to the end-user.

*

* @return string|null The postal code type, or null if the postal code

* field isn't used.

*/

public function getPostalCodeType(): ?string

{

return $this->postalCodeType;

}

/**

* Gets the postal code pattern.

*

* This is a regular expression pattern used to validate postal codes.

* Ignored if a subdivision defines its own full postal code pattern

* (E.g. Hong Kong when specified as a Chinese province).

*

* @return string|null The postal code pattern.

*/

public function getPostalCodePattern(): ?string

{

return $this->postalCodePattern;

}

/**

* Gets the postal code prefix.

*

* The prefix is optional and added to postal codes only when formatting

* an address for international mailing, as recommended by postal services.

*

* @return string|null The postal code prefix.

*/

public function getPostalCodePrefix(): ?string

{

return $this->postalCodePrefix;

}

/**

* Gets the subdivision depth.

*

* Indicates the number of levels of predefined subdivisions.

*

* @deprecated Use getSubdivisionDataFields() instead.

*

* @return int The subdivision depth. Possible values:

* 0: no subdivisions have been predefined.

* 1: administrative areas.

* 2: administrative areas, localities.

* 3: administrative areas, localities, dependent localities.

*/

public function getSubdivisionDepth(): int

{

return $this->subdivisionDepth;

}

}