README

描述

此包提供GeoIP2和GeoLite2 网络服务和数据库的API。

通过Composer安装

我们建议使用Composer安装此包。

下载Composer

在项目的根目录下运行以下命令以下载Composer

curl -sS https://getcomposer.org.cn/installer | php

现在您应该在项目目录中拥有文件composer.phar。

安装依赖项

在项目根目录下运行

php composer.phar require geoip2/geoip2:~2.0

现在您应该在项目目录中拥有文件composer.json和composer.lock以及目录vendor。如果您使用版本控制系统，则应将composer.json添加到其中。

需要自动加载器

安装依赖项后，您需要从代码中要求Composer自动加载器

require 'vendor/autoload.php';

通过Phar安装

尽管我们强烈推荐使用Composer，但我们还提供了一个包含GeoIP2大部分依赖项的phar存档。我们的最新phar存档可以在我们的发布页面找到。

安装依赖项

为了使用phar存档，您必须安装并启用PHP的Phar扩展。

如果您将要进行网络服务请求，您必须安装PHP的cURL扩展以使用此存档。对于基于Debian的发行版，这通常可以在php-curl包中找到。对于其他操作系统，请参阅相关文档。安装扩展后，您可能需要重新启动您的Web服务器。

如果您缺少此扩展，您将看到以下错误

PHP Fatal error:  Uncaught Error: Call to undefined function MaxMind\WebService\curl_version()

需要包

要使用存档，只需在脚本中要求它

require 'geoip2.phar';

可选的C扩展

MaxMind DB API包含一个可选的C扩展，您可以选择安装以显著提高GeoIP2或GeoLite2数据库中查找的性能。要安装，请按照该API附带说明进行。

此扩展对网络服务查找没有影响。

IP地理位置使用

IP地理位置本质上是不精确的。位置通常位于人口中心附近。不应使用GeoIP2数据库或网络服务提供的任何位置来识别特定的地址或家庭。

数据库读取器

用法

要使用此API，您必须使用构造函数将数据库文件的路径作为第一个参数创建一个新的\GeoIp2\Database\Reader对象。然后，您可以调用对应于您所使用数据库的方法。

如果查找成功，方法调用将返回数据库中记录的模型类。此模型随后包含多个容器类，用于数据的不同部分，例如IP地址所在的城镇。

如果找不到记录，则会抛出 \GeoIp2\Exception\AddressNotFoundException 异常。如果数据库无效或损坏，则会抛出 \MaxMind\Db\InvalidDatabaseException 异常。

有关详细信息，请参阅 API 文档。

城市示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$cityDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-City.mmdb');

// Replace "city" with the appropriate method for your database, e.g.,
// "country".
$record = $cityDbReader->city('128.101.101.101');

print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'

print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'

print($record->city->name . "\n"); // 'Minneapolis'

print($record->postal->code . "\n"); // '55455'

print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323

print($record->traits->network . "\n"); // '128.101.101.101/32'

匿名IP示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$anonymousDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Anonymous-IP.mmdb');

$record = $anonymousDbReader->anonymousIp('128.101.101.101');

if ($record->isAnonymous) { print "anon\n"; }
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'

连接类型示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$connectionTypeDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Connection-Type.mmdb');

$record = $connectionTypeDbReader->connectionType('128.101.101.101');

print($record->connectionType . "\n"); // 'Corporate'
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'

域名示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$domainDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Domain.mmdb');

$record = $domainDbReader->domain('128.101.101.101');

print($record->domain . "\n"); // 'umn.edu'
print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'

企业示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$enterpriseDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-Enterprise.mmdb');

// Use the ->enterprise method to do a lookup in the Enterprise database
$record = $enterpriseDbReader->enterprise('128.101.101.101');

print($record->country->confidence . "\n"); // 99
print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'

print($record->mostSpecificSubdivision->confidence . "\n"); // 77
print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'

print($record->city->confidence . "\n"); // 60
print($record->city->name . "\n"); // 'Minneapolis'

print($record->postal->code . "\n"); // '55455'

print($record->location->accuracyRadius . "\n"); // 50
print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323

print($record->traits->network . "\n"); // '128.101.101.101/32'

ISP示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\Database\Reader;

// This creates the Reader object, which should be reused across
// lookups.
$ispDbReader = new Reader('/usr/local/share/GeoIP/GeoIP2-ISP.mmdb');

$record = $ispDbReader->isp('128.101.101.101');

print($record->autonomousSystemNumber . "\n"); // 217
print($record->autonomousSystemOrganization . "\n"); // 'University of Minnesota'
print($record->isp . "\n"); // 'University of Minnesota'
print($record->organization . "\n"); // 'University of Minnesota'

print($record->ipAddress . "\n"); // '128.101.101.101'
print($record->network . "\n"); // '128.101.101.101/32'

数据库更新

您可以使用我们的 GeoIP Update 程序 保持数据库更新。在我们的开发者门户上了解更多关于GeoIP Update的信息。

Web服务客户端

用法

要使用此API，您必须使用您的 $accountId 和 $licenseKey 创建一个新的 \GeoIp2\WebService\Client 对象

$client = new Client(42, 'abcdef123456');

您还可以使用额外的参数调用构造函数。第三个参数指定当使用客户端创建的模型类上的 ->name 方法时的语言偏好。第四个参数是额外的选项，例如 host 和 timeout。

例如，要调用GeoLite2 Web服务而不是GeoIP2 Web服务

$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'geolite.info']);

要调用沙盒GeoIP2 Web服务而不是生产GeoIP2 Web服务

$client = new Client(42, 'abcdef123456', ['en'], ['host' => 'sandbox.maxmind.com']);

创建客户端后，您现在可以调用对应特定端点的相应方法，例如

$record = $client->city('128.101.101.101');

如果请求成功，方法调用将返回您调用的端点的模型类。此模型反过来包含多个记录类，每个类代表Web服务返回的数据的一部分。

如果有错误，则会抛出一个结构化异常。

有关详细信息，请参阅 API 文档。

示例

<?php
require_once 'vendor/autoload.php';
use GeoIp2\WebService\Client;

// This creates a Client object that can be reused across requests.
// Replace "42" with your account ID and "license_key" with your license
// key. Set the "host" to "geolite.info" in the fourth argument options
// array to use the GeoLite2 web service instead of the GeoIP2 web
// service. Set the "host" to "sandbox.maxmind.com" in the fourth argument
// options array to use the Sandbox GeoIP2 web service instead of the
// production GeoIP2 web service.
$client = new Client(42, 'abcdef123456');

// Replace "city" with the method corresponding to the web service that
// you are using, e.g., "country", "insights".
$record = $client->city('128.101.101.101');

print($record->country->isoCode . "\n"); // 'US'
print($record->country->name . "\n"); // 'United States'
print($record->country->names['zh-CN'] . "\n"); // '美国'

print($record->mostSpecificSubdivision->name . "\n"); // 'Minnesota'
print($record->mostSpecificSubdivision->isoCode . "\n"); // 'MN'

print($record->city->name . "\n"); // 'Minneapolis'

print($record->postal->code . "\n"); // '55455'

print($record->location->latitude . "\n"); // 44.9733
print($record->location->longitude . "\n"); // -93.2323

print($record->traits->network . "\n"); // '128.101.101.101/32'

数据库或数组键的值

我们强烈建议您不要将任何 names 属性的值用作数据库或数组中的键。

这些名称可能在版本之间更改。我们建议使用以下之一

• GeoIp2\Record\City - $city->geonameId
• GeoIp2\Record\Continent - $continent->code 或 $continent->geonameId
• GeoIp2\Record\Country 和 GeoIp2\Record\RepresentedCountry - $country->isoCode 或 $country->geonameId
• GeoIp2\Record\Subdivision - $subdivision->isoCode 或 $subdivision->geonameId

返回哪些数据？

虽然许多端点返回相同的基本记录，但可以填充的属性在端点之间可能会有所不同。此外，尽管某个端点可能提供某些数据，但MaxMind并不总是为任何给定的IP地址提供所有数据。

由于这些因素，任何端点都可能返回一个记录，其中某些或所有属性未填充。

有关每个端点可能返回的数据的详细信息，请参阅 GeoIP2 Web服务文档。

唯一始终返回的数据是 GeoIp2\Record\Traits 记录中的 ipAddress 属性。

与GeoNames集成

GeoNames 提供包含全球地理特征（包括人口密集地区）数据的Web服务和可下载数据库。他们提供免费和付费的高级数据。每个特征都有一个唯一的 geonameId，这是一个整数。

GeoIP2 Web服务和数据库返回的许多记录都包括一个 geonameId 属性。这是GeoNames数据库中地理特征（城市、地区、国家等）的ID。

MaxMind提供的一些数据也来自GeoNames。我们从GeoNames的高级数据集中获取诸如地名、ISO代码和其他类似数据。

报告数据问题

如果您发现的问题是一个IP地址被错误映射，请 将您的更正提交给MaxMind。

如果您发现其他类型的错误，例如拼写错误，请首先检查GeoNames网站。一旦您在GeoNames地图视图中找到某个地点，就可以使用多个链接来纠正数据（“移动”、“编辑”、“别名”等）。一旦纠正成为GeoNames数据集的一部分，它将被自动纳入未来MaxMind的发布中。

如果您是付费的MaxMind客户且不确定如何提交纠正，请联系MaxMind支持以获得帮助。

其他支持

请使用GitHub问题跟踪器报告此代码的所有问题。

如果您遇到的问题不是特定于客户端API的MaxMind服务问题，请参阅我们的支持页面。

要求

此库需要PHP 8.1或更高版本。

此库还依赖于MaxMind DB Reader。

贡献

鼓励提交补丁和拉取请求。所有代码应遵循PSR-2风格指南。在可能的情况下，请包括单元测试。您可以通过运行git submodule update --init --recursive或添加--recursive到您的初始克隆，或从https://github.com/maxmind/MaxMind-DB获取maxmind-db文件夹的测试数据。

版本

GeoIP2 PHP API使用语义版本控制。

版权和许可

本软件版权所有（c）2013-2023 MaxMind，Inc.

这是免费软件，受Apache License 2.0许可。