PHP SDK

The PHP SDK provides an easy-to-use interface for integrating GeoIP lookups into your PHP applications.

Installation

Install via Composer:

composer require synthient/geoip-php

Quick Start

<?php
require_once 'vendor/autoload.php';

use Synthient\GeoIP\GeoIPClient;

$client = new GeoIPClient();

try {
    // Get current IP address
    $currentIp = $client->getIp();
    echo "Your IP: " . $currentIp . "\n";
    
    // Get detailed geolocation data
    $geoData = $client->getIpData();
    echo "Location: " . $geoData->country->city . ", " . $geoData->country->name . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

Configuration

Configure the client with custom options:

$client = new GeoIPClient([
    'base_url' => 'https://api.geoipapi.com',
    'timeout' => 30,
    'verify_ssl' => true
]);

Available Methods

getIp()

Get your current public IP address:

$currentIp = $client->getIp();
echo "Current IP: " . $currentIp . "\n";

getIpData()

Get comprehensive geolocation data:

$geoData = $client->getIpData();

echo "Country: " . $geoData->country->name . "\n";
echo "City: " . $geoData->country->city . "\n";
echo "Coordinates: " . $geoData->location->latitude . ", " . $geoData->location->longitude . "\n";
echo "ISP: " . $geoData->asn->name . "\n";

Response Structure

class GeoIPResponse
{
    public string $ip;
    public string $type;
    public Country $country;
    public Location $location;
    public ASN $asn;
}

class Country
{
    public bool $is_eu_member;
    public string $currency_code;
    public string $continent;
    public string $name;
    public string $country_code;
    public string $state;
    public string $city;
    public string $zip;
    public string $timezone;
}

class Location
{
    public float $latitude;
    public float $longitude;
}

class ASN
{
    public int $number;
    public string $name;
    public string $network;
    public string $type;
}

Error Handling

Handle different types of errors:

use Synthient\GeoIP\Exceptions\InvalidIPException;
use Synthient\GeoIP\Exceptions\RateLimitException;
use Synthient\GeoIP\Exceptions\GeoIPException;

try {
    $result = $client->getIpData();
    echo "Success: " . json_encode($result) . "\n";
} catch (InvalidIPException $e) {
    echo "Invalid IP address: " . $e->getMessage();
} catch (RateLimitException $e) {
    echo "Rate limit exceeded: " . $e->getMessage();
} catch (GeoIPException $e) {
    echo "General error: " . $e->getMessage();
}

Laravel Integration

Add to your Laravel application:

// In config/services.php
'geoip' => [
    'base_url' => env('GEOIP_BASE_URL', 'https://api.geoipapi.com'),
],

// In a service provider
$this->app->singleton(GeoIPClient::class, function ($app) {
    return new GeoIPClient([
        'base_url' => config('services.geoip.base_url')
    ]);
});

// In your controller or service
public function getLocationData()
{
    $geoIP = app(GeoIPClient::class);
    
    $currentIp = $geoIP->getIp();
    $locationData = $geoIP->getIpData();
    
    return response()->json([
        'ip' => $currentIp,
        'location' => $locationData
    ]);
}

Symfony Integration

Register as a service in Symfony:

# config/services.yaml
services:
    Synthient\GeoIP\GeoIPClient:
        arguments:
            $config:
                base_url: '%env(GEOIP_BASE_URL)%'
                timeout: 30

// In your controller
use Synthient\GeoIP\GeoIPClient;

public function locationAction(GeoIPClient $geoIP)
{
    $currentIp = $geoIP->getIp();
    $locationData = $geoIP->getIpData();
    
    return $this->json([
        'ip' => $currentIp,
        'location' => $locationData
    ]);
}

Advanced Usage

Custom HTTP client configuration:

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

// Create custom Guzzle client with retry middleware
$stack = HandlerStack::create();
$stack->push(Middleware::retry(function ($retries, $request, $response, $exception) {
    return $retries < 3 && ($exception || ($response && $response->getStatusCode() >= 500));
}));

$httpClient = new Client([
    'handler' => $stack,
    'timeout' => 30,
]);

$client = new GeoIPClient(['http_client' => $httpClient]);

Environment Variables

Set environment variables for configuration:

# .env file
GEOIP_BASE_URL=https://api.geoipapi.com
GEOIP_TIMEOUT=30