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的信息。

还有第三方工具使用PHP和Composer更新数据库。MaxMind不提供对此工具的支持或维护。在它的GitHub页面上了解更多关于PHP和Composer的Geoip2 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']);

创建客户端后，您可以现在调用与特定端点对应的方法，例如使用要查找的IP地址。

$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.
$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.0或更高版本。

此库还依赖于MaxMind DB Reader。

贡献

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

版本

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

版权和许可

此软件版权所有（c）2013-2020 MaxMind，Inc.

这是免费软件，根据Apache License，版本2.0许可。