Improve PHPStan type hints

CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+3.1.0
+------------------
+
+* The PHPDoc type hints have been improved for use with PHPStan.
+
 3.0.0 (2023-12-04)
 ------------------
 

src/Database/Reader.php

@@ -56,9 +56,9 @@ class Reader implements ProviderInterface
     /**
      * Constructor.
      *
-     * @param string $filename the path to the GeoIP2 database file
-     * @param array  $locales  list of locale codes to use in name property
-     *                         from most preferred to least preferred
+     * @param string        $filename the path to the GeoIP2 database file
+     * @param array<string> $locales  list of locale codes to use in name property
+     *                                from most preferred to least preferred
      *
      * @throws InvalidDatabaseException if the database is corrupt or invalid
      */
@@ -215,6 +215,9 @@ private function flatModelFor(string $class, string $type, string $ipAddress): o
         return new $class($record);
     }
 
+    /**
+     * @return array{0:array<string, mixed>, 1:int}
+     */
     private function getRecord(string $class, string $type, string $ipAddress): array
     {
         if (!str_contains($this->dbType, $type)) {

src/Model/AnonymousIp.php

@@ -64,6 +64,8 @@ class AnonymousIp implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
      */
     public function __construct(array $raw)
     {
@@ -78,6 +80,9 @@ public function __construct(array $raw)
         $this->network = Util::cidr($ipAddress, $raw['prefix_len']);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Model/Asn.php

@@ -39,6 +39,8 @@ class Asn implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
      */
     public function __construct(array $raw)
     {
@@ -50,6 +52,9 @@ public function __construct(array $raw)
         $this->network = Util::cidr($ipAddress, $raw['prefix_len']);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Model/City.php

@@ -60,6 +60,9 @@ class City extends Country
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
+     * @param list<string>         $locales
      */
     public function __construct(array $raw, array $locales = ['en'])
     {
@@ -90,6 +93,9 @@ public function __construct(array $raw, array $locales = ['en'])
         $this->subdivisions = $subdivisions;
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = parent::jsonSerialize();

src/Model/ConnectionType.php

@@ -33,6 +33,8 @@ class ConnectionType implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
      */
     public function __construct(array $raw)
     {
@@ -42,6 +44,9 @@ public function __construct(array $raw)
         $this->network = Util::cidr($ipAddress, $raw['prefix_len']);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Model/Country.php

@@ -58,6 +58,9 @@ class Country implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
+     * @param list<string>         $locales
      */
     public function __construct(array $raw, array $locales = ['en'])
     {
@@ -81,6 +84,9 @@ public function __construct(array $raw, array $locales = ['en'])
         $this->traits = new Traits($raw['traits'] ?? []);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Model/Domain.php

@@ -33,6 +33,8 @@ class Domain implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
      */
     public function __construct(array $raw)
     {
@@ -42,6 +44,9 @@ public function __construct(array $raw)
         $this->network = Util::cidr($ipAddress, $raw['prefix_len']);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Model/Isp.php

@@ -65,6 +65,8 @@ class Isp implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $raw
      */
     public function __construct(array $raw)
     {
@@ -81,6 +83,9 @@ public function __construct(array $raw)
         $this->network = Util::cidr($ipAddress, $raw['prefix_len']);
     }
 
+    /**
+     * @return array<string, mixed>|null
+     */
     public function jsonSerialize(): ?array
     {
         $js = [];

src/Record/AbstractNamedRecord.php

@@ -14,14 +14,17 @@ abstract class AbstractNamedRecord implements \JsonSerializable
     public readonly ?string $name;
 
     /**
-     * @var array An array map where the keys are locale codes
-     *            and the values are names. This attribute is returned by all location
-     *            services and databases.
+     * @var array<string, string> An array map where the keys are locale codes
+     *                            and the values are names. This attribute is returned by all location
+     *                            services and databases.
      */
     public readonly array $names;
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -37,6 +40,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->name = null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = [];

src/Record/AbstractPlaceRecord.php

@@ -21,6 +21,9 @@ abstract class AbstractPlaceRecord extends AbstractNamedRecord
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -30,6 +33,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->geonameId = $record['geoname_id'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();

src/Record/Continent.php

@@ -26,6 +26,9 @@ class Continent extends AbstractNamedRecord
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -35,6 +38,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->geonameId = $record['geoname_id'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();

src/Record/Country.php

@@ -27,6 +27,9 @@ class Country extends AbstractPlaceRecord
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -36,6 +39,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->isoCode = $record['iso_code'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();

src/Record/Location.php

@@ -64,6 +64,11 @@ class Location implements \JsonSerializable
      */
     public readonly ?string $timeZone;
 
+    /**
+     * @ignore
+     *
+     * @param array<string, mixed> $record
+     */
     public function __construct(array $record)
     {
         $this->averageIncome = $record['average_income'] ?? null;
@@ -75,6 +80,9 @@ public function __construct(array $record)
         $this->timeZone = $record['time_zone'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = [];

src/Record/MaxMind.php

@@ -17,11 +17,19 @@ class MaxMind implements \JsonSerializable
      */
     public readonly ?int $queriesRemaining;
 
+    /**
+     * @ignore
+     *
+     * @param array<string, mixed> $record
+     */
     public function __construct(array $record)
     {
         $this->queriesRemaining = $record['queries_remaining'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = [];

src/Record/Postal.php

@@ -30,13 +30,18 @@ class Postal implements \JsonSerializable
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
      */
     public function __construct(array $record)
     {
         $this->code = $record['code'] ?? null;
         $this->confidence = $record['confidence'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = [];

src/Record/RepresentedCountry.php

@@ -22,6 +22,9 @@ class RepresentedCountry extends Country
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -30,6 +33,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->type = $record['type'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();

src/Record/Subdivision.php

@@ -22,6 +22,9 @@ class Subdivision extends AbstractPlaceRecord
 
     /**
      * @ignore
+     *
+     * @param array<string, mixed> $record
+     * @param list<string>         $locales
      */
     public function __construct(array $record, array $locales = ['en'])
     {
@@ -30,6 +33,9 @@ public function __construct(array $record, array $locales = ['en'])
         $this->isoCode = $record['iso_code'] ?? null;
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = parent::jsonSerialize();

src/Record/Traits.php

@@ -196,6 +196,11 @@ class Traits implements \JsonSerializable
      */
     public readonly ?string $userType;
 
+    /**
+     * @ignore
+     *
+     * @param array<string, mixed> $record
+     */
     public function __construct(array $record)
     {
         $this->autonomousSystemNumber = $record['autonomous_system_number'] ?? null;
@@ -226,6 +231,9 @@ public function __construct(array $record)
         }
     }
 
+    /**
+     * @return array<string, mixed>
+     */
     public function jsonSerialize(): array
     {
         $js = [];