addressing
v2.2.2
مكتبة عناوين PHP 8.0+، مدعومة ببيانات عناوين CLDR وGoogle.
التلاعب بالعناوين البريدية، بهدف تحديد موقع المستلم الدقيق لأغراض الشحن أو الفوترة.
سمات:
تم إنشاء تنسيقات العناوين والأقسام الفرعية في البداية من خدمة بيانات العناوين من Google، وهي الآن مملوكة للمكتبة وتحتفظ بها.
تحقق أيضًا منcommerceguys/intl للتعرف على اللغات/العملات/تنسيق الأرقام التي تدعم CLDR.
تمثل واجهة العنوان عنوانًا بريديًا، مزودًا بأحرف للحقول التالية:
تتبع أسماء الحقول معيار OASIS eXtensible Address Language (xAL).
لا تقدم الواجهة أي افتراضات حول قابلية التغيير. يمكن لتطبيق التنفيذ توسيع الواجهة لتوفير أدوات ضبط، أو تنفيذ كائن قيمة يستخدم إما نمط PSR-7 مع * mutators أو يعتمد على AddressBuilder. يتم توفير كائن قيمة العنوان الافتراضي الذي يمكن استخدامه كمثال، أو تعيينه بواسطة Doctrine (ويفضل أن يكون قابلاً للتضمين).
يوفر تنسيق العنوان المعلومات التالية:
توفر الدولة المعلومات التالية:
ويقدم القسم الفرعي المعلومات التالية:
التقسيمات الفرعية هرمية ويمكن أن تحتوي على ما يصل إلى ثلاثة مستويات: المنطقة الإدارية -> المنطقة المحلية -> المنطقة التابعة.
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 ();
}يتم تنسيق العناوين وفقًا لتنسيق العنوان، بتنسيق HTML أو النص.
يقوم بتنسيق عنوان للعرض، ويضيف دائمًا اسم البلد المحلي.
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>
**/ يعتني بالحقول ذات الأحرف الكبيرة حيثما يتطلب ذلك التنسيق (لتسهيل الفرز الآلي للبريد).
يتطلب تحديد رمز بلد المنشأ، مما يسمح له بالتمييز بين البريد المحلي والدولي. وفي حالة البريد المحلي، لا يتم عرض اسم الدولة على الإطلاق. في حالة البريد الدولي:
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
**/يعتمد التحقق من صحة العنوان على مكتبة Symfony Validator.
الشيكات التي تم إجراؤها:
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 ());
}المناطق هي مجموعات إقليمية تستخدم غالبًا لأغراض الشحن أو الضرائب. على سبيل المثال، مجموعة أسعار الشحن المرتبطة بمنطقة حيث تصبح الأسعار متاحة فقط إذا كان عنوان العميل ينتمي إلى المنطقة.
يمكن أن تتطابق المنطقة مع البلدان والأقسام الفرعية (الولايات/المقاطعات/البلديات) والرموز البريدية. يمكن أيضًا التعبير عن الرموز البريدية باستخدام النطاقات أو التعبيرات العادية.
أمثلة على المناطق:
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
