Improve the type hints for arrays

maxmind · Nov 14, 2024 · 7297c4f · 7297c4f
1 parent cbf37b8
commit 7297c4f
Show file tree

Hide file tree

Showing 6 changed files with 39 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ CHANGELOG
 
 * Improve the error handling when the user tries to open a directory
   with the pure PHP reader.
+* Improve the typehints on arrays in the PHPDocs.
 
 1.11.1 (2023-12-01)
 -------------------

diff --git a/src/MaxMind/Db/Reader.php b/src/MaxMind/Db/Reader.php
@@ -149,8 +149,8 @@ public function get(string $ipAddress)
      *                                   if the database is invalid or there is an error reading
      *                                   from it
      *
-     * @return array an array where the first element is the record and the
-     *               second the network prefix length for the record
+     * @return array{0:mixed, 1:int} an array where the first element is the record and the
+     *                               second the network prefix length for the record
      */
     public function getWithPrefixLen(string $ipAddress): array
     {
@@ -174,6 +174,9 @@ public function getWithPrefixLen(string $ipAddress): array
         return [$this->resolveDataPointer($pointer), $prefixLen];
     }
 
+    /**
+     * @return array{0:int, 1:int}
+     */
     private function findAddressInTree(string $ipAddress): array
     {
         $packedAddr = @inet_pton($ipAddress);

diff --git a/src/MaxMind/Db/Reader/Decoder.php b/src/MaxMind/Db/Reader/Decoder.php
@@ -63,6 +63,9 @@ public function __construct(
         $this->switchByteOrder = $this->isPlatformLittleEndian();
     }
 
+    /**
+     * @return array<mixed>
+     */
     public function decode(int $offset): array
     {
         $ctrlByte = \ord(Util::read($this->fileStream, $offset, 1));
@@ -110,6 +113,8 @@ public function decode(int $offset): array
 
     /**
      * @param int<0, max> $size
+     *
+     * @return array{0:mixed, 1:int}
      */
     private function decodeByType(int $type, int $offset, int $size): array
     {
@@ -167,6 +172,9 @@ private function verifySize(int $expected, int $actual): void
         }
     }
 
+    /**
+     * @return array{0:array<mixed>, 1:int}
+     */
     private function decodeArray(int $size, int $offset): array
     {
         $array = [];
@@ -247,6 +255,9 @@ private function decodeInt32(string $bytes, int $size): int
         return $int;
     }
 
+    /**
+     * @return array{0:array<string, mixed>, 1:int}
+     */
     private function decodeMap(int $size, int $offset): array
     {
         $map = [];
@@ -260,6 +271,9 @@ private function decodeMap(int $size, int $offset): array
         return [$map, $offset];
     }
 
+    /**
+     * @return array{0:int, 1:int}
+     */
     private function decodePointer(int $ctrlByte, int $offset): array
     {
         $pointerSize = (($ctrlByte >> 3) & 0x3) + 1;
@@ -378,6 +392,9 @@ private function decodeUint(string $bytes, int $byteLength)
         return $integerAsString;
     }
 
+    /**
+     * @return array{0:int, 1:int}
+     */
     private function sizeFromCtrlByte(int $ctrlByte, int $offset): array
     {
         $size = $ctrlByte & 0x1F;

diff --git a/src/MaxMind/Db/Reader/Metadata.php b/src/MaxMind/Db/Reader/Metadata.php
@@ -48,7 +48,7 @@ class Metadata
      * in that language as a UTF-8 string. May be undefined for some
      * databases.
      *
-     * @var array
+     * @var array<string, string>
      */
     public $description;
 
@@ -65,7 +65,7 @@ class Metadata
      * may contain data items that have been localized to some or all of
      * these languages. This may be undefined.
      *
-     * @var array
+     * @var array<string>
      */
     public $languages;
 
@@ -95,6 +95,9 @@ class Metadata
      */
     public $searchTreeSize;
 
+    /**
+     * @param array<string, mixed> $metadata
+     */
     public function __construct(array $metadata)
     {
         if (\func_num_args() !== 1) {

diff --git a/tests/MaxMind/Db/Test/Reader/DecoderTest.php b/tests/MaxMind/Db/Test/Reader/DecoderTest.php
@@ -291,6 +291,9 @@ private function bytes(): array
         return $bytes;
     }
 
+    /**
+     * @return array<int, array<int>>
+     */
     public function generateLargeUint(int $bits): array
     {
         $ctrlByte = $bits === 64 ? 0x2 : 0x3;
@@ -384,13 +387,19 @@ public function testUint128(): void
         $this->validateTypeDecoding('uint128', $this->generateLargeUint(128));
     }
 
+    /**
+     * @param array<mixed> $tests
+     */
     private function validateTypeDecoding(string $type, array $tests): void
     {
         foreach ($tests as $expected => $input) {
             $this->checkDecoding($type, $input, $expected);
         }
     }
 
+    /**
+     * @param array<mixed> $tests
+     */
     private function validateTypeDecodingList(string $type, array $tests): void
     {
         foreach ($tests as $test) {

diff --git a/tests/MaxMind/Db/Test/ReaderTest.php b/tests/MaxMind/Db/Test/ReaderTest.php
@@ -364,12 +364,12 @@ public function testMetadataArgs(): void
 
     public function testClose(): void
     {
+        $this->expectNotToPerformAssertions();
+
         $reader = new Reader(
             'tests/data/test-data/MaxMind-DB-test-decoder.mmdb'
         );
         $reader->close();
-
-        $this->assertTrue(true);
     }
 
     public function testCloseArgs(): void