Merge pull request #57 from maxmind/greg/release

Release 0.10.0
maxmind · Nov 15, 2024 · ac661c4 · ac661c4
2 parents 5a259c7 + d7c7c42
commit ac661c4
Show file tree

Hide file tree

Showing 13 changed files with 105 additions and 50 deletions.
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
@@ -14,7 +14,7 @@ jobs:
       - name: Setup PHP
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.1
+          php-version: 8.3
 
       - name: Checkout
         uses: actions/checkout@v4

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -12,7 +12,7 @@ jobs:
     strategy:
       matrix:
         operating-system: [ubuntu-latest, windows-latest, macos-latest]
-        php-versions: ['7.2', '7.3', '7.4', '8.0', '8.1']
+        php-versions: ['8.1', '8.2', '8.3', '8.4']
     name: "PHP ${{ matrix.php-versions }} test on ${{ matrix.operating-system }}"
     steps:
       - name: Setup PHP

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,12 @@
 CHANGELOG
 =========
 
+0.10.0 (2024-11-14)
+-------------------
+
+* PHP 8.1 or greater is now required.
+* Type hints for PHPStan have been improved.
+
 0.9.0 (2022-03-28)
 ------------------
 

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ shared code between MaxMind's various web service client APIs.
 
 ## Requirements  ##
 
-The library requires PHP 7.2 or greater.
+The library requires PHP 8.1 or greater.
 
 There are several other dependencies as defined in the `composer.json` file.
 
@@ -20,6 +20,6 @@ This API uses [Semantic Versioning](https://semver.org/).
 
 ## Copyright and License ##
 
-This software is Copyright (c) 2015-2023 by MaxMind, Inc.
+This software is Copyright (c) 2015-2024 by MaxMind, Inc.
 
 This is free software, licensed under the Apache License, Version 2.0.
diff --git a/composer.json b/composer.json
@@ -12,7 +12,7 @@
     }
   ],
   "require": {
-    "php": ">=7.2",
+    "php": ">=8.1",
     "composer/ca-bundle": "^1.0.3",
     "ext-curl": "*",
     "ext-json": "*"

diff --git a/phpstan.neon b/phpstan.neon
@@ -3,5 +3,4 @@ parameters:
     paths:
         - src
         - tests
-    checkMissingIterableValueType: false
 
diff --git a/phpunit.xml.dist b/phpunit.xml.dist
@@ -1,20 +1,17 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<phpunit bootstrap="./tests/bootstrap.php" colors="true">
-    <testsuites>
-        <testsuite name="minFraud Test Suite">
-            <directory suffix="Test.php">./tests/MaxMind/Test/</directory>
-        </testsuite>
-    </testsuites>
-
-    <filter>
-        <whitelist>
-            <directory suffix=".php">./src/MaxMind/</directory>
-        </whitelist>
-    </filter>
-
-    <logging>
-        <log type="coverage-clover" target="build/logs/clover.xml"/>
-    </logging>
-
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" bootstrap="./tests/bootstrap.php" colors="true" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">./src/MaxMind/</directory>
+    </include>
+    <report>
+      <clover outputFile="build/logs/clover.xml"/>
+    </report>
+  </coverage>
+  <testsuites>
+    <testsuite name="Test Suite">
+      <directory suffix="Test.php">./tests/MaxMind/Test/</directory>
+    </testsuite>
+  </testsuites>
+  <logging/>
 </phpunit>
diff --git a/src/WebService/Client.php b/src/WebService/Client.php
@@ -77,17 +77,17 @@ class Client
     private $accountId;
 
     /**
-     * @param int    $accountId  your MaxMind account ID
-     * @param string $licenseKey your MaxMind license key
-     * @param array  $options    an array of options. Possible keys:
-     *                           * `host` - The host to use when connecting to the web service.
-     *                           * `useHttps` - A boolean flag for sending the request via https.(True by default)
-     *                           * `userAgent` - The prefix of the User-Agent to use in the request.
-     *                           * `caBundle` - The bundle of CA root certificates to use in the request.
-     *                           * `connectTimeout` - The connect timeout to use for the request.
-     *                           * `timeout` - The timeout to use for the request.
-     *                           * `proxy` - The HTTP proxy to use. May include a schema, port,
-     *                           username, and password, e.g., `http://username:[email protected]:10`.
+     * @param int                  $accountId  your MaxMind account ID
+     * @param string               $licenseKey your MaxMind license key
+     * @param array<string, mixed> $options    an array of options. Possible keys:
+     *                                         * `host` - The host to use when connecting to the web service.
+     *                                         * `useHttps` - Set to false to disable HTTPS.
+     *                                         * `userAgent` - The prefix of the User-Agent to use in the request.
+     *                                         * `caBundle` - The bundle of CA root certificates to use in the request.
+     *                                         * `connectTimeout` - The connect timeout to use for the request.
+     *                                         * `timeout` - The timeout to use for the request.
+     *                                         * `proxy` - The HTTP proxy to use. May include a schema, port,
+     *                                         username, and password, e.g., `http://username:[email protected]:10`.
      */
     public function __construct(
         int $accountId,
@@ -127,9 +127,9 @@ public function __construct(
     }
 
     /**
-     * @param string $service name of the service querying
-     * @param string $path    the URI path to use
-     * @param array  $input   the data to be posted as JSON
+     * @param string       $service name of the service querying
+     * @param string       $path    the URI path to use
+     * @param array<mixed> $input   the data to be posted as JSON
      *
      * @throws InvalidInputException      when the request has missing or invalid
      *                                    data
@@ -142,7 +142,7 @@ public function __construct(
      * @throws WebServiceException        when some other error occurs. This also
      *                                    serves as the base class for the above exceptions.
      *
-     * @return array|null The decoded content of a successful response
+     * @return array<mixed>|null The decoded content of a successful response
      */
     public function post(string $service, string $path, array $input): ?array
     {
@@ -170,6 +170,9 @@ public function post(string $service, string $path, array $input): ?array
         );
     }
 
+    /**
+     * @return array<mixed>|null
+     */
     public function get(string $service, string $path): ?array
     {
         $request = $this->createRequest(
@@ -195,6 +198,9 @@ private function userAgent(): string
            ' curl/' . $curlVersion['version'];
     }
 
+    /**
+     * @param array<string> $headers
+     */
     private function createRequest(string $path, array $headers = []): Http\Request
     {
         array_push(
@@ -233,7 +239,7 @@ private function createRequest(string $path, array $headers = []): Http\Request
      * @throws WebServiceException        when some other error occurs. This also
      *                                    serves as the base class for the above exceptions
      *
-     * @return array|null The decoded content of a successful response
+     * @return array<mixed>|null The decoded content of a successful response
      */
     private function handleResponse(
         int $statusCode,
@@ -463,7 +469,7 @@ private function handleUnexpectedStatus(int $statusCode, string $service, string
      *                             included, or is expected and included
      *                             but cannot be decoded as JSON
      *
-     * @return array|null the decoded request body
+     * @return array<mixed>|null the decoded request body
      */
     private function handleSuccess(int $statusCode, ?string $body, string $service): ?array
     {

diff --git a/src/WebService/Http/CurlRequest.php b/src/WebService/Http/CurlRequest.php
@@ -24,10 +24,13 @@ class CurlRequest implements Request
     private $url;
 
     /**
-     * @var array
+     * @var array<string, mixed>
      */
     private $options;
 
+    /**
+     * @param array<string, mixed> $options
+     */
     public function __construct(string $url, array $options)
     {
         $this->url = $url;
@@ -37,6 +40,8 @@ public function __construct(string $url, array $options)
 
     /**
      * @throws HttpException
+     *
+     * @return array{0:int, 1:string|null, 2:string|null}
      */
     public function post(string $body): array
     {
@@ -48,6 +53,9 @@ public function post(string $body): array
         return $this->execute($curl);
     }
 
+    /**
+     * @return array{0:int, 1:string|null, 2:string|null}
+     */
     public function get(): array
     {
         $curl = $this->createCurl();
@@ -106,6 +114,8 @@ private function createCurl()
      * @param \CurlHandle $curl
      *
      * @throws HttpException
+     *
+     * @return array{0:int, 1:string|null, 2:string|null}
      */
     private function execute($curl): array
     {

diff --git a/src/WebService/Http/Request.php b/src/WebService/Http/Request.php
@@ -11,9 +11,18 @@
  */
 interface Request
 {
+    /**
+     * @param array<string, mixed> $options
+     */
     public function __construct(string $url, array $options);
 
+    /**
+     * @return array{0:int, 1:string|null, 2:string|null}
+     */
     public function post(string $body): array;
 
+    /**
+     * @return array{0:int, 1:string|null, 2:string|null}
+     */
     public function get(): array;
 }
diff --git a/src/WebService/Http/RequestFactory.php b/src/WebService/Http/RequestFactory.php
@@ -39,6 +39,9 @@ private function getCurlHandle()
         return $this->ch;
     }
 
+    /**
+     * @param array<string, mixed> $options
+     */
     public function request(string $url, array $options): Request
     {
         $options['curlHandle'] = $this->getCurlHandle();

diff --git a/tests/MaxMind/Test/WebService/ClientTest.php b/tests/MaxMind/Test/WebService/ClientTest.php
@@ -348,6 +348,9 @@ public function testGetInvalidAuth(string $code): void
         );
     }
 
+    /**
+     * @return array<int, list<string>>
+     */
     public function invalidAuthCodes(): array
     {
         return [
@@ -508,9 +511,13 @@ public function testGet500(): void
         $this->withResponseTestServer(500, 'application/json', '', 'get');
     }
 
-    // Convenience method when you don't care about the request
-    // It runs the request through the test server.
-    // This version is used for when we want to test with an actual server.
+    /**
+     * Convenience method when you don't care about the request
+     * It runs the request through the test server.
+     * This version is used for when we want to test with an actual server.
+     *
+     * @return array<mixed>|null
+     */
     private function withResponseTestServer(int $statusCode, string $contentType, string $body, string $httpMethod): ?array
     {
         // Set up the test server
@@ -535,7 +542,14 @@ private function withResponseTestServer(int $statusCode, string $contentType, st
         );
     }
 
-    // runs the request through the test server
+    /**
+     * Runs the request through the test server.
+     *
+     * @param array<mixed>         $requestContent
+     * @param array<string, mixed> $options
+     *
+     * @return array<mixed>|null
+     */
     private function runRequestTestServer(
         string $service,
         string $path,
@@ -558,7 +572,11 @@ private function runRequestTestServer(
         return $client->post($service, $path, $requestContent);
     }
 
-    // convenience method when you don't care about the request
+    /**
+     * Convenience method when you don't care about the request.
+     *
+     * @return array<mixed>|null
+     */
     private function withResponse(int $statusCode, string $contentType, string $body): ?array
     {
         return $this->runRequest(
@@ -571,8 +589,15 @@ private function withResponse(int $statusCode, string $contentType, string $body
         );
     }
 
-    // The other version of withResponse exists because some responses are not supported
-    // by the built-in php server, such as sending a body while having a status 204(No-content).
+    /**
+     * The other version of withResponse exists because some responses are not supported
+     * by the built-in php server, such as sending a body while having a status 204(No-content).
+     *
+     * @param array<mixed>         $requestContent
+     * @param array<string, mixed> $options
+     *
+     * @return array<mixed>|null
+     */
     private function runRequest(
         string $service,
         string $path,

diff --git a/tests/MaxMind/Test/WebService/Http/CurlRequestTest.php b/tests/MaxMind/Test/WebService/Http/CurlRequestTest.php
@@ -22,7 +22,7 @@
 class CurlRequestTest extends TestCase
 {
     /**
-     * @var array
+     * @var array<string, mixed>
      */
     private $options;
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,5 +3,4 @@ parameters: @@
         paths:
             - src
             - tests
-        checkMissingIterableValueType: false