PHPackages                             globus-studio/sypexgeo - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. globus-studio/sypexgeo

ActiveLibrary[Utility & Helpers](/categories/utility)

globus-studio/sypexgeo
======================

Maintained PHP 8 reader for the SypexGeo binary IP-to-geo database (Country, City, City Max).

v1.0.0(1mo ago)19471MITPHPPHP ^8.1CI passing

Since Apr 26Pushed 1mo ago13 watchersCompare

[ Source](https://github.com/GLOBUS-studio/SypexGeo)[ Packagist](https://packagist.org/packages/globus-studio/sypexgeo)[ Docs](https://github.com/globus-studio/SypexGeo)[ RSS](/packages/globus-studio-sypexgeo/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

SypexGeo
========

[](#sypexgeo)

[![CI](https://github.com/globus-studio/SypexGeo/actions/workflows/ci.yml/badge.svg)](https://github.com/globus-studio/SypexGeo/actions/workflows/ci.yml)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![PHP](https://camo.githubusercontent.com/cfe7d269be25fc7f4bb5ad7d9dcc0d09cc9273b4fbaff1a2076c4ec5dbd40d07/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253545382e312d3737376262342e737667)](composer.json)

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](https://globus.studio) and Yevhen Leonidov.

Features
--------

[](#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 with 100% line and method coverage of the reader.

Requirements
------------

[](#requirements)

- PHP 8.1 or newer.
- A SypexGeo binary database file (`SxGeo.dat`).

Installation
------------

[](#installation)

### Composer

[](#composer)

```
composer require globus-studio/sypexgeo
```

### Manual

[](#manual)

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

Usage
-----

[](#usage)

```
use GlobusStudio\SypexGeo\SxGeo;

$sxgeo = new SxGeo(__DIR__ . '/SxGeo.dat', SxGeo::MODE_FILE);

$iso     = $sxgeo->getCountry('8.8.8.8');     // "US"
$id      = $sxgeo->getCountryId('8.8.8.8');   // internal numeric id
$city    = $sxgeo->getCity('8.8.8.8');        // ['city' => ..., 'country' => ...]
$full    = $sxgeo->getCityFull('8.8.8.8');    // ['city' => ..., 'region' => ..., 'country' => ...]
$about   = $sxgeo->about();                   // database metadata
```

### Lookup modes

[](#lookup-modes)

Modes are bit flags and may be combined.

ConstantBehaviour`SxGeo::MODE_FILE`Read from disk on every lookup. Lowest memory.`SxGeo::MODE_MEMORY`Load the whole database into RAM. Fastest reads.`SxGeo::MODE_BATCH`Pre-decode indices for many sequential lookups.`MODE_MEMORY | MODE_BATCH`Best throughput for bulk processing.```
$sxgeo = new SxGeo('SxGeo.dat', SxGeo::MODE_MEMORY | SxGeo::MODE_BATCH);
```

API summary
-----------

[](#api-summary)

MethodReturns`get(string $ip)`City structure for City DB, country code for Country DB.`getCountry(string $ip)`ISO 3166-1 alpha-2 country code, empty string for invalid IPs.`getCountryId(string $ip)`Internal numeric country id, `0` for invalid IPs.`getCity(string $ip)``['city' => ..., 'country' => ...]` or `false`.`getCityFull(string $ip)``['city' => ..., 'region' => ..., 'country' => ...]` or `false`.`about()`Database metadata (type, charset, sizes, timestamps).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.

Testing
-------

[](#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:

1. Place a SypexGeo `.dat` file at `tests/fixtures/SxGeo.dat`, or
2. Set `SXGEO_DB=/absolute/path/to/SxGeo.dat`, or
3. Use the helper:

    ```
    composer fetch-db -- https://example.com/SxGeoCity_utf8.zip
    ```

    The script accepts a direct `.dat` URL or a `.zip` archive containing one.

Continuous integration
----------------------

[](#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
-------

[](#license)

MIT, see [LICENSE](LICENSE).

Credits
-------

[](#credits)

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

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity21

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

45d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/285d32ac89643c66426e75f97a13c5eee2d8e8b809efd2d6fdde4665837b7b63?d=identicon)[Yevhen Leonidov](/maintainers/Yevhen%20Leonidov)

---

Top Contributors

[![MADEVAL](https://avatars.githubusercontent.com/u/10908537?v=4)](https://github.com/MADEVAL "MADEVAL (3 commits)")

---

Tags

ip2countryip2locationphp85sypex-geosypexgeogeoipgeolocationIPsypexgeoip to countryip to city

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/globus-studio-sypexgeo/health.svg)

```
[![Health](https://phpackages.com/badges/globus-studio-sypexgeo/health.svg)](https://phpackages.com/packages/globus-studio-sypexgeo)
```

###  Alternatives

[torann/geoip

Support for multiple Geographical Location services.

2.2k14.9M92](/packages/torann-geoip)[stevebauman/location

Retrieve a user's location by their IP Address

1.3k8.2M84](/packages/stevebauman-location)[zoujingli/ip2region

ip2region v3.0 for PHP - 企业级 IP 地理位置查询库，支持 IPv4 和 IPv6，多种缓存策略，零依赖，开箱即用

1.4k462.5k65](/packages/zoujingli-ip2region)[ipip/db

IPIP.net officially supported IP database ipdb format parsing library

139207.1k6](/packages/ipip-db)[ipip/datx

IPIP.net官方支持的IP数据库datx格式解析库

3831.3k1](/packages/ipip-datx)[adrianorosa/laravel-geolocation

Laravel Geo Location package to get details for a given IP Address

6598.6k1](/packages/adrianorosa-laravel-geolocation)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)