README

Numverify 手机号码验证和国家 API 客户端库，适用于 PHP。

此库是基于 markrogoyski/numverify-api-client-php 的分支。有关更多信息，请参阅致谢。

特性

客户端调用缓存（Guzzle）。请参阅构建 API 以使用缓存
手机号码验证 API
- 验证手机号码
- 运营商信息
- 线路类型
- 位置信息：国家，本地信息
- 手机号码格式
国家 API
- 国家列表
- 国家名称，国家代码，拨号代码

Numverify API 文档：https://numverify.com/documentation

设置

将库添加到您项目的 composer.json 文件中

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

使用 composer 安装库

$ php composer.phar install

Composer 将在您的 vendor 文件夹中安装 Numverify API 客户端库。然后您可以将以下内容添加到您的 .php 文件中，以使用自动加载使用库。

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

或者，在命令行上使用 composer 请求和安装 Numverify API 客户端库

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

最低要求

PHP 8.2 版本，带有 ext-json。

用法

创建新 API

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

手机号码验证 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);

国家 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);

选项

API 构造函数的签名

    /**
     * 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 = []
    );

构建 API 以使用 HTTPS 进行 API 调用

注意：Numverify API 在注册访问密钥时具有不同的计划选项。'免费'计划无法使用安全的（HTTPS）URL 进行 API 调用。

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

构建 API 以使用自定义 Guzzle 客户端或选项

注意：如果为 Api 创建并传递自己的客户端，它将完全忽略 $useHttps。

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

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

如果您只想更改一些 Guzzle 的默认选项，请将它们传递给可选的 $options 参数。

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

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

构建 API 以使用缓存

API 构造函数允许您传递可选的 $options 参数，通常用于将 Guzzle 选项传递给客户端。

如果您在 $options 中指定 cachePath，并且它是一个有效的目录，则构造函数将向 Guzzle 的处理程序堆栈添加缓存处理程序。

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

异常

API 失败抛出 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.
}

关于

要求

PHP 8.2.0 或更高版本。

提交错误和功能请求

错误和功能请求在 GitHub 上跟踪

问题是最快报告错误的方式。如果您发现错误或文档错误，请首先检查以下内容

有关错误的 Issue 已经打开
问题尚未解决（例如，在关闭的 Issue 中）

贡献

欢迎社区贡献代码和文档。这些贡献可以以 Issue 或 Pull Requests 的形式在 Numverify API for PHP 存储库上提交。

Numverify API PHP客户端遵循MIT许可证。在向该库提交新功能或补丁时，您同意将这些功能或补丁许可给MIT许可证。

Numverify API PHP客户端力求遵循PHPStan 9级别，采用严格规则和前沿技术。请确保您的任何贡献也能做到这一点。

指南

在探讨具体做法之前，以下是指南。如果您的Pull Requests未通过这些指南，将被拒绝，您需要修改后重新提交。这可能听起来有些严格，但这是为了保持代码库的质量所必需的。

PHP风格

请确保所有新的贡献符合PSR-12编码风格指南。该项目目前尚未完全符合PSR-12，但是为了确保最轻松地过渡到编码指南，我希望要求任何贡献都遵循这些指南。

文档

如果您更改了需要更改文档的内容，则需要添加相应的文档。新方法、参数、更改默认值、添加常量等都需要更改文档。变更日志也必须对每次更改进行更新。此外，还必须维护PHPDoc块。

函数/变量文档（PHPDoc）

请确保所有新的贡献在记录新函数或更改现有文档时遵循

。

分支

一次一件事情：Pull Request应仅包含一个更改。这并不意味着只有一个提交，而是一个更改——无论需要多少提交。这样做的原因是，如果您同时更改X和Y，但发送一个包含两者的Pull Request，我们可能真的需要X，但不同意Y，这意味着我们无法合并请求。使用Git-Flow分支模型，您可以创建用于这两个功能的分支并发送两个请求。

作者

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

许可证

Numverify API PHP客户端遵循MIT许可证 - 详细信息请参阅LICENSE.md文件。

致谢

此库是fork自Mark Rogoyski的markrogoyski/numverify-api-client-php(https://github.com/markrogoyski/numverify-api-client-php)库。

要查看此库与原始库相比的更改列表，请参阅CHANGELOG.md文件。

esi / numverify-api-client-php

维护者

详细信息