README

一个用于使用 what3words REST API 的 PHP 库。

概述

what3words PHP 包装器为您提供了以下编程访问权限

• 将 3 个单词地址转换为坐标
• 将坐标转换为 3 个单词地址
• 自动建议功能，它接受略微不正确的 3 个单词地址，并建议一系列有效的 3 个单词地址
• 获取 3m x 3m what3words 网格的某个区域
• 确定当前支持的 3 个单词地址语言。

身份验证

要使用此库，您需要获取一个 API 密钥，请访问 https://what3words.com/select-plan 并注册一个账户。

安装

Composer

要将此库用于您的项目，请在您的 composer.json 中放置以下行

"what3words/w3w-php-wrapper": "3.*"

手动

要手动包含此文件，请将 Geocoder.php 放入您的项目中，并使用 require_once("Geocoder.php")

初始化

use What3words\Geocoder\Geocoder;
use What3words\Geocoder\AutoSuggestOption;

$api = new Geocoder("<Secret API Key>");

转换为坐标

将 3 个单词地址转换为表示纬度和经度的位置。

此函数将 words 参数作为包含 3 个单词的字符串 'table.book.chair'

convertToCoordinates 方法的返回负载在 what3words REST API 文档 中描述。

代码示例

$result = $api->convertToCoordinates("index.home.raft");
print_r($result);

转换为 3 个单词地址

将表示为纬度和经度的坐标转换为 3 个单词地址。

convertTo3wa 方法的返回负载在 what3words REST API 文档 中描述。

代码示例

$result = $api->convertTo3wa(51.432393,-0.348023);
print_r($result);

可用语言

此函数返回当前支持的语言。它将返回两字母代码（ISO 639）以及该语言和英语中的名称。

convertTo3wa 方法的返回负载在 what3words REST API 文档 中描述。

代码示例

$result = $api->availableLanguages();
print_r($result);

网格部分

返回给定区域的 3m x 3m what3words 网格的某个部分。请求的框必须不大于从角落到角落 4km，否则将返回 BadBoundingBoxTooBig 错误。纬度必须 >= -90 且 <= 90，但经度可以绕过 180。要指定穿过子午线的边界框，请使用大于 180 的经度。示例值：50.0, 179.995, 50.01, 180.0005。

gridSection 函数的返回负载在 what3words REST API 文档 中描述。

代码示例

$result = $api->gridSection(39.903795, 116.384550, 39.902718, 116.383122);
print_r($result);

自动建议

根据用户输入和其他参数返回一系列 3 个单词地址。

此方法提供以下类型输入错误的纠正

• 打字错误
• 拼写错误
• 忘记的单词（例如，单数与复数）
• 单词顺序错误

autoSuggest 方法根据上述输入错误的概率确定对提供的3词地址字符串的可能更正，并返回一个按建议排序的列表。此方法还可以考虑可能更正与给定位置的地理邻近性，以进一步提高返回的建议。

输入3词地址

只有当您提交的部分3词地址字符串包含前两个单词以及第三个单词的第一个字符时，您才会收到结果；否则，将返回错误消息。

剪辑和焦点

我们提供各种clip策略，允许您指定用于排除可能对您的用户不相关的结果的地理区域。我们建议您使用剪辑为用户提供更精确、更短的结果集。如果您知道用户当前的位置，我们还强烈建议您使用focus来返回可能更相关的结果。

总之，剪辑策略用于可选地限制候选自动建议结果的列表，在此之后，如果提供了焦点，这将用于按相关性的顺序对结果进行排序。

autosuggest方法返回的有效负载在what3words REST API文档中描述。

用法

第一个参数是部分三个单词或语音数据。其后跟一个AutoSuggestOption对象的数组。最后一个参数是完成块。数组中的AutoSuggestOption对象是通过以下形式的静态便利函数创建的：

AutoSuggestOption::fallbackLanguage("de");
AutoSuggestOption::focus($latitude, $longitude);

代码示例 #1

$result = $api->autosuggest("fun.with.code");
print_r($result);

代码示例 #2

关注点 (51.4243877,-0.34745) 并查找6个结果。

$result = $api->autosuggest("fun.with.code", [AutoSuggestOption::focus(51.4243877,-0.34745), AutoSuggestOption::numberResults(6)]);
print_r($result);

代码示例 #3

验证what3words

$result = $api->isPossible3wa("filled.count.soap");
print_r($result); // yields 1

$result = $api->isPossible3wa("not a 3wa");
print_r($result); // yields 0

$result = $api->findPossible3wa('from "index.home.raft" to " "filled.count.soap"');
print_r(implode(", ", $result)); // yields "index.home.raft, filled.count.soap"

$result = $api->isValid3wa('filled.count.soapp');
print_r($result ? $result : 'invalid'); // yields 'invalid'

错误处理

所有函数都将返回一个包含请求数据的stdClass对象，或者在失败时返回false。如果返回false，则调用get_error()，它将返回一个包含code值和message值的关联数组。

print_r($api->getError());

错误值在what3words REST API文档中列出。

开发（使用Docker）

您可以通过运行docker compose watch（确保您是从development目录运行此命令）来查看w3w-php-wrapper的作用，并在浏览器中打开http://localhost:9000。您对源代码所做的任何更改都会在您刷新浏览器时重新加载，只需确保您已通过运行export W3W_API_KEY=加载了名为W3W_API_KEY的环境变量。

$ export W3W_API_KEY=KEYFROMW3W
$ docker compose watch
[+] Building 0.6s (18/18) FINISHED
[+] Running 1/1
 ✔ Container php-server  Started                                                                                     0.0s
Watch configuration for service "server":
  - Action sync for path "/w3w-php-wrapper/development/src"
  - Action sync for path "/w3w-php-wrapper/src"
  - Action sync for path "/w3w-php-wrapper/tests"

运行测试（使用Docker）

启动容器后，您可以通过运行docker exec php-server /var/www/html/vendor/bin/phpunit来执行单元测试。

$ docker exec php-server /var/www/html/vendor/bin/phpunit
PHPUnit 5.5.4 by Sebastian Bergmann and contributors.

......................                                            22 / 22 (100%)

Time: 1.57 seconds, Memory: 3.25MB

OK (22 tests, 25 assertions)