Laravel Phone

Telepon Laravel

Menambahkan fungsionalitas nomor telepon ke Laravel berdasarkan port php libphonenumber oleh Google.

Daftar isi

• Demo
• Instalasi
• Validasi
• Casting atribut
• Kelas utilitas
  • Format
  • Informasi nomor
  • Perbandingan kesetaraan
  • Fungsi pembantu
• Pertimbangan basis data

Demo

Lihat perilaku paket ini dalam demo.

Instalasi

Jalankan perintah berikut untuk menginstal versi paket terbaru yang berlaku:

composer require propaganistas/laravel-phone

Penyedia layanan ditemukan secara otomatis oleh Laravel.

Di direktori bahasa Anda, tambahkan terjemahan tambahan di setiap file bahasa validation.php :

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

Validasi

Gunakan kata kunci phone dalam array aturan validasi Anda atau gunakan PropaganistasLaravelPhoneRulesPhone untuk menentukan aturan dengan cara ekspresif.

Untuk menempatkan kendala pada negara -negara asal yang diizinkan, Anda dapat secara eksplisit menentukan kode negara yang diizinkan.

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

Atau untuk membuat segalanya lebih dinamis, Anda juga dapat mencocokkan dengan bidang data lain yang memegang kode negara. Misalnya, untuk meminta nomor telepon agar sesuai dengan negara tempat tinggal yang disediakan. Pastikan bidang negara memiliki nama yang sama dengan bidang telepon tetapi dengan _country ditambahkan untuk penemuan otomatis, atau berikan nama bidang negara kustom Anda sebagai parameter ke validator:

 ' 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 ' ,

Catatan: Kode negara harus patuh ISO 3166-1 Alpha-2 .

Untuk mendukung nomor telepon yang diformat secara internasional yang valid di sebelah negara -negara yang masuk daftar putih, gunakan parameter INTERNATIONAL . Ini bisa berguna ketika Anda mengharapkan angka yang diformat secara lokal dari negara tertentu tetapi juga ingin menerima nomor asing lain yang dimasukkan dengan benar:

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

Untuk menentukan batasan pada jenis angka, cukup tambahkan jenis yang diizinkan ke akhir parameter, misalnya:

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

Jenis yang paling umum adalah mobile dan fixed_line , tetapi jangan ragu untuk menggunakan salah satu jenis yang ditentukan di sini.

Persiapkan tipe dengan tanda seru untuk daftar hitam sebagai gantinya. Perhatikan bahwa Anda tidak akan pernah bisa menggunakan jenis putih dan daftar hitam pada saat yang sama.

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

Anda juga dapat mengaktifkan validasi lenient dengan menggunakan parameter LENIENT . Dengan keringanan hukuman diaktifkan, hanya panjang angka yang diperiksa alih -alih pola pembawa yang sebenarnya.

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

Casting atribut

Dua kelas pemeran disediakan untuk casting otomatis atribut model yang fasih:

 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 ' ,
    ];
}

Kedua kelas secara otomatis melemparkan nilai database ke objek fonenMen untuk digunakan lebih lanjut dalam aplikasi Anda.

 $ user -> phone // PhoneNumber object or null

Saat menetapkan nilai, mereka berdua menerima nilai string atau objek fonenMer. RawPhoneNumberCast bermutasi nilai database ke nomor input mentah, sedangkan E164PhoneNumberCast menulis nomor telepon E.164 yang diformat ke database.

Dalam hal RawPhoneNumberCast , para pemeran perlu diisyaratkan tentang negara telepon untuk menguraikan nomor mentah dengan benar menjadi objek telepon. Dalam hal E164PhoneNumberCast dan nilai yang akan ditetapkan belum dalam beberapa format internasional, para pemeran perlu diisyaratkan tentang negara telepon untuk mengubah nilainya dengan benar.

Kedua kelas menerima parameter pemeran dengan cara yang sama:

1. Ketika atribut bernama serupa ada, tetapi sufiks dengan _country (misalnya phone_country), para pemain akan mendeteksi dan menggunakannya secara otomatis.
2. Berikan nama atribut lain sebagai parameter pemeran
3. Berikan satu atau beberapa kode negara sebagai parameter cast

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

Catatan Penting: Kedua gips mengharapkan nomor telepon yang valid agar dapat dikonversi dengan lancar dari/ke objek nomor phonen. Harap validasi nomor telepon sebelum mengaturnya pada model. Lihat dokumentasi validasi untuk mempelajari cara memvalidasi nomor telepon.

️ Penugasan Atribut dan E164PhoneNumberCast

Karena sifat E164PhoneNumberCast Atribut negara yang valid diharapkan jika jumlahnya tidak dilewati dalam format internasional. Karena gips diterapkan dalam urutan nilai yang diberikan, pastikan untuk mengatur atribut negara sebelum mengatur atribut nomor telepon. Kalau tidak, E164PhoneNumberCast akan menemukan nilai negara kosong dan melemparkan pengecualian yang tidak terduga.

 // 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 ' ;

Kelas Bilangan Fonenitas Utilitas

Nomor telepon dapat dibungkus dalam kelas PropaganistasLaravelPhonePhoneNumber untuk meningkatkannya dengan metode utilitas yang bermanfaat. Aman untuk secara langsung merujuk objek -objek ini dalam tampilan atau saat menabung ke database karena mereka akan menurun dengan anggun ke format E.164.

 use Propaganistas  LaravelPhone  PhoneNumber ;

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

Format

Bilangan fonen dapat diformat dengan berbagai cara:

 $ 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]

Informasi nomor

Dapatkan beberapa informasi tentang nomor telepon:

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

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

Perbandingan kesetaraan

Periksa apakah nomor telepon tertentu (tidak) sama dengan yang lain:

 $ 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

Fungsi pembantu

Paket memaparkan fungsi helper phone() yang mengembalikan PropaganistasLaravelPhonePhoneNumber instance atau string yang diformat jika $format disediakan:

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

Pertimbangan basis data

Penafian: Penanganan nomor telepon sangat berbeda di setiap aplikasi. Oleh karena itu, topik -topik yang disebutkan di bawah ini dimaksudkan sebagai serangkaian pemikiran; Dukungan tidak akan diberikan.

Menyimpan nomor telepon dalam database selalu menjadi topik spekulatif dan tidak ada peluru perak. Itu semua tergantung pada persyaratan aplikasi Anda. Berikut adalah beberapa hal yang perlu dipertimbangkan, bersama dengan saran implementasi. Pengaturan basis data ideal Anda mungkin akan menjadi kombinasi dari beberapa petunjuk yang dirinci di bawah ini.

Keunikan

Format E.164 secara global dan unik mengidentifikasi nomor telepon di seluruh dunia. Ini juga secara inheren menyiratkan negara tertentu dan dapat disediakan apa adanya ke helper phone() .

Anda akan membutuhkan:

• Satu kolom untuk menyimpan nomor telepon
• Untuk memformat nomor telepon ke E.164 sebelum bertahan

Contoh:

• Input Pengguna = 012/45.65.78
• Kolom basis data
  • phone (varchar) = [phone]

Menyajikan nomor telepon seperti yang dimasukkan

Jika Anda menyimpan nomor telepon yang diformat, input pengguna mentah tidak akan hilang. Mungkin bermanfaat untuk menyajikan nomor telepon mereka sendiri, misalnya dalam hal peningkatan pengalaman pengguna.

Anda akan membutuhkan:

• Dua kolom untuk menyimpan input mentah dan negara berkorelasi

Contoh:

• Input Pengguna = 012/34.56.78
• Kolom basis data
  • phone (varchar) = 012/34.56.78
  • phone_country (varchar) = BE

Pencarian mendukung

Mencari melalui nomor telepon dapat dengan cepat menjadi sangat rumit dan akan selalu membutuhkan pemahaman yang mendalam tentang konteks dan tingkat aplikasi Anda. Berikut adalah pendekatan yang mungkin mencakup cukup banyak kasus penggunaan "alami".

Anda akan membutuhkan:

• Tiga kolom tambahan untuk menyimpan varian yang dapat dicari dari nomor telepon:
  • Input dinormalisasi (input mentah dengan semua karakter non-alpha dilucuti)
  • Nomor telepon yang diformat nasional (dengan semua karakter non-alpha dilucuti)
  • E.164 Nomor telepon yang diformat
• Mungkin pengamat saving() (atau setara) untuk lebih memilih varian sebelum kegigihan
• Kueri pencarian yang luas menggunakan varian yang dapat dicari

Contoh:

• Input Pengguna = 12/34.56.78
• Metode pengamat:

   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 ();
      }
  }

• Kolom basis data
  • phone_normalized (varchar) = 12345678
  • phone_national (varchar) = 012345678
  • phone_e164 (varchar) = [phone]
• Kueri Pencarian:

   // $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 ) . ' % ' )
  });