PHP SDK

Overview

The IPFly PHP SDK wraps the IPFly API in a single dependency-free file. It uses the curl extension when available for real parallel batch lookups, and falls back to PHP's built-in streams otherwise — so your integration code can stay focused on what to do with the response instead of the transport layer.

Where This SDK Belongs

If you need geolocation results in a frontend app, put this SDK behind your own endpoint and call that endpoint from the client (see the Laravel proxy example below), or use the IPFly JavaScript SDK with a domain-restricted token for prototyping.

Installation

No Composer package is published — copy ipfly_sdk.php into your project.

# Drop ipfly_sdk.php directly into your source tree, e.g.:
cp ipfly_sdk.php src/IPFly/ipfly_sdk.php

curl -O https://ipfly.world/libs/php-sdk/ipfly_sdk
# or
wget https://ipfly.world/libs/php-sdk/ipfly_sdk

<?php
require_once __DIR__ . '/ipfly_sdk.php';

use IPFly\IPFlyClient;
use IPFly\IPFlyException;

$client = new IPFlyClient('YOUR_TOKEN');

Requirements

PHP 7.4 or later. The curl extension is optional but recommended — it enables real parallel batch lookups and more precise timeouts; without it the SDK falls back to PHP's stream wrappers automatically. The apcu extension is only needed if you choose 'storage' => 'apcu' for the cache.

Quick Start

Create a client once, then call lookup() wherever you need geolocation data.

<?php
require_once 'ipfly_sdk.php';

use IPFly\IPFlyClient;
use IPFly\IPFlyException;

$client = new IPFlyClient('YOUR_TOKEN', [
    'include' => 'security', // optional: request the security/ASN field set on every call
]);

// Look up a specific IP
$data = $client->lookup('8.8.8.8');
echo $data['city'], ' ', $data['country_name'], "\n";

// Look up the caller's own IP (omit the ip argument)
$me = $client->lookupSelf();
echo "You appear to be in {$me['city']}\n";

// Handle errors explicitly
try {
    $client->lookup('not-an-ip');
} catch (IPFlyException $err) {
    echo $err->getErrorCode(), ': ', $err->getMessage(), "\n";
}

Client Options

The second constructor argument is an options array: new IPFlyClient($token, [...]).

Cache Options

Passed as the cache array, e.g. new IPFlyClient($token, ['cache' => ['storage' => 'apcu', 'ttl' => 3600]]).

Which storage should I pick?

'memory' lives only for the current request/process — fine for CLI scripts, mostly useless for a typical PHP-FPM app where each request is a fresh process. 'file' persists a shared JSON file across requests; simple and portable, best at low/medium traffic. 'apcu' is shared in-memory across PHP-FPM workers on the same machine with no disk I/O — the best choice for a typical web app, if the extension is installed.

lookup() & lookupSelf()

lookup(?string $ip = null, array $options = []): array looks up a single IP. Pass null (or omit) to geolocate the caller — or use the lookupSelf(array $options = []) shorthand.

$client->lookup('1.1.1.1', [
    'include' => 'security', // overrides the client-level `include` for this call only
    'skip_cache' => true,     // force a fresh network request, bypassing the cache
    'timeout' => 3.0,          // override the client's default timeout for this call
]);

Returns the parsed JSON response as an associative array (see Response Shape). Throws IPFlyException on failure (see Error Handling).

batchLookup()

batchLookup(array $ips, ?int $concurrency = null, array $options = []): BatchResult[] looks up an array of IPs. When the curl extension is loaded this runs genuinely in parallel via curl_multi, bounded by $concurrency; otherwise it falls back to a sequential loop automatically. This call never throws for an individual IP failure — it returns a list of BatchResult in the same order as $ips.

use IPFly\BatchResult;

$results = $client->batchLookup(['8.8.8.8', '1.1.1.1', 'not-an-ip']);
foreach ($results as $r) {
    if ($r->ok) {
        echo "{$r->ip} -> {$r->data['city']}\n";
    } else {
        echo "{$r->ip} failed: {$r->error->getErrorCode()}\n";
    }
}

BatchResult is a small value object: public string $ip, public bool $ok, public ?array $data, public ?IPFlyException $error.

Cache Controls

is_valid_ip()

A namespaced function that validates an IPv4 or IPv6 string without making a request.

use function IPFly\is_valid_ip;

is_valid_ip('8.8.8.8');               // true
is_valid_ip('2001:4860:4860::8888');  // true
is_valid_ip('not-an-ip');             // false

Response Shape

Successful lookups return the same JSON structure the IPFly API returns, unchanged, as a PHP associative array — see the full field reference in the API docs. Shape depends on your plan and the include value requested.

[
    'ip' => '8.8.8.8',
    'hostname' => 'dns.google',
    'country_name' => 'United States',
    'city' => 'Mountain View',
    'latitude' => '37.4056',
    'longitude' => '-122.0775',
    'time_zone' => ['name' => 'America/New_York', /* ... */],
    'asn' => ['asn' => 'AS15169', 'name' => 'Google LLC', /* ... */],
    'security' => ['is_vpn' => false, 'is_tor' => false, /* ... */],
]

Error Handling

All failures throw IPFly\IPFlyException, a RuntimeException subclass with getMessage(), getStatus(), getErrorCode(), and getCause().

use IPFly\IPFlyClient;
use IPFly\IPFlyException;

$client = new IPFlyClient('YOUR_TOKEN');

try {
    $client->lookup('8.8.8.8');
} catch (IPFlyException $err) {
    if ($err->getErrorCode() === 'TIMEOUT') {
        // retry later, log, fall back to a default
    } elseif ($err->getStatus() === 401) {
        // token is invalid — surface a config error, don't retry
    }
    error_log($err->getMessage());
}

Performance Notes

Examples

Two common integration patterns: enriching a CSV of visitor IPs in bulk, and proxying instead of embedding your token in a client-facing app.

<?php
require_once 'ipfly_sdk.php';

use IPFly\IPFlyClient;

$client = new IPFlyClient(getenv('IPFLY_TOKEN'), [
    'cache' => ['storage' => 'file', 'path' => __DIR__ . '/geo_cache.json'],
]);

$ips = [];
if (($handle = fopen('visitors.csv', 'r')) !== false) {
    $header = fgetcsv($handle);
    $ipCol = array_search('ip', $header, true);
    while (($row = fgetcsv($handle)) !== false) {
        $ips[] = $row[$ipCol];
    }
    fclose($handle);
}

foreach ($client->batchLookup($ips, 8) as $result) {
    if ($result->ok) {
        echo "{$result->ip} -> {$result->data['country_name']}\n";
    } else {
        echo "{$result->ip} -> error: {$result->error->getErrorCode()}\n";
    }
}

<?php
require_once __DIR__ . '/../../ipfly_sdk.php';

use IPFly\IPFlyClient;
use IPFly\IPFlyException;

$client = new IPFlyClient(getenv('IPFLY_TOKEN'));
$ip = $_GET['ip'] ?? $_SERVER['REMOTE_ADDR'];

header('Content-Type: application/json');

try {
    echo json_encode($client->lookup($ip, ['include' => 'security']));
} catch (IPFlyException $err) {
    http_response_code($err->getStatus() ?: 502);
    echo json_encode(['error' => $err->getErrorCode(), 'message' => $err->getMessage()]);
}

<?php

namespace App\Http\Controllers;

use IPFly\IPFlyClient;
use IPFly\IPFlyException;
use Illuminate\Http\Request;

class GeoController extends Controller
{
    public function __invoke(Request $request)
    {
        static $client = null;
        $client ??= new IPFlyClient(config('services.ipfly.token'), [
            'cache' => ['storage' => 'apcu'],
        ]);

        try {
            return response()->json(
                $client->lookup($request->query('ip') ?? $request->ip(), ['include' => 'security'])
            );
        } catch (IPFlyException $err) {
            return response()->json(
                ['error' => $err->getErrorCode(), 'message' => $err->getMessage()],
                $err->getStatus() ?: 502
            );
        }
    }
}

Requirements

PHP 7.4 or later (uses typed properties and arrow functions; no PHP 8-only syntax required). The curl extension is optional but recommended — without it, the SDK automatically falls back to PHP's built-in stream wrappers for single lookups and runs batchLookup() sequentially. The apcu extension is only needed for 'storage' => 'apcu' caching.

License

MIT — use it, fork it, ship it.