Api::validateAndDecodeResponse() - Code Metrics - Inspection of "preparing 3.0.1" - ericsizemore/numverify-api-client-php - Measure and Improve Code Quality continuously with Scrutinizer

Passed
Push — master ( c9356f...ede02a )

by Eric
created 2024-03-14 02:24 UTC
Api::validateAndDecodeResponse() A

↳ Parent: Api
Complexity

Conditions	5
Paths	5
Size

Total Lines	24
Code Lines	8
Duplication

Lines	0
Ratio	0 %
Code Coverage

Tests	9
CRAP Score	5
Importance

Changes
Metric	Value
cc	5
eloc	8
c	0
b	0
f	0
nc	5
nop	2
dl	0
loc	24
ccs	9
cts	9
cp	1
crap	5
rs	9.6111
<?php

declare(strict_types=1);

/**
 * This file is part of the Numverify API Client for PHP.
 *
 * (c) 2024 Eric Sizemore <[email protected]>
 * (c) 2018-2021 Mark Rogoyski <[email protected]>
 *
 * @license The MIT License
 *
 * For the full copyright and license information, please view the LICENSE.md
 * file that was distributed with this source code.
 */

namespace Numverify;

use GuzzleHttp\{
    Client,
    ClientInterface,
    Exception\GuzzleException,
    Exception\ServerException,
    HandlerStack
};
use Kevinrob\GuzzleCache\{
    CacheMiddleware,
    Storage\Psr6CacheStorage,
    Strategy\PrivateCacheStrategy
};
use Numverify\{
    Country\Collection,
    Country\Country,
    Exception\NumverifyApiFailureException,
    PhoneNumber\Factory,
    PhoneNumber\PhoneNumberInterface
};
use Psr\Http\Message\ResponseInterface;
use SensitiveParameter;
use stdClass;
use Symfony\Component\Cache\Adapter\FilesystemAdapter;

use function array_keys;
use function array_map;
use function array_merge;
use function is_dir;
use function is_writable;
use function json_decode;
use function trim;

/**
 * Main API class.
 *
 * @see \Numverify\Tests\ApiTest
 *
 * @psalm-api
 *
 * @phpstan-type ApiJsonArray array{success?: bool, error?: array{code?: int, type?: string, info?: string}, valid?: bool, number?: string, local_format?: string, international_format?: string, country_prefix?: string, country_code?: string, country_name?: string, location?: string, carrier?: string, line_type?: string}
 * @phpstan-type ApiCountryJsonArray array<string, array{country_name: string, dialling_code: string}>
 */
class Api
{
    /**
     * Current version of the Numverify package.
     *
     * @var string
     */
    public const LIBRARY_VERSION = '3.0.1';

    /**
     * URL for Numverify's "Free" plan.
     *
     * @see https://numverify.com/product
     */
    private const HTTP_URL = 'http://apilayer.net/api';

    /**
     * URL for Numverify's paid plans. ("Basic", "Professional", or "Enterprise").
     *
     * @see https://numverify.com/product
     */
    private const HTTPS_URL = 'https://apilayer.net/api';

    /**
     * Guzzle Client.
     */
    private ClientInterface $client;

    /**
     * Api constructor.
     *
     * Requires an access 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 = []
    ) {
        // If we already have a client.
        if ($client instanceof ClientInterface) {
            $this->client = $client;

            return;
        }

        // Build client
        $clientOptions = ['base_uri' => self::getUrl($useHttps)];

        // If $options has 'cachePath' key, and it is a valid directory, then buildCacheHandler() will
        // add Cache to the Guzzle handler stack.
        $options = self::buildCacheHandler($options);

        // Merge $options into main client options.
        $clientOptions = array_merge($clientOptions, $options);

        $this->client = new Client($clientOptions);
    }

    /**
     * Validate a phone number.
     *
     * Will return ValidPhoneNumber for a valid number, InvalidPhoneNumber otherwise (both PhoneNumberInterface).
     *
     * @param string $countryCode (Optional) Use to provide a phone number in a local format (non E.164).
     *
     * @throws NumverifyApiFailureException If the response is non 200 or success field is false.
     * @throws GuzzleException              If Guzzle encounters an issue.
     */
    public function validatePhoneNumber(string $phoneNumber, string $countryCode = ''): PhoneNumberInterface
    {
        $phoneNumber = trim($phoneNumber);
        $countryCode = trim($countryCode);

        $query = [
            'access_key' => $this->accessKey,
            'number'     => $phoneNumber,
        ];

        if ($countryCode !== '') {
            $query['country_code'] = $countryCode;
        }

        try {
            $result = $this->client->request('GET', '/validate', [
                'query' => $query,
            ]);
        } catch (ServerException $serverException) {
            // >= 400 <= 500 status code
            // wrap ServerException with NumverifyApiFailureException
            throw new NumverifyApiFailureException($serverException->getResponse());
        }

        /** @var stdClass $body */
        $body = self::validateAndDecodeResponse($result);

        return Factory::create($body);
    }

    /**
     * Get list of countries.
     *
     * @throws NumverifyApiFailureException If the response is non 200 or success field is false.
     * @throws GuzzleException              If Guzzle encounters an issue.
     */
    public function getCountries(): Collection
    {
        try {
            $response = $this->client->request('GET', '/countries', [
                'query' => [
                    'access_key' => $this->accessKey,
                ],
            ]);
        } catch (ServerException $serverException) {
            // >= 400 <= 500 status code
            // wrap ServerException with NumverifyApiFailureException
            throw new NumverifyApiFailureException($serverException->getResponse());
        }

        /** @var ApiCountryJsonArray $body */
        $body = self::validateAndDecodeResponse($response, true);

        $countries = array_map(
            static fn (array $country, string $countryCode): Country => new Country($countryCode, $country['country_name'], $country['dialling_code']),
            $body,
            /** @scrutinizer ignore-type */ $body,
            array_keys($body)
            array_keys(/** @scrutinizer ignore-type */ $body)
        );

        return new Collection(...$countries);
    }

    /**
     * Get the URL to use for API calls.
     */
    private static function getUrl(bool $useHttps): string
    {
        return $useHttps ? self::HTTPS_URL : self::HTTP_URL;
    }

    /**
     * Given a response object, checks the status code and checks the 'success' field, if it exists.
     *
     * If everything looks good, it returns the decoded jSON data based on $asArray.
     *
     * @param bool $asArray If true, returns the decoded jSON as an assoc. array, stdClass otherwise.
     *
     * @return stdClass | ApiJsonArray | ApiCountryJsonArray
     *
     * @throws NumverifyApiFailureException If the response is non 200 or success field is false.
     */
    private static function validateAndDecodeResponse(ResponseInterface $response, bool $asArray = false): stdClass | array
    {
        // If not 200 ok
        if ($response->getStatusCode() !== 200) {
            throw new NumverifyApiFailureException($response);
        }

        /**
         * @var ApiJsonArray | ApiCountryJsonArray | stdClass $body
         */
        $body = json_decode($response->getBody()->getContents(), $asArray);

        /**
         * @var ApiJsonArray | ApiCountryJsonArray $data
         */
        $data = $asArray ? $body : (array) $body;

        if (isset($data['success']) && $data['success'] === false) {
            throw new NumverifyApiFailureException($response);
        }

        unset($data);

        return $body;
    }

    /**
     * Creates a Guzzle HandlerStack and adds the CacheMiddleware if 'cachePath' exists within the
     * given $options array, and it is a valid directory.
     *
     * Returns given $options as passed, minus the 'cachePath' as it is not a valid Guzzle option for
     * the client.
     *
     * @param array<string, mixed> $options
     *
     * @return array<string, mixed>
     */
    private static function buildCacheHandler(array $options): array
    {
        $cachePath = (string) ($options['cachePath'] ?? null); // @phpstan-ignore-line

        if (is_dir($cachePath) && is_writable($cachePath)) {
            $handlerStack = HandlerStack::create();
            $handlerStack->push(middleware: new CacheMiddleware(cacheStrategy: new PrivateCacheStrategy(
                cache: new Psr6CacheStorage(cachePool: new FilesystemAdapter(namespace: 'numverify', defaultLifetime: 300, directory: $cachePath))
            )), name: 'cache');

            unset($options['cachePath']);
            $options += ['handler' => $handlerStack];
        }

        return $options;
    }
}

ericsizemore / numverify-api-client-php

Push — master ( c9356f...ede02a )

Api::validateAndDecodeResponse() A

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like
