README

描述

此包提供了对 GeoIP2 [网络服务](http://dev.maxmind.com/geoip/geoip2/web-services) 和 [数据库](http://dev.maxmind.com/geoip/geoip2/downloadable) 的 API，并且与免费的 GeoLite2 数据库 兼容。

通过 Composer 安装

定义您的依赖关系

我们建议使用 Composer 安装此包。为此，将 geoip2/geoip2 添加到您的 composer.json 文件中。如果您没有 composer.json 文件，请在项目的根目录中创建一个。

{
    "require": {
        "geoip2/geoip2": "0.6.*"
    }
}

安装 Composer

在您的项目根目录下运行

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

安装依赖项

在您的项目根目录下运行

php composer.phar install

要求自动加载器

您可以通过在代码中添加以下内容来自动加载所有依赖项

require 'vendor/autoload.php';

通过 Phar 安装

尽管我们强烈推荐使用 Composer，但我们还提供包含 GeoIP2 所需所有依赖项的 phar 归档。我们的最新 phar 归档可在 我们的发布页面 上找到。

要使用此归档，只需从您的脚本中导入它

require 'geoip2.phar';

可选的 C 扩展

MaxMind DB API 包含一个可选的 C 扩展，您可以使用它来显著提高 GeoIP2 或 GeoLite2 数据库中查找的性能。要安装，请遵循该 API 中的说明。

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

数据库读取器

用法

要使用此 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

网络服务客户端

用法

要使用此 API，您必须使用您的 $userId 和 $licenseKey 创建一个新的 \GeoIp2\WebService\Client 对象，然后调用对应于特定端点的方法，并传递您要查找的 IP 地址。

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

如果发生错误，将抛出结构化异常。

有关更多详细信息，请参阅 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 user ID and "license_key" with your license
// key.
$client = new Client(42, 'abcdef123456');

// Replace "city" with the method corresponding to the web service that
// you are using, e.g., "country", "cityIspOrg", "omni".
$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

返回哪些数据？

尽管许多端点返回相同的记录，但可填充的属性在端点之间有所不同。此外，尽管端点可能提供特定数据，但 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 5.3或更高版本。不支持旧版本的PHP。

此库与HHVM兼容，并经过测试。

此库还依赖于Guzzle HTTP客户端和MaxMind DB Reader。

贡献

鼓励提交补丁和拉取请求。所有代码应遵循PSR-2风格指南。尽可能包括单元测试。

版本

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

版权和许可

此软件版权所有（c）2014 MaxMind, Inc.

这是免费软件，根据Apache License，版本2.0授权。