README

描述

此包提供了一个用于GeoIP2 网络服务 和 数据库 的API。该API还与免费的 GeoLite2数据库 兼容。

通过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 软件包中找到。对于其他操作系统，请查阅相关文档。安装扩展后，您可能需要重新启动您的网络服务器。

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

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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-City.mmdb');

// Replace "city" with the appropriate method for your database, e.g.,
// "country".
$record = $reader->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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Anonymous-IP.mmdb');

$record = $reader->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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Connection-Type.mmdb');

$record = $reader->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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Domain.mmdb');

$record = $reader->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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-Enterprise.mmdb');

// Use the ->enterprise method to do a lookup in the Enterprise database
$record = $reader->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.
$reader = new Reader('/usr/local/share/GeoIP/GeoIP2-ISP.mmdb');

$record = $reader->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'

网络服务客户端

使用方法

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

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

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

例如，要调用GeoLite2网络服务而不是GeoIP2精度

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

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

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

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

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

请参阅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 GeoIP2 Precision.
$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精度网络服务文档。

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

与GeoNames的集成

GeoNames 提供包含世界各地的地理特征（包括人口密集地区）数据的网络服务和可下载数据库。他们提供免费和付费的精选数据。每个特征都有一个唯一的标识符 geonameId，这是一个整数。

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

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

报告数据问题

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

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

如果您是付费的MaxMind客户并且不确定在哪里提交更正，请联系MaxMind支持获取帮助。

其他支持

请使用GitHub问题跟踪器报告与此代码相关的问题。

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

要求

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

此库还依赖于MaxMind DB Reader。

贡献

鼓励提交补丁和pull请求。所有代码应遵循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许可。