Add reusable GeoIP client

composer.json

@@ -3,7 +3,7 @@
     "type": "project",
     "require": {
         "php": ">=8.3.0",
-        "utopia-php/fetch": "0.5.*",
+        "utopia-php/fetch": "^1.1",
         "utopia-php/http": "^2.0@RC",
         "utopia-php/platform": "^1.0@RC",
         "utopia-php/di": "0.3.*",

phpunit.xml

@@ -7,6 +7,9 @@
     testdox="true"
 >
     <testsuites>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
         <testsuite name="e2e">
             <directory>tests/E2E</directory>
         </testsuite>

src/Geo/GeoIp.php

@@ -0,0 +1,55 @@
+<?php
+
+namespace Appwrite\Geo;
+
+use Throwable;
+use Utopia\Fetch\Client;
+
+final readonly class GeoIp
+{
+    private Client $client;
+
+    public function __construct(
+        private string $endpoint,
+        private string $secret,
+        ?Client $client = null,
+    ) {
+        $this->client = $client ?? new Client();
+        $this->client
+            ->addHeader('Accept', Client::CONTENT_TYPE_APPLICATION_JSON)
+            ->setTimeout(1000);
+    }
+
+    public function getCountryCode(string $ip): ?string
+    {
+        $geo = $this->get($ip);
+
+        return $geo?->getCountryCode();
+    }
+
+    public function get(string $ip): ?GeoRecord
+    {
+        if ($this->endpoint === '' || $this->secret === '') {
+            return null;
+        }
+
+        try {
+            $response = $this->client
+                ->addHeader('Authorization', 'Bearer ' . $this->secret)
+                ->fetch(
+                    \rtrim($this->endpoint, '/') . '/v1/ips/' . \rawurlencode($ip),
+                    Client::METHOD_GET,
+                );
+
+            if ($response->getStatusCode() >= 400) {
+                return null;
+            }
+
+            $body = \json_decode((string) $response->getBody(), true);
+        } catch (Throwable) {
+            return null;
+        }
+
+        return \is_array($body) ? GeoRecord::fromArray($body) : null;
+    }
+}

src/Geo/GeoRecord.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace Appwrite\Geo;
+
+final readonly class GeoRecord
+{
+    /**
+     * @param array<string, mixed> $data
+     */
+    public function __construct(
+        private array $data,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    public function getCountryCode(): ?string
+    {
+        $countryCode = $this->data['countryCode'] ?? null;
+
+        return \is_string($countryCode) && $countryCode !== ''
+            ? $countryCode
+            : null;
+    }
+
+    public function get(string $key): mixed
+    {
+        return $this->data[$key] ?? null;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}

tests/Unit/GeoIpTest.php

@@ -0,0 +1,134 @@
+<?php
+
+namespace Tests\Unit;
+
+use Appwrite\Geo\GeoIp;
+use Appwrite\Geo\GeoRecord;
+use PHPUnit\Framework\TestCase;
+use RuntimeException;
+use Utopia\Fetch\Client as FetchClient;
+use Utopia\Fetch\Response;
+
+final class GeoIpTest extends TestCase
+{
+    public function testGetReturnsGeoRecord(): void
+    {
+        $client = $this->createMock(FetchClient::class);
+        $client
+            ->expects($this->exactly(2))
+            ->method('addHeader')
+            ->willReturnCallback(function (string $key, string $value) use ($client): FetchClient {
+                if ($key === 'Authorization') {
+                    $this->assertSame('Bearer secret', $value);
+                    return $client;
+                }
+
+                $this->assertSame('Accept', $key);
+                $this->assertSame(FetchClient::CONTENT_TYPE_APPLICATION_JSON, $value);
+
+                return $client;
+            });
+        $client
+            ->expects($this->once())
+            ->method('setTimeout')
+            ->with(1000)
+            ->willReturn($client);
+        $client
+            ->expects($this->once())
+            ->method('fetch')
+            ->with('http://geo/v1/ips/8.8.8.8', FetchClient::METHOD_GET)
+            ->willReturn(new Response(200, '{"countryCode":"US","city":{"en":"Mountain View"}}', []));
+
+        $geo = new GeoIp('http://geo/', 'secret', $client);
+        $record = $geo->get('8.8.8.8');
+
+        $this->assertInstanceOf(GeoRecord::class, $record);
+        $this->assertSame('US', $record->getCountryCode());
+        $this->assertSame(['en' => 'Mountain View'], $record->get('city'));
+        $this->assertSame([
+            'countryCode' => 'US',
+            'city' => [
+                'en' => 'Mountain View',
+            ],
+        ], $record->toArray());
+    }
+
+    public function testGetCountryCodeReturnsCountryCode(): void
+    {
+        $geo = new GeoIp('http://geo', 'secret', $this->clientReturning(new Response(200, '{"countryCode":"US"}', [])));
+
+        $this->assertSame('US', $geo->getCountryCode('8.8.8.8'));
+    }
+
+    public function testGetCountryCodeReturnsNullWhenCountryCodeIsMissing(): void
+    {
+        $geo = new GeoIp('http://geo', 'secret', $this->clientReturning(new Response(200, '{}', [])));
+
+        $this->assertNull($geo->getCountryCode('8.8.8.8'));
+    }
+
+    public function testGetReturnsNullOnHttpErrors(): void
+    {
+        $geo = new GeoIp('http://geo', 'secret', $this->clientReturning(new Response(500, '{}', [])));
+
+        $this->assertNull($geo->get('8.8.8.8'));
+    }
+
+    public function testGetReturnsNullOnInvalidJson(): void
+    {
+        $geo = new GeoIp('http://geo', 'secret', $this->clientReturning(new Response(200, 'not-json', [])));
+
+        $this->assertNull($geo->get('8.8.8.8'));
+    }
+
+    public function testGetReturnsNullOnFetchExceptions(): void
+    {
+        $client = $this->createStub(FetchClient::class);
+        $client
+            ->method('addHeader')
+            ->willReturn($client);
+        $client
+            ->method('setTimeout')
+            ->willReturn($client);
+        $client
+            ->method('fetch')
+            ->willThrowException(new RuntimeException('timeout'));
+
+        $geo = new GeoIp('http://geo', 'secret', $client);
+
+        $this->assertNull($geo->get('8.8.8.8'));
+    }
+
+    public function testGetDoesNotCallClientWithoutEndpointOrSecret(): void
+    {
+        $client = $this->createMock(FetchClient::class);
+        $client
+            ->method('addHeader')
+            ->willReturn($client);
+        $client
+            ->method('setTimeout')
+            ->willReturn($client);
+        $client
+            ->expects($this->never())
+            ->method('fetch');
+
+        $this->assertNull(new GeoIp('', 'secret', $client)->get('8.8.8.8'));
+        $this->assertNull(new GeoIp('http://geo', '', $client)->get('8.8.8.8'));
+    }
+
+    private function clientReturning(Response $response): FetchClient
+    {
+        $client = $this->createStub(FetchClient::class);
+        $client
+            ->method('addHeader')
+            ->willReturn($client);
+        $client
+            ->method('setTimeout')
+            ->willReturn($client);
+        $client
+            ->method('fetch')
+            ->willReturn($response);
+
+        return $client;
+    }
+}