PHP Classes

PHP Numverify API Client: Verify phones and get country data using NumVerify

Recommend this page to a friend!
  Info   Documentation   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Last Updated Ratings Unique User Downloads Download Rankings
2024-03-13 (6 months ago) RSS 2.0 feedNot enough user ratingsTotal: 8 All time: 11,430 This week: 74Up
Version License PHP version Categories
numverify-api 3.0.1MIT/X Consortium ...8.2.0Wireless and Mobile, Web services, Ge..., V..., P...
Description 

Author

This package can verify phones and get country data using NumVerify.

It can send HTTP requests to the NumVerify API Web servers to perform several types of number validation:

Currently, it can:

- Validate and return details of a given phone number like:

* The number in a local format

* The number with the international prefix

* The number country prefix, code, name, location, carrier

* The type of line

- Find a country by code or name

- Get country information like:

* Code

* Name

* Dialing code

Picture of Eric Sizemore
  Performance   Level  
Name: Eric Sizemore is available for providing paid consulting. Contact Eric Sizemore .
Classes: 15 packages by
Country: United States United States
Age: 37
All time rank: 15119 in United States United States
Week rank: 192 Down22 in United States United States Down
Innovation award
Innovation award
Nominee: 4x

Winner: 2x

Documentation

Numverify API Client Library for PHP

Numverify phone number validation and country API client library for PHP.

Build Status Code Coverage Scrutinizer Code Quality Tests PHPStan Psalm Static analysis

Type Coverage Psalm Level Latest Stable Version Downloads per Month License

This library is a fork of markrogoyski/numverify-api-client-php. See Acknowledgements for more information.

Features

  • Cache of client (Guzzle) calls. See Construct API to use a cache
  • Phone number validation API * Validate phone numbers * Carrier information * Line type * Location info: country, local information * Phone number formats
  • Countries API * List of countries * Country names, country codes, dialing codes

Numverify API documentation: https://numverify.com/documentation

Setup

Add the library to your composer.json file in your project:

{
  "require": {
      "esi/numverify-api-client-php": "3.*"
  }
}

Use composer to install the library:

$ php composer.phar install

Composer will install Numverify API Client Library for PHP inside your vendor folder. Then you can add the following to your .php files to the use library with Autoloading.

require_once __DIR__ . '/vendor/autoload.php';

Alternatively, use composer on the command line to require and install Numverify API Client Library:

$ php composer.phar require esi/numverify-api-client-php:3.*

Minimum Requirements

  • PHP 8.2 with `ext-json`.

Usage

Create New API

$accessKey = 'AccountAccessKeyGoesHere';
$api       = new \Numverify\Api($accessKey);

Phone Number Validation API

$phoneNumber          = '14158586273';
$validatedPhoneNumber = $api->validatePhoneNumber($phoneNumber);
 
// Phone number information
if ($validatedPhoneNumber->isValid()) {
    $number              = $validatedPhoneNumber->getNumber();              // 14158586273
    $localFormat         = $validatedPhoneNumber->getLocalFormat();         // 4158586273
    $internationalPrefix = $validatedPhoneNumber->getInternationalFormat(); // +14158586273
    $countryPrefix       = $validatedPhoneNumber->getCountryPrefix();       // +1
    $countryCode         = $validatedPhoneNumber->getCountryCode();         // US
    $countryName         = $validatedPhoneNumber->getCountryName();         // United States of America
    $location            = $validatedPhoneNumber->getLocation();            // Novato
    $carrier             = $validatedPhoneNumber->getCarrier();             // AT&T Mobility LLC
    $lineType            = $validatedPhoneNumber->getLineType();            // mobile
}

// Use optional country code parameter for local (non-E.164) phone numbers
$phoneNumber = '4158586273';
$countryCode = 'US';
$validatedPhoneNumber = $api->validatePhoneNumber($phoneNumber, $countryCode);
 
// PHP Interfaces
$stringRepresentation = (string) $validatedPhoneNumber;
$jsonRepresentation   = json_encode($validatedPhoneNumber);

Countries API

$countries = $api->getCountries();
 
// Find countries (by country code or by name)
$unitedStates = $countries->findByCountryCode('US');
$japan        = $countries->findByCountryName('Japan');
 
// Country information
$usCountryCode = $unitedStates->getCountryCode(); // US
$usCountryName = $unitedStates->getCountryName(); // United States
$usDialingCode = $unitedStates->getDialingCode(); // +1
 
$japanCountryCode = $japan->getCountryCode();     // JP
$japanCountryName = $japan->getCountryName();     // Japan
$japanDialingCode = $japan->getDialingCode();     // +81
 
// Country collection is iterable
foreach ($countries as $country) {
    $countryCode = $country->getCountryCode();
    $countryName = $country->getCountryName();
    $dialingCode = $country->getDialingCode();
}
 
// Country collection PHP interfaces
$numberOfCountries  = count($countries);
$jsonRepresentation = json_encode($numberOfCountries);
 
// Country PHP interfaces
$stringRepresentation = (string) $unitedStates;   // US: United States (+1)
$jsonRepresentation   = json_encode($unitedStates);

Options

Signature of the Api constructor

    /
     * Api constructor.
     *
     * Requires an access (or api) key. You can get one from Numverify:
     *
     * @see https://numverify.com/product
     *
     * Note: If you are on their free plan, $useHttps = true will not work for you.
     *
     * @param  string                $accessKey  API access key.
     * @param  bool                  $useHttps   (optional) Flag to determine if API calls should use http or https.
     * @param  ClientInterface|null  $client     (optional) Parameter to provide your own Guzzle client.
     * @param  array<string, mixed>  $options    (optional) Array of options to pass to the Guzzle client.
     */
    public function __construct(
        #[SensitiveParameter]
        private readonly string $accessKey,
        bool $useHttps = false,
        ?ClientInterface $client = null,
        array $options = []
    );

Construct API to use HTTPS for API calls

Note: The Numverify api has different plan options when signing up for an access key. The 'free' plan can not use the secure (HTTPS) url for the API.

$useHttps = true;
$api      = new \Numverify\Api($accessKey, $useHttps);  // Optional second parameter

Construct API to use a custom Guzzle client or options

Note: If creating and passing your own client to Api, it will completely ignore $useHttps.

$client = new \GuzzleHttp\Client([
    'base_uri' => 'http://apilayer.net/api',
    'timeout => 10
]);

$api = new \Numverify\Api($accessKey, $useHttps, $client);

If you simply want to change some of Guzzle's default options, pass them along to the optional $options parameter instead.

$api = new \Numverify\Api($accessKey, $useHttps, null, ['timeout => 10]);

// or
$api = new \Numverify\Api($accessKey, $useHttps, options: ['timeout => 10]);

Construct API to use a cache

The Api constructor allows you to pass an optional $options parameter, typically used to pass Guzzle options on to the client.

If you specify cachePath within $options, and it is a valid directory, the constructor will add the cache handler to Guzzle's handler stack.

$api = new \Numverify\Api($accessKey, $useHttps, options: ['cachePath' => '/tmp']);

Exceptions

API failures throw a `NumverifyApiFailureException`

// Numverify API server error
try {
    $validatedPhoneNumber = $api->validatePhoneNumber($phoneNumber);
} catch (\Numverify\Exception\NumverifyApiFailureException $e) {
    $statusCode = $e->getStatusCode(); // 500
    $message    = $e->getMessage();    // Unknown error - 500 Internal Server Error
}

// Numverify API failure response
try {
    $validatedPhoneNumber = $api->validatePhoneNumber($phoneNumber);
} catch (\Numverify\Exception\NumverifyApiFailureException $e) {
    $statusCode = $e->getStatusCode(); // 200
    $message    = $e->getMessage();    // Type:invalid_access_key Code:101 Info:You have not supplied a valid API Access Key.
}

About

Requirements

  • PHP 8.2.0 or above.

Submitting bugs and feature requests

Bugs and feature requests are tracked on GitHub

Issues are the quickest way to report a bug. If you find a bug or documentation error, please check the following first:

  • That there is not an Issue already open concerning the bug
  • That the issue has not already been addressed (within closed Issues, for example)

Contributing

Contributions of code and documentation from the community is welcome. These contributions can be made in the form of Issues or Pull Requests on the Numverify API for PHP repository.

Numverify API Client for PHP is licensed under the MIT license. When submitting new features or patches to this library, you are giving permission to license those features or patches under the MIT license.

Numverify API Client for PHP tries to adhere to PHPStan level 9 with strict rules and bleeding edge. Please ensure any contributions do as well.

Guidelines

Before we look into how, here are the guidelines. If your Pull Requests fail to pass these guidelines it will be declined and you will need to re-submit when you?ve made the changes. This might sound a bit tough, but it is required for me to maintain quality of the code-base.

PHP Style

Please ensure all new contributions match the PSR-12 coding style guide. The project is not fully PSR-12 compatible, yet; however, to ensure the easiest transition to the coding guidelines, I would like to go ahead and request that any contributions follow them.

Documentation

If you change anything that requires a change to documentation then you will need to add it. New methods, parameters, changing default values, adding constants, etc are all things that will require a change to documentation. The change-log must also be updated for every change. Also PHPDoc blocks must be maintained.

Documenting functions/variables (PHPDoc)

Please ensure all new contributions adhere to:

when documenting new functions, or changing existing documentation.

Branching

One thing at a time: A pull request should only contain one change. That does not mean only one commit, but one change - however many commits it took. The reason for this is that if you change X and Y but send a pull request for both at the same time, we might really want X but disagree with Y, meaning we cannot merge the request. Using the Git-Flow branching model you can create new branches for both of these features and send two requests.

Author

Eric Sizemore - <admin@secondversion.com> - <https://www.secondversion.com>

License

Numverify API Client for PHP is licensed under the MIT License - see the LICENSE.md file for details

Acknowledgements

This library is a fork of the markrogoyski/numverify-api-client-php(https://github.com/markrogoyski/numverify-api-client-php) library by Mark Rogoyski(https://github.com/markrogoyski).

To see a list of changes in this library in comparison to the original library, please see the CHANGELOG.md file.


  Files folder image Files (35)  
File Role Description
Files folder image.github (2 files, 1 directory)
Files folder imagesrc (1 file, 3 directories)
Files folder imagetests (3 files, 3 directories)
Accessible without login Plain text file .php-cs-fixer.dist.php Example Example script
Accessible without login Plain text file .scrutinizer.yml Data Auxiliary data
Accessible without login Plain text file CHANGELOG.md Data Auxiliary data
Accessible without login Plain text file composer.json Data Auxiliary data
Accessible without login Plain text file composer.lock Data Auxiliary data
Accessible without login Plain text file LICENSE.md Lic. License text
Accessible without login Plain text file phpstan.neon Data Auxiliary data
Accessible without login Plain text file phpunit.xml Data Auxiliary data
Accessible without login Plain text file psalm.xml Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation
Accessible without login Plain text file renovate.json Data Auxiliary data
Accessible without login Plain text file SECURITY.md Data Auxiliary data

  Files folder image Files (35)  /  .github  
File Role Description
Files folder imageworkflows (3 files)
  Accessible without login Plain text file dependabot.yml Data Auxiliary data
  Accessible without login Plain text file FUNDING.yml Data Auxiliary data

  Files folder image Files (35)  /  .github  /  workflows  
File Role Description
  Accessible without login Plain text file analysis.yml Data Auxiliary data
  Accessible without login Plain text file psalm.yml Data Auxiliary data
  Accessible without login Plain text file tests.yml Data Auxiliary data

  Files folder image Files (35)  /  src  
File Role Description
Files folder imageCountry (2 files)
Files folder imageException (2 files)
Files folder imagePhoneNumber (4 files)
  Plain text file Api.php Class Class source

  Files folder image Files (35)  /  src  /  Country  
File Role Description
  Plain text file Collection.php Class Class source
  Plain text file Country.php Class Class source

  Files folder image Files (35)  /  src  /  Exception  
File Role Description
  Plain text file NumverifyApiFailureException.php Class Class source
  Plain text file NumverifyApiResponseException.php Class Class source

  Files folder image Files (35)  /  src  /  PhoneNumber  
File Role Description
  Plain text file Factory.php Class Class source
  Plain text file InvalidPhoneNumber.php Class Class source
  Plain text file PhoneNumberInterface.php Class Class source
  Plain text file ValidPhoneNumber.php Class Class source

  Files folder image Files (35)  /  tests  
File Role Description
Files folder imageCountry (2 files)
Files folder imageException (2 files)
Files folder imagePhoneNumber (2 files)
  Plain text file ApiCountryTest.php Class Class source
  Plain text file ApiPhoneNumberTest.php Class Class source
  Plain text file ApiTest.php Class Class source

  Files folder image Files (35)  /  tests  /  Country  
File Role Description
  Plain text file CollectionTest.php Class Class source
  Plain text file CountryTest.php Class Class source

  Files folder image Files (35)  /  tests  /  Exception  
File Role Description
  Plain text file NumverifyApiFailureExceptionTest.php Class Class source
  Plain text file NumverifyApiResponseExceptionTest.php Class Class source

  Files folder image Files (35)  /  tests  /  PhoneNumber  
File Role Description
  Plain text file InvalidPhoneNumberTest.php Class Class source
  Plain text file ValidPhoneNumberTest.php Class Class source

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:8
This week:0
All time:11,430
This week:74Up