README

Maintained PHP 8 reader for the SypexGeo binary IP-to-geo database. Pure PHP, zero runtime dependencies, exposing a modern PSR-4 namespaced class.

Maintained by GLOBUS.studio and Yevhen Leonidov.

Features

• Pure PHP reader for SypexGeo Country, City and City Max databases.
• Compatible with PHP 8.1 through 8.5.
• File, in-memory and batch lookup modes (combinable as bit flags).
• Country, City and full City+Region+Country lookups.
• PHPUnit test suite.

Requirements

• PHP 8.1 or newer.
• A SypexGeo binary database file — download from sypexgeo.net.

Installation

Composer

composer require globus-studio/sypexgeo

Manual

Copy src/SxGeo.php into your project and load it however you prefer (PSR-4 autoloader or a plain require).

Usage

use GlobusStudio\SypexGeo\SxGeo;

// Relative paths are resolved against the src/ directory — use an absolute path:
$sxgeo = new SxGeo('/absolute/path/to/SxGeoCity.dat', SxGeo::MODE_MEMORY);

$sxgeo->getCountry('8.8.8.8');     // "US"
$sxgeo->getCountryId('8.8.8.8');   // internal numeric id
$sxgeo->getCity('8.8.8.8');        // ['city' => ..., 'country' => ...]
$sxgeo->getCityFull('8.8.8.8');    // ['city' => ..., 'region' => ..., 'country' => ...]
$sxgeo->get('8.8.8.8');            // city array (City DB) or country string (Country DB)
$sxgeo->about();                   // database metadata

Lookup modes

Modes are bit flags and may be combined.

$sxgeo = new SxGeo('/path/to/SxGeoCity.dat', SxGeo::MODE_MEMORY | SxGeo::MODE_BATCH);

API summary

Notes:

• IPv4 only.
• Private and reserved ranges (10/8, 127/8, 0/8) intentionally return false / empty.
• The constructor throws \RuntimeException if the database is missing or has an unexpected format.

Example

See examples/lookup.php for the full script.

# Download a database from https://sypexgeo.net/en/download/
# and place it in tests/fixtures/, then:
php examples/lookup.php

SxGeo City EN  ·  utf-8  ·  5 995 121 blocks  ·  2025.12.19

8.8.8.8
  Country  US  (id: 225)
  City     Mountain View  37.3861, -122.0839
  Region   California  US-CA
  Country  United States  39.76, -98.5

Testing

composer install
composer test

The unit suite runs without any database. Integration tests are skipped automatically unless a real database is available. To run them, place a .dat file in tests/fixtures/ (see tests/fixtures/README.md).

Continuous integration

GitHub Actions runs the suite against PHP 8.1–8.5 on every push and pull request. Set the SXGEO_URL repository secret to a downloadable database URL to enable the integration suite in CI.

License

MIT, see LICENSE.

Credits

Based on the original SypexGeo library by zapimir and BINOVATOR. This fork is maintained by GLOBUS.studio and Yevhen Leonidov.