Laravel Phone

Laravel Phone

Adiciona a funcionalidade do número de telefone ao Laravel com base na porta PHP do libphoneNumber pelo Google.

Índice

• Demonstração
• Instalação
• Validação
• Elenco de atributo
• Classe de utilidade
  • Formatação
  • Informações do número
  • Comparação de igualdade
  • Função auxiliar
• Considerações de banco de dados

Demonstração

Confira o comportamento deste pacote na demonstração.

Instalação

Execute o seguinte comando para instalar a versão mais recente aplicável do pacote:

composer require propaganistas/laravel-phone

O provedor de serviços é descoberto automaticamente pela Laravel.

No seu diretório de idiomas, adicione uma tradução extra em cada arquivo de idioma validation.php :

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

Validação

Use a palavra -chave phone em sua matriz de regras de validação ou use a classe PropaganistasLaravelPhoneRulesPhone para definir a regra de maneira expressiva.

Para colocar restrições nos países originários permitidos, você pode especificar explicitamente os códigos de país permitidos.

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

Ou para tornar as coisas mais dinâmicas, você também pode corresponder a outro campo de dados que mantém um código de país. Por exemplo, exigir um número de telefone para corresponder ao país de residência fornecido. Verifique se o campo do país tem o mesmo nome do campo do telefone, mas com _country anexado à descoberta automática ou forneça seu nome de campo do país personalizado como um parâmetro para o 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: Os códigos do país devem ser compatíveis com ISO 3166-1 .

Para apoiar qualquer número de telefone válido formatado internacionalmente ao lado dos países da lista de permissões, use o parâmetro INTERNATIONAL . Isso pode ser útil quando você espera números formatados localmente de um país específico, mas também deseja aceitar qualquer outro número estrangeiro inserido corretamente:

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

Para especificar restrições no tipo de número, basta anexar os tipos permitidos ao final dos parâmetros, por exemplo:

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

Os tipos mais comuns são mobile e fixed_line , mas sinta -se à vontade para usar qualquer um dos tipos definidos aqui.

Prenda um tipo com uma marca de exclamação para a lista negra. Observe que você nunca pode usar tipos de lista de permissões e listados negros ao mesmo tempo.

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

Você também pode ativar a validação branda usando o parâmetro LENIENT . Com a clemência ativada, apenas o comprimento do número é verificado em vez de padrões de transportadora reais.

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

Elenco de atributo

Duas classes de elenco são fornecidas para a fundição automática de atributos de modelo eloquente:

 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 as classes lançam automaticamente o valor do banco de dados em um objeto PhoneNumber para uso posterior em seu aplicativo.

 $ user -> phone // PhoneNumber object or null

Ao definir um valor, ambos aceitam um valor de string ou um objeto fonenumber. O RawPhoneNumberCast sofra o valor do banco de dados para o número de entrada bruto, enquanto o E164PhoneNumberCast grava um número de telefone formatado E.164 no banco de dados.

No caso do RawPhoneNumberCast , o elenco precisa ser sugerido sobre o país de telefone para analisar adequadamente o número bruto em um objeto de telefone. No caso de E164PhoneNumberCast e o valor a ser definido ainda não está em algum formato internacional, o elenco precisa ser sugerido sobre o país telefônico para mudar adequadamente o valor.

Ambas as classes aceitam parâmetros de elenco da mesma maneira:

1. Quando existe um atributo nomeado semelhante, mas sufixo com _country (por exemplo, Phone_Country), o elenco detectará e o usará automaticamente.
2. Forneça o nome de outro atributo como um parâmetro de elenco
3. Forneça um ou vários códigos de país como parâmetros de elenco

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

NOTA IMPORTANTE: Ambos os elencos esperam números de telefone válidos para converter suavemente de/para objetos de número de telefone. Valide os números de telefone antes de defini -los em um modelo. Consulte a documentação da validação para aprender como validar números de telefone.

️ Atributo atribuição e E164PhoneNumberCast

Devido à natureza do E164PhoneNumberCast um atributo de país válido será esperado se o número não for aprovado em formato internacional. Como os elencos são aplicados na ordem dos valores fornecidos, certifique -se de definir o atributo do país antes de definir o atributo do número de telefone. Caso contrário, E164PhoneNumberCast encontrará um valor vazio do país e lançará uma exceção 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 ' ;

Classe de número de telefone de utilidade

Um número de telefone pode ser embrulhado na classe PropaganistasLaravelPhonePhoneNumber para aprimorá -la com métodos de utilidade úteis. É seguro fazer referência diretamente a esses objetos nas visões ou ao salvar no banco de dados, pois eles se degradam graciosamente para o formato E.164.

 use Propaganistas  LaravelPhone  PhoneNumber ;

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

Formatação

Um número de telefone pode ser formatado de várias maneiras:

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

Informações do número

Obtenha algumas informações sobre o número de telefone:

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

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

Comparação de igualdade

Verifique se um determinado número de telefone é (não) igual a outro:

 $ 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

Função auxiliar

O pacote expõe a função Helper phone() que retorna uma instância PropaganistasLaravelPhonePhoneNumber ou a sequência formatada se $format foi fornecido:

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

Considerações de banco de dados

Isenção de responsabilidade: o manuseio do número de telefone é bem diferente em cada aplicativo. Os tópicos mencionados abaixo são, portanto, como um conjunto de iniciantes; o suporte não será fornecido.

O armazenamento de números de telefone em um banco de dados sempre foi um tópico especulativo e simplesmente não há bala de prata. Tudo depende dos requisitos do seu aplicativo. Aqui estão algumas coisas a levar em consideração, juntamente com uma sugestão de implementação. Sua configuração ideal de banco de dados provavelmente será uma combinação de algumas das dicas detalhadas abaixo.

Exclusividade

O formato E.164 identifica um número de telefone em todo o mundo. Também implica inerentemente um país específico e pode ser fornecido como é o ajudante de phone() .

Você precisará:

• Uma coluna para armazenar o número de telefone
• Para formatar o número de telefone para E.164 antes de persistir

Exemplo:

• Entrada do usuário = 012/45.65.78
• Coluna de banco de dados
  • phone (Varchar) = [phone]

Apresentando o número de telefone da maneira como foi inserido

Se você armazenar números de telefone formatados, a entrada do usuário bruto será perdida inocente. Pode ser benéfico apresentar a seus usuários o próprio número de telefone inserido, por exemplo, em termos de melhoria da experiência do usuário.

Você precisará:

• Duas colunas para armazenar a entrada bruta e o país correlacionado

Exemplo:

• Entrada do usuário = 012/34.56.78
• Colunas de banco de dados
  • phone (Varchar) = 012/34.56.78
  • phone_country (Varchar) = BE

Suportar pesquisas

A pesquisa nos números de telefone pode rapidamente se tornar ridiculamente complexa e sempre exigirá uma compreensão profunda do contexto e extensão do seu aplicativo. Aqui está uma abordagem possível que abrange muitos casos de uso "naturais".

Você precisará:

• Três colunas adicionais para armazenar variantes pesquisáveis ​​do número de telefone:
  • Entrada normalizada (entrada bruta com todos os caracteres não alfa despojados)
  • Número de telefone formatado nacional (com todos os caracteres não alfa despojados)
  • E.164 Número de telefone formatado
• Provavelmente um observador saving() (ou equivalente) para preencher as variantes antes da persistência
• Uma extensa consulta de pesquisa utilizando as variantes pesquisáveis

Exemplo:

• Entrada do usuário = 12/34.56.78
• Método do 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 ();
      }
  }

• Colunas de banco de dados
  • phone_normalized (Varchar) = 12345678
  • phone_national (Varchar) = 012345678
  • phone_e164 (Varchar) = [phone]
• Consulta de pesquisa:

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