addressing
v2.2.2
Une bibliothèque d'adressage PHP 8.0+, alimentée par CLDR et les données d'adresse de Google.
Manipule les adresses postales, destinées à identifier un emplacement précis du destinataire à des fins d'expédition ou de facturation.
Caractéristiques:
Les formats d'adresse et les subdivisions ont été initialement générés à partir du service de données d'adresse de Google et sont désormais détenus et gérés par la bibliothèque.
Consultez également commerceguys/intl pour le formatage des langues/devises/nombres basés sur CLDR.
L'interface d'adresse représente une adresse postale, avec des getters pour les champs suivants :
Les noms de champs suivent la norme OASIS eXtensible Address Language (xAL).
L'interface ne fait aucune hypothèse sur la mutabilité. L'application d'implémentation peut étendre l'interface pour fournir des setters, ou implémenter un objet de valeur qui utilise le style PSR-7 avec des mutateurs* ou qui s'appuie sur un AddressBuilder. Un objet de valeur d'adresse par défaut est fourni et peut être utilisé comme exemple ou mappé par Doctrine (de préférence en tant qu'intégrable).
Le format d'adresse fournit les informations suivantes :
Le pays fournit les informations suivantes :
Le lotissement fournit les informations suivantes :
Les subdivisions sont hiérarchiques et peuvent avoir jusqu'à trois niveaux : Zone administrative -> Localité -> Localité dépendante.
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 ();
}Les adresses sont formatées selon le format d'adresse, en HTML ou en texte.
Formate une adresse à afficher, ajoute toujours le nom du pays localisé.
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>
**/ Prend en charge les champs en majuscules lorsque le format l'exige (pour faciliter le tri automatisé du courrier).
Nécessite de spécifier le code du pays d'origine, lui permettant de faire la différence entre le courrier national et international. En cas de courrier national, le nom du pays n'est pas affiché du tout. En cas de courrier international :
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
**/La validation des adresses s'appuie sur la bibliothèque Symfony Validator.
Contrôles effectués :
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 ());
}Les zones sont des groupements territoriaux souvent utilisés à des fins maritimes ou fiscales. Par exemple, un ensemble de tarifs d'expédition associés à une zone où les tarifs ne sont disponibles que si l'adresse du client appartient à la zone.
Une zone peut correspondre à des pays, des subdivisions (états/provinces/municipalités), des codes postaux. Les codes postaux peuvent également être exprimés à l'aide de plages ou d'expressions régulières.
Exemples de zones :
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
