Laravel Phone

Teléfono de Laravel

Agrega la funcionalidad del número de teléfono a Laravel en función del puerto PHP de LibphonEnumber por Google.

Tabla de contenido

• Manifestación
• Instalación
• Validación
• Casting de atributos
• Clase de servicios públicos
  • Formato
  • Información numérica
  • Comparación de igualdad
  • Función auxiliar
• Consideraciones de la base de datos

Manifestación

Mira el comportamiento de este paquete en la demostración.

Instalación

Ejecute el siguiente comando para instalar la última versión aplicable del paquete:

composer require propaganistas/laravel-phone

El proveedor de servicios es descubierto automáticamente por Laravel.

En su directorio de idiomas, agregue una traducción adicional en cada archivo de idioma validation.php :

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

Validación

Use la palabra clave phone en su matriz de reglas de validación o use la clase de reglas de reglas PropaganistasLaravelPhoneRulesPhone para definir la regla de manera expresiva.

Para poner restricciones en los países originales permitidos, puede especificar explícitamente los códigos de país permitidos.

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

O para hacer las cosas más dinámicas, también puede igualar con otro campo de datos que contiene un código de país. Por ejemplo, para exigir un número de teléfono para que coincida con el país de residencia provisto. Asegúrese de que el campo del país tenga el mismo nombre que el campo del teléfono pero con _country agregado para el descubrimiento automático, o proporcione el nombre de su campo de país personalizado como parámetro para el validador:

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

Nota: Los códigos de país deben ser ISO 31661-1 Alpha-2 que cumplan con Alpha-2 .

Para admitir cualquier número de teléfono válido internacionalmente formateado al lado de los países de la lista blanca, use el parámetro INTERNATIONAL . Esto puede ser útil cuando espera números formateados localmente de un país específico, pero también desea aceptar cualquier otro número extranjero ingresado correctamente:

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

Para especificar restricciones sobre el tipo de número, solo agregue los tipos permitidos al final de los parámetros, por ejemplo:

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

Los tipos más comunes son mobile y fixed_line , pero no dude en usar cualquiera de los tipos definidos aquí.

Prepare un tipo con una marca de exclamación para la lista negra en su lugar. Tenga en cuenta que nunca puede usar tipos de lista blanca y en la lista negra al mismo tiempo.

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

También puede habilitar la validación de Lenient utilizando el parámetro LENIENT . Con la clemencia habilitada, solo se verifica la longitud del número en lugar de los patrones de portadoras reales.

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

Casting de atributos

Se proporcionan dos clases de reparto para el lanzamiento automático de atributos del modelo elocuente:

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

Ambas clases lanzan automáticamente el valor de la base de datos a un objeto PhoneNumber para su uso adicional en su aplicación.

 $ user -> phone // PhoneNumber object or null

Al establecer un valor, ambos aceptan un valor de cadena o un objeto PhoneNumber. El RawPhoneNumberCast muta el valor de la base de datos al número de entrada sin procesar, mientras que el E164PhoneNumberCast escribe un número de teléfono E.164 formateado en la base de datos.

En el caso de RawPhoneNumberCast , el elenco debe insinuarse sobre el país telefónico para analizar adecuadamente el número RAW en un objeto de teléfono. En el caso de E164PhoneNumberCast y el valor a establecer no está ya en algún formato internacional, el elenco debe insinuarse sobre el país telefónico para mutar adecuadamente el valor.

Ambas clases aceptan parámetros de reparto de la misma manera:

1. Cuando existe un atributo con nombre similar, pero sufijo con _country (por ejemplo, phone_country), el elenco lo detectará y lo usará automáticamente.
2. Proporcione el nombre de otro atributo como parámetro de reparto
3. Proporcione uno o varios códigos de país como parámetros de fundición

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

Nota importante: Ambos fundiciones esperan números de teléfono válidos para convertir sin problemas de/a objetos de número de fono. Valide los números de teléfono antes de configurarlos en un modelo. Consulte la documentación de validación para aprender a validar los números de teléfono.

️ Asignación de atributos y E164PhoneNumberCast

Debido a la naturaleza de E164PhoneNumberCast se espera un atributo de país válido si el número no se pasa en formato internacional. Dado que se aplican las fundiciones en el orden de los valores dados, asegúrese de establecer el atributo del país antes de configurar el atributo del número de teléfono. De lo contrario, E164PhoneNumberCast encontrará un valor de país vacío y lanzará una excepción inesperada.

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

Clase de número de fono de servicios públicos

Se puede envolver un número de teléfono en la clase PropaganistasLaravelPhonePhoneNumber para mejorarlo con métodos de utilidad útiles. Es seguro hacer referencia directamente a estos objetos en vistas o al guardar en la base de datos, ya que se degradarán con gracia al formato E.164.

 use Propaganistas  LaravelPhone  PhoneNumber ;

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

Formato

Se puede formatear un número de fono de varias maneras:

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

Información numérica

Obtenga información sobre el número de teléfono:

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

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

Comparación de igualdad

Verifique si un número de teléfono dado es (no) igual a otro:

 $ 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

Función auxiliar

El paquete expone la función de phone() auxiliar que devuelve una instancia PropaganistasLaravelPhonePhoneNumber o la cadena formateada si se proporcionó $format :

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

Consideraciones de la base de datos

Descargo de responsabilidad: el manejo del número de teléfono es bastante diferente en cada aplicación. Por lo tanto, los temas mencionados a continuación se entienden como un conjunto de titulares de pensamiento; No se proporcionará soporte.

Almacenar números de teléfono en una base de datos siempre ha sido un tema especulativo y simplemente no hay bala de plata. Todo depende de los requisitos de su aplicación. Aquí hay algunas cosas a tener en cuenta, junto con una sugerencia de implementación. La configuración de su base de datos ideal probablemente será una combinación de algunos de los punteros detallados a continuación.

Unicidad

El formato E.164 identifica a nivel mundial y exclusivo de un número de teléfono en todo el mundo. También implica inherentemente un país específico y se puede suministrar como es al ayudante phone() .

Necesitarás:

• Una columna para almacenar el número de teléfono
• Para formatear el número de teléfono en E.164 antes de persistirlo

Ejemplo:

• Entrada del usuario = 012/45.65.78
• Columna de base de datos
  • phone (varchar) = [phone]

Presentar el número de teléfono de la forma en que se ingresó

Si almacena números de teléfono formateados, la entrada de usuario sin procesar se perderá sin restealmente. Puede ser beneficioso presentar a sus usuarios su propio número de teléfono ingresado, por ejemplo, en términos de experiencia mejorada del usuario.

Necesitarás:

• Dos columnas para almacenar la entrada sin procesar y el país correlacionado

Ejemplo:

• Entrada del usuario = 012/34.56.78
• Columnas de base de datos
  • phone (varchar) = 012/34.56.78
  • phone_country (varchar) = BE

Apoyo de las búsquedas

La búsqueda a través de los números de teléfono puede volverse ridículamente complejo y siempre requerirá una comprensión profunda del contexto y el alcance de su aplicación. Aquí hay un posible enfoque que cubre muchos casos de uso "naturales".

Necesitarás:

• Tres columnas adicionales para almacenar variantes de búsqueda del número de teléfono:
  • Entrada normalizada (entrada en bruto con todos los caracteres no alfa despojados)
  • Número de teléfono con formato nacional (con todos los caracteres no alfa despojados)
  • E.164 Número de teléfono formateado
• Probablemente un observador saving() (o equivalente) para que prefiera las variantes antes de la persistencia
• Una consulta de búsqueda extensa que utiliza las variantes de búsqueda

Ejemplo:

• Entrada del usuario = 12/34.56.78
• Método Observador:

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

• Columnas de base de datos
  • phone_normalized (varchar) = 12345678
  • phone_national (Varchar) = 012345678
  • phone_e164 (varchar) = [phone]
• Consulta de búsqueda:

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