addressing
v2.2.2
Uma biblioteca de endereçamento PHP 8.0+, alimentada por CLDR e dados de endereço do Google.
Manipula endereços postais, com o objetivo de identificar a localização precisa do destinatário para fins de envio ou cobrança.
Características:
Os formatos e subdivisões de endereços foram inicialmente gerados a partir do serviço de dados de endereços do Google e agora pertencem e são mantidos pela biblioteca.
Verifique também commerceguys/intl para idiomas/moedas/formatação de números baseados em CLDR.
A interface de endereço representa um endereço postal, com getters para os seguintes campos:
Os nomes dos campos seguem o padrão OASIS eXtensible Address Language (xAL).
A interface não faz suposições sobre mutabilidade. O aplicativo de implementação pode estender a interface para fornecer setters ou implementar um objeto de valor que usa o estilo PSR-7 com* mutadores ou depende de um AddressBuilder. É fornecido um objeto de valor de endereço padrão que pode ser usado como exemplo ou mapeado pelo Doctrine (de preferência como incorporável).
O formato do endereço fornece as seguintes informações:
O país fornece as seguintes informações:
A subdivisão fornece as seguintes informações:
As subdivisões são hierárquicas e podem ter até três níveis: Área Administrativa -> Localidade -> Localidade Dependente.
use CommerceGuys Addressing AddressFormat AddressFormatRepository ;
use CommerceGuys Addressing Country CountryRepository ;
use CommerceGuys Addressing Subdivision SubdivisionRepository ;
$ countryRepository = new CountryRepository ();
$ addressFormatRepository = new AddressFormatRepository ();
$ subdivisionRepository = new SubdivisionRepository ();
// Get the country list (countryCode => name), in French.
$ countryList = $ countryRepository -> getList ( ' fr-FR ' );
// Get the country object for Brazil.
$ brazil = $ countryRepository -> get ( ' BR ' );
echo $ brazil -> getThreeLetterCode (); // BRA
echo $ brazil -> getName (); // Brazil
echo $ brazil -> getCurrencyCode (); // BRL
print_r ( $ brazil -> getTimezones ());
// Get all country objects.
$ countries = $ countryRepository -> getAll ();
// Get the address format for Brazil.
$ addressFormat = $ addressFormatRepository -> get ( ' BR ' );
// Get the subdivisions for Brazil.
$ states = $ subdivisionRepository -> getAll ([ ' BR ' ]);
foreach ( $ states as $ state ) {
$ municipalities = $ state -> getChildren ();
}
// Get the subdivisions for Brazilian state Ceará.
$ municipalities = $ subdivisionRepository -> getAll ([ ' BR ' , ' CE ' ]);
foreach ( $ municipalities as $ municipality ) {
echo $ municipality -> getName ();
}Os endereços são formatados de acordo com o formato do endereço, em HTML ou texto.
Formata um endereço para exibição, sempre adiciona o nome do país localizado.
use CommerceGuys Addressing Address ;
use CommerceGuys Addressing Formatter DefaultFormatter ;
use CommerceGuys Addressing AddressFormat AddressFormatRepository ;
use CommerceGuys Addressing Country CountryRepository ;
use CommerceGuys Addressing Subdivision SubdivisionRepository ;
$ addressFormatRepository = new AddressFormatRepository ();
$ countryRepository = new CountryRepository ();
$ subdivisionRepository = new SubdivisionRepository ();
$ formatter = new DefaultFormatter ( $ addressFormatRepository , $ countryRepository , $ subdivisionRepository );
// Options passed to the constructor or format() allow turning off
// html rendering, customizing the wrapper element and its attributes.
$ address = new Address ();
$ address = $ address
-> withCountryCode ( ' US ' )
-> withAdministrativeArea ( ' CA ' )
-> withLocality ( ' Mountain View ' )
-> withAddressLine1 ( ' 1098 Alta Ave ' );
echo $ formatter -> format ( $ address );
/** Output:
<p translate="no">
<span class="address-line1">1098 Alta Ave</span><br>
<span class="locality">Mountain View</span>, <span class="administrative-area">CA</span><br>
<span class="country">United States</span>
</p>
**/ Cuida dos campos em letras maiúsculas quando exigido pelo formato (para facilitar a classificação automatizada de mensagens).
Requer a especificação do código do país de origem, permitindo diferenciar entre correio nacional e internacional. No caso de correio nacional, o nome do país não é exibido. No caso de correio internacional:
use CommerceGuys Addressing Address ;
use CommerceGuys Addressing Formatter PostalLabelFormatter ;
use CommerceGuys Addressing AddressFormat AddressFormatRepository ;
use CommerceGuys Addressing Country CountryRepository ;
use CommerceGuys Addressing Subdivision SubdivisionRepository ;
$ addressFormatRepository = new AddressFormatRepository ();
$ countryRepository = new CountryRepository ();
$ subdivisionRepository = new SubdivisionRepository ();
// Defaults to text rendering. Requires passing the "origin_country"
// (e.g. 'FR') to the constructor or to format().
$ formatter = new PostalLabelFormatter ( $ addressFormatRepository , $ countryRepository , $ subdivisionRepository , [ ' locale ' => ' fr ' ]);
$ address = new Address ();
$ address = $ address
-> withCountryCode ( ' US ' )
-> withAdministrativeArea ( ' CA ' )
-> withLocality ( ' Mountain View ' )
-> withAddressLine1 ( ' 1098 Alta Ave ' );
echo $ formatter -> format ( $ address , [ ' origin_country ' => ' FR ' ]);
/** Output:
1098 Alta Ave
MOUNTAIN VIEW, CA 94043
ÉTATS-UNIS - UNITED STATES
**/A validação de endereço depende da biblioteca Symfony Validator.
Verificações realizadas:
use CommerceGuys Addressing Address ;
use CommerceGuys Addressing Validator Constraints AddressFormatConstraint ;
use CommerceGuys Addressing Validator Constraints CountryConstraint ;
use Symfony Component Validator Validation ;
$ address = new Address ( ' FR ' );
$ validator = Validation :: createValidator ();
// Validate the country code, then validate the rest of the address.
$ violations = $ validator -> validate ( $ address -> getCountryCode (), new CountryConstraint ());
if (! $ violations -> count ()) {
$ violations = $ validator -> validate ( $ address , new AddressFormatConstraint ());
}Zonas são agrupamentos territoriais frequentemente usados para fins marítimos ou fiscais. Por exemplo, um conjunto de taxas de envio associadas a uma zona onde as taxas ficam disponíveis apenas se o endereço do cliente pertencer à zona.
Uma zona pode corresponder a países, subdivisões (estados/províncias/municípios), códigos postais. Os códigos postais também podem ser expressos usando intervalos ou expressões regulares.
Exemplos de zonas:
use CommerceGuys Addressing Address ;
use CommerceGuys Addressing Zone Zone ;
// Create the German VAT zone (Germany and 4 Austrian postal codes).
$ zone = new Zone ([
' id ' => ' german_vat ' ,
' label ' => ' German VAT ' ,
' territories ' => [
[ ' country_code ' => ' DE ' ],
[ ' country_code ' => ' AT ' , ' included_postal_codes ' => ' 6691, 6991:6993 ' ],
],
]);
// Check if the provided austrian address matches the German VAT zone.
$ austrianAddress = new Address ();
$ austrianAddress = $ austrianAddress
-> withCountryCode ( ' AT ' )
-> withPostalCode ( ' 6992 ' );
echo $ zone -> match ( $ austrianAddress ); // true
