Laravel Phone

هاتف Laravel

يضيف وظائف رقم الهاتف إلى Laravel استنادًا إلى منفذ PHP من Libphonenumber بواسطة Google.

جدول المحتويات

• العرض التوضيحي
• تثبيت
• تصديق
• سمة الصب
• فئة فائدة
  • التنسيق
  • معلومات عدد
  • مقارنة المساواة
  • وظيفة المساعد
• اعتبارات قاعدة البيانات

العرض التوضيحي

تحقق من سلوك هذه الحزمة في العرض التوضيحي.

تثبيت

قم بتشغيل الأمر التالي لتثبيت أحدث إصدار قابل للتطبيق من الحزمة:

composer require propaganistas/laravel-phone

يتم اكتشاف مزود الخدمة تلقائيًا بواسطة Laravel.

في دليل اللغات الخاص بك ، أضف ترجمة إضافية في كل ملف لغة validation.php .

 ' phone ' => ' The :attribute field must be a valid number. ' ,

تصديق

استخدم الكلمة الرئيسية phone في صفيف قواعد التحقق من الصحة أو استخدم فئة قواعد PropaganistasLaravelPhoneRulesPhone لتحديد القاعدة بطريقة تعبيرية.

لوضع قيود على البلدان الأصلية المسموح بها ، يمكنك تحديد رموز البلد المسموح بها صراحة.

 ' phonefield '       => ' phone:US,BE ' ,
// ' phonefield '    => ( new Phone )-> country ([ ' US ' , ' BE ' ])

أو لجعل الأمور أكثر ديناميكية ، يمكنك أيضًا المطابقة مع حقل بيانات آخر يحمل رمز البلد. على سبيل المثال ، للحصول على رقم هاتف لمطابقة البلد المقدم من الإقامة. تأكد من أن حقل البلد لديه نفس اسم حقل الهاتف ولكن مع _country Assoded لاكتشاف التلقائي ، أو توفير اسم حقل البلد المخصص الخاص بك كمعلمة للمقحة:

 ' phonefield '            => ' phone ' ,
// ' phonefield '         => ( new Phone )
' phonefield_country '    => ' required_with:phonefield ' ,

 ' phonefield '            => ' phone:custom_country_field ' ,
// ' phonefield '         => ( new Phone )-> countryField ( ' custom_country_field ' )
' custom_country_field '  => ' required_with:phonefield ' ,

ملاحظة: يجب أن تكون رموز البلد ISO 3166-1 Alpha-2 متوافقة .

لدعم أي رقم هاتف صحيح منسق دوليًا بجوار البلدان ذات القائمة البيضاء ، استخدم المعلمة INTERNATIONAL . قد يكون هذا مفيدًا عندما تتوقع أرقامًا منسقة محليًا من بلد معين ولكنك تريد أيضًا قبول أي رقم أجنبي آخر يتم إدخاله بشكل صحيح:

 ' phonefield '            => ' phone:INTERNATIONAL,BE ' ,
// ' phonefield '         => ( new Phone )-> international ()-> country ( ' BE ' )

لتحديد القيود على نوع الرقم ، ما عليك سوى إلحاق الأنواع المسموح بها إلى نهاية المعلمات ، على سبيل المثال:

 ' phonefield '       => ' phone:mobile ' ,
// ' phonefield '    => ( new Phone )-> type ( ' mobile ' )

الأنواع الأكثر شيوعًا هي mobile fixed_line ، ولكن لا تتردد في استخدام أي من الأنواع المحددة هنا.

قم بإعداد نوع مع علامة تعجب لإدراجها السوداء بدلاً من ذلك. لاحظ أنه لا يمكنك أبدًا استخدام أنواع القائمة البيضاء والمدروسة في القائمة السوداء في نفس الوقت.

 ' phonefield '       => ' phone:!mobile ' ,
// ' phonefield '    => ( new Phone )-> notType ( ' mobile ' )

يمكنك أيضًا تمكين التحقق من الصحة المتساهلة باستخدام المعلمة LENIENT . مع تمكين التساهل ، يتم فحص طول الرقم فقط بدلاً من أنماط الناقل الفعلية.

 ' phonefield '       => ' phone:LENIENT ' ,
// ' phonefield '    => ( new Phone )-> lenient ()

سمة الصب

يتم توفير فئتين من الممثلين للصياد التلقائي لسمات النموذج البليغ:

 use Illuminate  Database  Eloquent  Model ;
use Propaganistas  LaravelPhone  Casts  RawPhoneNumberCast ;
use Propaganistas  LaravelPhone  Casts  E164PhoneNumberCast ;

class User extends Model
{
    public $ casts = [
        ' phone_1 ' => RawPhoneNumberCast ::class. ' :BE ' ,
        ' phone_2 ' => E164PhoneNumberCast ::class. ' :BE ' ,
    ];
}

يلقي كلا الفئتين تلقائيًا قيمة قاعدة البيانات إلى كائن فونين للاستخدام لمزيد من الاستخدام في التطبيق الخاص بك.

 $ user -> phone // PhoneNumber object or null

عند تعيين قيمة ، فإن كلاهما يقبلون قيمة السلسلة أو كائن فون. يقوم RawPhoneNumberCast بتوضيح قيمة قاعدة البيانات إلى رقم الإدخال RAW ، بينما يكتب E164PhoneNumberCast رقم هاتف E.164 المنسق إلى قاعدة البيانات.

في حالة RawPhoneNumberCast ، يجب التلميح إلى بلد الهاتف من أجل تحليل الرقم الخام بشكل صحيح في كائن هاتف. في حالة E164PhoneNumberCast والقيمة المراد تعيينها ليست بالفعل في شكل دولي ، يجب التلميح إلى بلد الهاتف من أجل تحوير القيمة بشكل صحيح.

كلا الفئتين يقبلان المعلمات المدلى بها بنفس الطريقة:

1. عندما توجد سمة مشابهة مسموحة ، ولكنها ملائمة بـ _country (على سبيل المثال phone_country) ، سيكتشف طاقم العمل ويستخدمه تلقائيًا.
2. قدم اسم سمة أخرى كمعلمة مصبوب
3. توفير واحد أو عدة رموز البلد كمعلمات يلقي

 public $ casts = [
    ' phone_1 ' => RawPhoneNumberCast ::class. ' :country_field ' ,
    ' phone_2 ' => E164PhoneNumberCast ::class. ' :BE ' ,
];

ملاحظة مهمة: يتوقع كلا الممثلين أرقام هواتف صالحة من أجل التحويل بسلاسة من/كائنات الصوتية. يرجى التحقق من صحة أرقام الهواتف قبل إعدادها على نموذج. ارجع إلى وثائق التحقق لمعرفة كيفية التحقق من صحة أرقام الهواتف.

️ تعيين السمة و E164PhoneNumberCast

نظرًا لطبيعة E164PhoneNumberCast من المتوقع أن يتم تمرير السمة من البلدان الصالحة إذا لم يتم تمرير الرقم بالتنسيق الدولي. نظرًا لأنه يتم تطبيق الممثلين بترتيب القيم المحددة ، تأكد من تعيين سمة البلد قبل تعيين سمة رقم الهاتف. وإلا فإن E164PhoneNumberCast ستواجه قيمة بلد فارغ ويلقي استثناء غير متوقع.

 // Wrong
$ model -> fill ([
    ' phone ' => ' 012 34 56 78 ' ,
    ' phone_country ' => ' BE ' ,
]);

// Correct
$ model -> fill ([
    ' phone_country ' => ' BE ' ,
    ' phone ' => ' 012 34 56 78 ' ,
]);

// Wrong
$ model -> phone = ' 012 34 56 78 ' ;
$ model -> phone_country = ' BE ' ;

// Correct
$ model -> phone_country = ' BE ' ;
$ model -> phone = ' 012 34 56 78 ' ;

فئة فئة الصوتيات

يمكن لف رقم الهاتف في فئة PropaganistasLaravelPhonePhoneNumber لتعزيزه بطرق فائدة مفيدة. من الآمن الرجوع مباشرة إلى هذه الكائنات في طرق العرض أو عند حفظ قاعدة البيانات لأنها ستتحول بأمان إلى تنسيق E.164.

 use Propaganistas  LaravelPhone  PhoneNumber ;

( string ) new PhoneNumber ( ' +3212/34.56.78 ' );                // [phone]
( string ) new PhoneNumber ( ' 012 34 56 78 ' , ' BE ' );            // [phone]

التنسيق

يمكن تنسيق عدد فني بطرق مختلفة:

 $ phone = new PhoneNumber ( ' 012/34.56.78 ' , ' BE ' );

$ phone -> format ( $ format );       // See libphonenumberPhoneNumberFormat
$ phone -> formatE164 ();          // [phone]
$ phone -> formatInternational (); // [phone]
$ phone -> formatRFC3966 ();       // tel:[phone]
$ phone -> formatNational ();      // 012 34 56 78

// Formats so the number can be called straight from the provided country.
$ phone -> formatForCountry ( ' BE ' ); // 012 34 56 78
$ phone -> formatForCountry ( ' NL ' ); // 00 32 12 34 56 78
$ phone -> formatForCountry ( ' US ' ); // 011 32 12 34 56 78

// Formats so the number can be clicked on and called straight from the provided country using a cellphone.
$ phone -> formatForMobileDialingInCountry ( ' BE ' ); // 012345678
$ phone -> formatForMobileDialingInCountry ( ' NL ' ); // [phone]
$ phone -> formatForMobileDialingInCountry ( ' US ' ); // [phone]

معلومات عدد

احصل على بعض المعلومات حول رقم الهاتف:

 $ phone = new PhoneNumber ( ' 012 34 56 78 ' , ' BE ' );

$ phone -> getType ();              // 'fixed_line'
$ phone -> isOfType ( ' fixed_line ' ); // true
$ phone -> getCountry ();           // 'BE'
$ phone -> isOfCountry ( ' BE ' );      // true

مقارنة المساواة

تحقق مما إذا كان رقم هاتف معين (لا) يساوي رقمًا آخر:

 $ phone = new PhoneNumber ( ' 012 34 56 78 ' , ' BE ' );

$ phone -> equals ( ' 012/34.56.76 ' , ' BE ' )       // true
$ phone -> equals ( ' [phone] ' )          // true
$ phone -> equals ( $ anotherPhoneObject )      // true / false

$ phone -> notEquals ( ' 045 67 89 10 ' , ' BE ' )    // true
$ phone -> notEquals ( ' [phone] ' )       // true
$ phone -> notEquals ( $ anotherPhoneObject )   // true / false

وظيفة المساعد

تكشف الحزمة وظيفة المساعد phone() التي تُرجع مثيلًا PropaganistasLaravelPhonePhoneNumber أو السلسلة المنسقة إذا تم توفير $format :

 phone ( $ number , $ country = [], $ format = null )

اعتبارات قاعدة البيانات

إخلاء المسئولية: معالجة رقم الهاتف مختلفة تمامًا في كل تطبيق. وبالتالي فإن الموضوعات المذكورة أدناه تهدف إلى مجموعة من مبتدئين الفكر ؛ لن يتم تقديم الدعم.

لطالما كان تخزين أرقام الهواتف في قاعدة بيانات موضوعًا مضاربة ولا يوجد ببساطة رصاصة فضية. كل هذا يتوقف على متطلبات طلبك. فيما يلي بعض الأشياء التي يجب مراعاتها ، إلى جانب اقتراح التنفيذ. من المحتمل أن يكون إعداد قاعدة البيانات المثالية الخاص بك مزيجًا من بعض المؤشرات المفصلة أدناه.

التفرد

يحدد تنسيق E.164 على الصعيد العالمي والفريد رقم هاتف في جميع أنحاء العالم. كما أنه يتضمن بطبيعته بلدًا معينًا ويمكن تزويده كما هو الحال إلى phone() المساعد.

ستحتاج:

• عمود واحد لتخزين رقم الهاتف
• لتنسيق رقم الهاتف إلى E.164 قبل استمراره

مثال:

• إدخال المستخدم = 012/45.65.78
• عمود قاعدة البيانات
  • phone (varchar) = [phone]

تقديم رقم الهاتف بالطريقة التي تم بها إدخالها

إذا قمت بتخزين أرقام الهواتف المنسقة ، فستفقد إدخال المستخدم الخام بشكل لا يطاق. قد يكون من المفيد تقديم المستخدم الخاص بك برقم هاتفهم المُدخل للغاية ، على سبيل المثال من حيث تجربة المستخدم المحسنة.

ستحتاج:

• عمودين لتخزين المدخلات الخام والبلد المرتبط

مثال:

• إدخال المستخدم = 012/34.56.78
• أعمدة قاعدة البيانات
  • phone (varchar) = 012/34.56.78
  • phone_country (varchar) = BE

دعم عمليات البحث

يمكن أن يصبح البحث من خلال أرقام الهواتف بسرعة معقدة بشكل يبعث على السخرية وسيتطلب دائمًا فهمًا عميقًا لسياق ومدى تطبيقك. إليك نهجًا محتملًا يغطي الكثير من حالات الاستخدام "الطبيعية".

ستحتاج:

• ثلاثة أعمدة إضافية لتخزين المتغيرات القابلة للبحث في رقم الهاتف:
  • مدخلات طبيعية (مدخلات خام مع تجريد جميع الأحرف غير الفطرية)
  • رقم الهاتف المنسق الوطني (مع تجريد جميع الشخصيات غير المصنفة)
  • E.164 رقم هاتف منسق
• ربما saving() مراقب (أو ما يعادله) لإعادة توصيل المتغيرات قبل الثبات
• استعلام بحث واسع النطاق باستخدام المتغيرات القابلة للبحث

مثال:

• إدخال المستخدم = 12/34.56.78
• طريقة المراقب:

   public function saving ( User $ user )
  {
      if ( $ user -> isDirty ( ' phone ' ) && $ user -> phone ) {
          $ user -> phone_normalized = preg_replace ( ' /[^0-9]/ ' , '' , $ user -> phone );
          $ user -> phone_national = preg_replace ( ' /[^0-9]/ ' , '' , phone ( $ user -> phone , $ user -> phone_country )-> formatNational ());
          $ user -> phone_e164 = phone ( $ user -> phone , $ user -> phone_country )-> formatE164 ();
      }
  }

• أعمدة قاعدة البيانات
  • phone_normalized (varchar) = 12345678
  • phone_national (varchar) = 012345678
  • phone_e164 (varchar) = [phone]
• البحث عن استعلام:

   // $search holds the search term
  User :: where ( function ( $ query ) use ( $ search ) {
    $ query -> where ( ' phone_normalized ' , ' LIKE ' , preg_replace ( ' /[^0-9]/ ' , '' , $ search ) . ' % ' )
          -> orWhere ( ' phone_national ' , ' LIKE ' , preg_replace ( ' /[^0-9]/ ' , '' , $ search ) . ' % ' )
          -> orWhere ( ' phone_e164 ' , ' LIKE ' , preg_replace ( ' /[^+0-9]/ ' , '' , $ search ) . ' % ' )
  });