Merge pull request #243 from maxmind/greg/eng-1813

Add Anonymous Plus support

Author: faktas2

CHANGELOG.md

@@ -4,6 +4,9 @@ CHANGELOG
 3.2.0
 ------------------
 
+* Support for the GeoIP Anonymous Plus database has been added. To do a
+  lookup in this database, use the `anonymousPlus` method on
+  `GeoIP2\Database\Reader`.
 * `metroCode` on `GeoIp2\Record\Location` has been deprecated. The code
   values are no longer being maintained.
 

README.md

@@ -162,6 +162,28 @@ print($record->network . "\n"); // '128.101.101.101/32'
 
 ```
 
+### Anonymous Plus Example ###
+
+```php
+<?php
+require_once 'vendor/autoload.php';
+use GeoIp2\Database\Reader;
+
+// This creates the Reader object, which should be reused across
+// lookups.
+$anonymousDbReader = new Reader('/usr/local/share/GeoIP/GeoIP-Anonymous-Plus.mmdb');
+
+$record = $anonymousDbReader->anonymousIp('203.0.113.0');
+
+print($record->anonymizerConfidence . "\n"); // 30
+print($record->networkLastSeen . "\n"); // '2025-04-14'
+print($record->providerName . "\n"); // 'FooBar VPN'
+
+print($record->ipAddress . "\n"); // '203.0.113.0'
+print($record->network . "\n"); // '203.0.113.0/32'
+
+```
+
 ### Connection-Type Example ###
 
 ```php

maxmind-db

@@ -6,6 +6,7 @@
 
 use GeoIp2\Exception\AddressNotFoundException;
 use GeoIp2\Model\AnonymousIp;
+use GeoIp2\Model\AnonymousPlus;
 use GeoIp2\Model\Asn;
 use GeoIp2\Model\City;
 use GeoIp2\Model\ConnectionType;
@@ -44,14 +45,8 @@
  */
 class Reader implements ProviderInterface
 {
-    private DbReader $dbReader;
-
-    private string $dbType;
-
-    /**
-     * @var array<string>
-     */
-    private array $locales;
+    private readonly DbReader $dbReader;
+    private readonly string $dbType;
 
     /**
      * Constructor.
@@ -64,11 +59,11 @@ class Reader implements ProviderInterface
      */
     public function __construct(
         string $filename,
-        array $locales = ['en']
+        /** @var array<string> */
+        public readonly array $locales = ['en']
     ) {
         $this->dbReader = new DbReader($filename);
         $this->dbType = $this->dbReader->metadata()->databaseType;
-        $this->locales = $locales;
     }
 
     /**
@@ -78,6 +73,7 @@ public function __construct(
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function city(string $ipAddress): City
     {
@@ -91,6 +87,7 @@ public function city(string $ipAddress): City
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function country(string $ipAddress): Country
     {
@@ -104,6 +101,7 @@ public function country(string $ipAddress): Country
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function anonymousIp(string $ipAddress): AnonymousIp
     {
@@ -114,13 +112,32 @@ public function anonymousIp(string $ipAddress): AnonymousIp
         );
     }
 
+    /**
+     * This method returns a GeoIP Anonymous Plus model.
+     *
+     * @param string $ipAddress an IPv4 or IPv6 address as a string
+     *
+     * @throws AddressNotFoundException if the address is not in the database
+     * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
+     */
+    public function anonymousPlus(string $ipAddress): AnonymousPlus
+    {
+        return $this->flatModelFor(
+            AnonymousPlus::class,
+            'GeoIP-Anonymous-Plus',
+            $ipAddress
+        );
+    }
+
     /**
      * This method returns a GeoLite2 ASN model.
      *
      * @param string $ipAddress an IPv4 or IPv6 address as a string
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function asn(string $ipAddress): Asn
     {
@@ -138,6 +155,7 @@ public function asn(string $ipAddress): Asn
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function connectionType(string $ipAddress): ConnectionType
     {
@@ -155,6 +173,7 @@ public function connectionType(string $ipAddress): ConnectionType
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function domain(string $ipAddress): Domain
     {
@@ -172,6 +191,7 @@ public function domain(string $ipAddress): Domain
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function enterprise(string $ipAddress): Enterprise
     {
@@ -185,6 +205,7 @@ public function enterprise(string $ipAddress): Enterprise
      *
      * @throws AddressNotFoundException if the address is not in the database
      * @throws InvalidDatabaseException if the database is corrupt or invalid
+     * @throws \BadMethodCallException  if this database type is not supported
      */
     public function isp(string $ipAddress): Isp
     {

src/Database/Reader.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace GeoIp2\Model;
+
+/**
+ * This class provides the GeoIP Anonymous Plus model.
+ */
+class AnonymousPlus extends AnonymousIp
+{
+    /**
+     * @var int|null a score ranging from 1 to 99 that is our percent
+     *               confidence that the network is currently part of
+     *               an actively used VPN service
+     */
+    public readonly ?int $anonymizerConfidence;
+
+    /**
+     * @var string|null The last day that the network was sighted in our
+     *                  analysis of anonymized networks. This is in the ISO
+     *                  8601 date format, e.g., "2025-04-21".
+     */
+    public readonly ?string $networkLastSeen;
+
+    /**
+     * @var string|null The name of the VPN provider (e.g., NordVPN,
+     *                  SurfShark, etc.) associated with the network.
+     */
+    public readonly ?string $providerName;
+
+    /**
+     * @ignore
+     *
+     * @param array<string, mixed> $raw
+     */
+    public function __construct(array $raw)
+    {
+        parent::__construct($raw);
+        $this->anonymizerConfidence = $raw['anonymizer_confidence'] ?? null;
+        $this->networkLastSeen = $raw['network_last_seen'] ?? null;
+        $this->providerName = $raw['provider_name'] ?? null;
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function jsonSerialize(): ?array
+    {
+        $js = parent::jsonSerialize();
+
+        if ($this->anonymizerConfidence !== null) {
+            $js['anonymizer_confidence'] = $this->anonymizerConfidence;
+        }
+
+        if ($this->networkLastSeen !== null) {
+            $js['network_last_seen'] = $this->networkLastSeen;
+        }
+
+        if ($this->providerName !== null) {
+            $js['provider_name'] = $this->providerName;
+        }
+
+        return $js;
+    }
+}

src/Model/AnonymousPlus.php

@@ -51,11 +51,7 @@
  */
 class Client implements ProviderInterface
 {
-    /**
-     * @var array<string>
-     */
-    private array $locales;
-    private WsClient $client;
+    private readonly WsClient $client;
     private static string $basePath = '/geoip/v2.1';
 
     public const VERSION = 'v3.1.0';
@@ -86,21 +82,18 @@ class Client implements ProviderInterface
     public function __construct(
         int $accountId,
         string $licenseKey,
-        array $locales = ['en'],
+        /** @var list<string> */
+        public readonly array $locales = ['en'], // Promoted and readonly
         array $options = []
     ) {
-        $this->locales = $locales;
-
         // This is for backwards compatibility. Do not remove except for a
         // major version bump.
         // @phpstan-ignore-next-line
         if (\is_string($options)) {
             $options = ['host' => $options];
         }
 
-        if (!isset($options['host'])) {
-            $options['host'] = 'geoip.maxmind.com';
-        }
+        $options['host'] ??= 'geoip.maxmind.com';
 
         $options['userAgent'] = $this->userAgent();
 
@@ -139,7 +132,6 @@ private function userAgent(): string
      */
     public function city(string $ipAddress = 'me'): City
     {
-        // @phpstan-ignore-next-line
         return $this->responseFor('city', City::class, $ipAddress);
     }
 
@@ -201,11 +193,29 @@ public function country(string $ipAddress = 'me'): Country
      */
     public function insights(string $ipAddress = 'me'): Insights
     {
-        // @phpstan-ignore-next-line
         return $this->responseFor('insights', Insights::class, $ipAddress);
     }
 
-    private function responseFor(string $endpoint, string $class, string $ipAddress): Country
+    /**
+     * Generic helper method to call an endpoint and return the corresponding model.
+     *
+     * @template TModel of City|Country|Insights
+     *
+     * @param 'city'|'country'|'insights' $endpoint  the endpoint name
+     * @param class-string<TModel>        $class     The specific model class string (e.g., City::class)
+     * @param string                      $ipAddress the IP address or 'me'
+     *
+     * @throws AddressNotFoundException
+     * @throws AuthenticationException
+     * @throws OutOfQueriesException
+     * @throws InvalidRequestException
+     * @throws HttpException
+     * @throws GeoIp2Exception
+     * @throws \InvalidArgumentException
+     *
+     * @return TModel the corresponding model object, matching the passed class string
+     */
+    private function responseFor(string $endpoint, string $class, string $ipAddress): City|Country|Insights
     {
         if ($ipAddress !== 'me' && !filter_var($ipAddress, \FILTER_VALIDATE_IP)) {
             throw new \InvalidArgumentException(

src/WebService/Client.php

@@ -152,6 +152,30 @@ public function testAnonymousIpAllTrue(): void
         $reader->close();
     }
 
+    public function testAnonymousPlus(): void
+    {
+        $reader = new Reader('maxmind-db/test-data/GeoIP-Anonymous-Plus-Test.mmdb');
+        $ipAddress = '1.2.0.1';
+
+        $record = $reader->anonymousPlus($ipAddress);
+
+        $this->assertSame($record->anonymizerConfidence, 30);
+        $this->assertTrue($record->isAnonymous);
+        $this->assertTrue($record->isAnonymousVpn);
+        $this->assertFalse($record->isHostingProvider);
+        $this->assertFalse($record->isPublicProxy);
+        $this->assertFalse($record->isResidentialProxy);
+        $this->assertFalse($record->isTorExitNode);
+        $this->assertSame($record->networkLastSeen, '2025-04-14');
+        $this->assertSame($record->providerName, 'foo');
+
+
+        $this->assertSame($ipAddress, $record->ipAddress);
+        $this->assertSame('1.2.0.1/32', $record->network);
+
+        $reader->close();
+    }
+
     public function testAsn(): void
     {
         $reader = new Reader('maxmind-db/test-data/GeoLite2-ASN-Test.mmdb');