nekulin/geocoder

几乎缺失的Geocoder PHP 5.4库。

维护者

详细信息

github.com/nekulin/Geocoder

主页

源代码

安装: 22

依赖项: 0

建议者: 0

安全: 0

星标: 0

关注者: 2

分支: 516

v3.3.0 2015-12-06 20:17 UTC

Requires

Requires (Dev)

Suggests

  • ext-geoip: Enabling the geoip extension allows you to use the MaxMindProvider.
  • geoip/geoip: If you are going to use the MaxMindBinaryProvider (conflict with geoip extension).
  • geoip2/geoip2: If you are going to use the GeoIP2DatabaseProvider.
  • symfony/stopwatch: If you want to use the TimedGeocoder

MIT ccc178e2984c0af24881faa0ffe515f20e5e8c23

  • William DURAND <william.durand1.woop@gmail.com>

geocodingabstractiongeocodergeoip

This package is not auto-updated.

Last update: 2024-09-20 18:12:17 UTC

README

Build Status Total Downloads Latest Stable Version PHP7 ready

重要：您正在浏览Geocoder 3.x 的文档。版本 2.x 的文档在此处可用：Geocoder 2.x 文档。

Geocoder 是一个PHP库，通过提供地理编码操作的强大抽象层，帮助您构建地理感知应用程序。

安装

安装Geocoder的推荐方式是通过 Composer

$ composer require willdurand/geocoder

用法

Geocoder 和其伴侣 Geocoder Extra 提供了许多 提供者。

首先选择适合您需求的提供者。假设您正在寻找的是 GoogleMaps，让我们看看如何使用它。在下面的代码片段中，已经选择了 curl 作为 HTTP层，但这是由您决定的，因为每个基于HTTP的提供者都实现了 PSR-7。

$curl     = new \Ivory\HttpAdapter\CurlHttpAdapter();
$geocoder = new \Geocoder\Provider\GoogleMaps($curl);

$geocoder->geocode(...);
$geocoder->reverse(...);

所有提供者都实现的 Geocoder 接口公开了两个主要方法

  • geocode($streetOrIpAddress)
  • reverse($latitude, $longitude)

它还包含控制结果数量的方法

  • limit($limit)
  • getLimit()

地址 & 地址集合

Both geocode() 和 reverse() 方法返回一个 Address 对象集合 (AddressCollection)，每个对象提供以下API

  • getCoordinates() 将返回一个包含 latitude 和 longitude 属性的 Coordinates 对象；
  • getLatitude() 将返回 latitude 值；
  • getLongitude() 将返回 longitude 值；
  • getBounds() 将返回一个包含 south、west、north 和 east 属性的 Bounds 对象；
  • getStreetNumber() 将返回 street number/house number 值；
  • getStreetName() 将返回 street name 值；
  • getLocality() 将返回 locality 或 city；
  • getPostalCode() 将返回 postalCode 或 zipcode；
  • getSubLocality() 将返回 city district 或 sublocality；
  • getAdminLevels() 将返回一个有序的 AdminLevel 对象集合 (AdminLevelCollection)，每个对象包含 level、name 和 code 属性；
  • getCountry() 将返回一个包含 name 和 code 属性的 Country 对象；
  • getCountryCode() 将返回ISO country代码；
  • getTimezone() 将返回 timezone。

AddressCollection 公开了以下方法

  • count() (此类实现了 Countable)；
  • first() 获取第一个 Address;
  • slice($offset, $length = null) 返回从 $offset 到 length 之间的 Address 对象；
  • get($index) 使用 $index 获取一个 Address；
  • all() 返回所有 Address 对象；
  • getIterator()（此类实现 IteratorAggregate）。

提供者聚合器

使用 ProviderAggregator 可以注册多个提供者，以便您以后可以决定使用哪个提供者。

<?php

$geocoder = new \Geocoder\ProviderAggregator();

$geocoder->registerProviders([
    new \Geocoder\Provider\GoogleMaps(
        $adapter, $locale, $region, $useSsl
    ),
    new \Geocoder\Provider\GoogleMapsBusiness(
        $adapter, '<CLIENT_ID>', '<PRIVATE_KEY>', $locale, $region, $useSsl
    ),
    new \Geocoder\Provider\Yandex(
        $adapter, $locale, $toponym
    ),
    new \Geocoder\Provider\MaxMind(
        $adapter, '<MAXMIND_API_KEY>', $service, $useSsl
    ),
    new \Geocoder\Provider\ArcGISOnline(
        $adapter, $sourceCountry, $useSsl
    ),
]);

$geocoder->registerProvider(
    new \Geocoder\Provider\Nominatim(
        $adapter, 'http://your.nominatim.server', $locale
    )
);

$geocoder
    ->using('google_maps')
    ->geocode('...');

$geocoder
    ->limit(10)
    ->reverse($lat, $lng);

ProviderAggregator 的 API 是流畅的，这意味着您可以编写

<?php

$addresses = $geocoder
    ->registerProvider(new \My\Provider\Custom($adapter))
    ->using('custom')
    ->limit(10)
    ->geocode('68.145.37.34')
    ;

using() 方法允许您通过名称选择要使用的 provider。当您处理多个提供者时，您可能想要选择其中一个。默认行为是使用第一个，但这可能很麻烦。

limit() 方法允许您配置返回的最大结果数。根据您使用的提供者，您可能不会得到预期的那么多结果，这是一个最大限制，而不是预期结果数。

定时地理编码器

TimedGeocoder 类为每个 geocode 和 reverse 调用进行性能分析。因此，您可以轻松地了解每个 geocoder/reverse 调用花费了多少时间/内存。

// configure you geocoder object

$stopwatch = new \Symfony\Component\Stopwatch\Stopwatch();
$geocoder = new \Geocoder\TimedGeocoder($geocoder, $stopwatch);

$geocoder->geocode('Paris, France');

// Now you can debug your application

我们使用 symfony/stopwatch 组件，这意味着，如果您使用 Symfony 框架，geocoder 调用将出现在您的 Web Profiler 的时间轴部分。

HTTP适配器

为了与地理编码 API 进行通信，您需要 HTTP 适配器。虽然这在 Geocoder 1.x 和 2.x 的库中是作为一部分的，但 Geocoder 3.x 及更高版本现在依赖于 PSR-7 标准，该标准定义了 HTTP 消息应该如何实现。选择任何遵循此 PSR 的库，并实现指定的接口以与 Geocoder 一起使用。

由于做出选择相当困难，Geocoder 默认附带 egeloen/http-adapter 库，但选择不同的实现取决于您。

注意：并非所有提供者都是基于 HTTP 的。

提供者

提供者为您执行地理编码的魔法（与 API 通信、获取结果、处理错误等），并且可以高度配置。

基于地址的提供者

以下将提供有关这些提供者的更多信息。

ArcGISOnline

您可以使用 sourceCountry 来指定一个国家，以将结果限制为该特定国家，从而减少请求时间（请注意，这在反向地理编码中不起作用）。

GeoIP2

需要 数据库文件 或 webservice，由 GeoIP2 表示，注入到 GeoIP2Adapter 中。必须安装 geoip2/geoip2 包。

此提供者只能与相应的 GeoIP2Adapter 一起使用。

<?php

// Maxmind GeoIP2 Provider: e.g. the database reader
$reader   = new \GeoIp2\Database\Reader('/path/to/database');

$adapter  = new \Geocoder\Adapter\GeoIP2Adapter($reader);
$geocoder = new \Geocoder\Provider\GeoIP2($adapter);

$address   = $geocoder->geocode('74.200.247.59')->first();
GoogleMaps

可以指定区域和/或区域。

$geocoder = new \Geocoder\Provider\GoogleMaps(
    $httpAdapter,
    $locale,
    $region,
    $useSsl, // true|false
    $apiKey
);
GoogleMapsBusiness

需要有效的 Client ID。私钥是可选的。此提供者还支持 SSL，并扩展了 GoogleMaps 提供者。

MaxMindBinary

此提供者需要一个数据文件，并且必须安装 geoip/geoip 包。

值得指出的是，此提供者存在 严重的性能问题，不应在生产中使用。有关更多信息，请阅读 问题 #301。

Nominatim

需要访问 Nominatim 服务器。有关更多信息，请参阅 Nominatim 维基页面。

TomTom

默认语言-区域设置为 en，您可以选择 de、es、fr、it、nl、pl、pt 和 sv 之间的任意一个。

Yandex

默认语言地区设置为ru-RU，您可以选择以下选项：uk-UA、be-BY、en-US、en-BR和tr-TR。此提供商还可以根据坐标（纬度、经度）反向查找信息。可以通过指定地名（如house、street、metro、district和locality）来精确地名，以获取更精确的反向地理编码结果。

基于IP的提供者

重要： Geocoder Extra 库包含更多官方提供商！

区域感知提供者

支持地区设置的提供商公开以下方法

$geocoder->setLocale('xyz');

$locale = $geocoder->getLocale();

链提供者

Chain 提供商是一个特殊的提供商，它接受提供商列表并遍历此列表以获取信息。请注意，当某个提供商返回结果时，它会停止迭代。结果由 GoogleMaps 返回，因为 FreeGeoIp 和 HostIp 无法对街道地址进行地理编码。BingMaps 被忽略。

$geocoder = new \Geocoder\ProviderAggregator();
$adapter  = new \Ivory\HttpAdapter\CurlHttpAdapter();

$chain = new \Geocoder\Provider\Chain([
    new \Geocoder\Provider\FreeGeoIp($adapter),
    new \Geocoder\Provider\HostIp($adapter),
    new \Geocoder\Provider\GoogleMaps($adapter, 'fr_FR', 'France', true),
    new \Geocoder\Provider\BingMaps($adapter, '<API_KEY>'),
    // ...
]);

$geocoder->registerProvider($chain);

try {
    $geocode = $geocoder->geocode('10 rue Gambetta, Paris, France');
    var_export($geocode);
} catch (Exception $e) {
    echo $e->getMessage();
}

一切正常，尽情享受吧！

转储器

Geocoder 提供了旨在将 Address 对象转换为标准格式的导出器。

GPS eXchange Format (GPX)

GPS eXchange 格式旨在共享地理定位数据，如兴趣点、轨迹、路线，以及坐标。Geocoder 提供了一个导出器，可以将 Address 对象转换为符合 GPX 格式。

假设我们得到了前面提到的 $address 对象

<?php

$dumper = new \Geocoder\Dumper\Gpx();
$strGpx = $dumper->dump($address);

echo $strGpx;

它将显示

<gpx
    version="1.0"
    creator="Geocoder" version="1.0.1-dev"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://www.topografix.com/GPX/1/0"
    xsi:schemaLocation="http://www.topografix.com/GPX/1/0 http://www.topografix.com/GPX/1/0/gpx.xsd">
    <bounds minlat="2.388911" minlon="48.863151" maxlat="2.388911" maxlon="48.863151"/>
    <wpt lat="48.8631507" lon="2.3889114">
        <name><![CDATA[Paris]]></name>
        <type><![CDATA[Address]]></type>
    </wpt>
</gpx>

GeoJSON

GeoJSON 是一种用于编码各种地理数据结构的格式。

Keyhole Markup Language (KML)

Keyhole Markup Language 是一种 XML 表示法，用于在基于互联网的二维地图和三维地球浏览器中表达地理注释和可视化。

Well-Known Binary (WKB)

几何值的已知二进制（WKB）表示法由 OpenGIS 规范定义。

Well-Known Text (WKT)

已知文本（WKT）是一种文本标记语言，用于在地图上表示矢量几何对象、空间对象的参考系统和空间参考系统之间的转换。

格式化器

一个常见的用例是打印地理编码数据。得益于 StringFormatter 类，将 Address 对象格式化为字符串非常简单

<?php

// $address is an instance of Address
$formatter = new \Geocoder\Formatter\StringFormatter();

$formatter->format($address, '%S %n, %z %L');
// 'Badenerstrasse 120, 8001 Zuerich'

$formatter->format($address, '<p>%S %n, %z %L</p>');
// '<p>Badenerstrasse 120, 8001 Zuerich</p>'

以下是映射

  • 街道号码：%n

  • 街道名称：%S

  • 城市：%L

  • 城市区域：%D

  • 邮政编码：%z

  • 行政级别名称：%A1、%A2、%A3、%A4、%A5

  • 行政级别代码：%a1、%a2、%a3、%a4、%a5

  • 国家：%C

  • 国家代码：%c

  • 时区：%T

扩展内容

您可以通过实现 Provider 接口来编写自己的 provider。

您可以通过实现 Dumper 接口来提供自己的 dumper。

版本控制

Geocoder 遵循 语义版本控制。

生命周期结束

1.x

截至 2014 年 12 月，分支 1.7 已不再官方支持，这意味着主要版本 1 已达到生命周期结束。最后一个版本是：1.7.1。

2.x

截至 2014 年 12 月，版本 2.x 处于 功能冻结 状态。所有新功能都应贡献给 3.0 及以上版本。最后一个版本是：2.8.1。

主要版本 2 将于 2015 年 12 月达到 生命周期结束。

稳定版本

版本 3.x 是 Geocoder 的当前主要稳定版本。

贡献

请参阅 CONTRIBUTING 文件。

单元测试

为了运行测试套件，请安装开发依赖项

$ composer install --dev

然后，运行以下命令

$ phpunit

由于需要API密钥，您将获得一些跳过的单元测试。

将phpunit.xml.dist文件重命名为phpunit.xml，然后取消以下行的注释并添加您自己的API密钥

<php>
    <!-- <server name="IPINFODB_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="BINGMAPS_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="GEOIPS_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="MAXMIND_API_KEY" value="YOUR_API_KEY" /> -->
    <!-- <server name="GEONAMES_USERNAME" value="YOUR_USERNAME" /> -->
    <!-- <server name="TOMTOM_MAP_KEY" value="YOUR_MAP_KEY" /> -->
    <!-- <server name="GOOGLE_GEOCODING_KEY" value="YOUR_GEOCODING_KEY" /> -->
    <!-- <server name="OPENCAGE_API_KEY" value="YOUR_API_KEY" /> -->
</php>

您已完成。

致谢

贡献者行为准则

作为本项目的贡献者和维护者，我们承诺尊重通过报告问题、发布特性请求、更新文档、提交拉取请求或补丁等方式参与贡献的所有人。

我们致力于为所有参与者创造一个无骚扰的参与体验，无论经验水平、性别、性别认同和表达、性取向、残疾、个人外观、体型、种族、年龄或宗教。

参与者不可接受的行为示例包括使用性语言或图像、侮辱性评论或个人攻击、捣乱、公开或私人骚扰、侮辱或其他不专业行为。

项目负责人有权也有责任移除、编辑或拒绝不符合此行为准则的评论、提交、代码、维基编辑、问题和其他贡献。不遵守行为准则的项目负责人可能会被从项目团队中移除。

可以通过提交问题或联系项目负责人之一来报告滥用、骚扰或不可接受的行为。

此行为准则改编自贡献者誓言，版本1.0.0，可在http://contributor-covenant.org/version/1/0/0/找到

许可

Geocoder在MIT许可证下发布。有关详细信息，请参阅捆绑的LICENSE文件。