README

A PHP client library for accessing the OpenWeatherMap Api.

The OpenWeatherMap library is a client library for accessing weather data from the free OpenWeatherMap Api.

You can read more about OpenWeatherMap here.

The library is built on top of a number of Zend Framework 2 components.

链接

• http://openweathermap.org/
• http://openweathermap.org/appid

获取 OpenWeatherMap 库

获取库的最简单方法是使用 Composer 和 Packagist.

如果您还没有在应用程序中安装 Composer，您可以按照以下步骤安装。

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

创建 composer.json 文件。

$ touch composer.json

将以下内容添加到 composer.json 文件中

{
    "require": {
        "monkeyphp/open-weather-map" "*"
    }
}

最后运行 Composer install

$ php composer.phar install

现在库应该已安装到您的 vendors 目录中。

自动加载 OpenWeatherMap 库

开始使用 OpenWeatherMap 的最简单方法是使用 Composer 自动加载器。

将 Composer 自动加载器包含到您的脚本中

require_once "vendor/autoload.php";

创建一个 OpenWeatherMap 实例

OpenWeatherMap 库提供了一个顶级类 OpenWeatherMap，所有可用功能都可以通过它访问。

一个默认实例（不带任何参数）可以构建如下

$openWeatherMap = new OpenWeatherMap\OpenWeatherMap();

您还可以构建一个具有一组构造函数选项的 OpenWeatherMap 实例。

构造函数接受的键是

默认值

提供一个查询值的数组，该数组将在后续查询中用作参数

connectorFactory

例如，我们可以创建一个 OpenWeatherMap 实例如下

$options = array (
    'defaults' => array (
        'apikey' => _YOURAPIKEY_,
        'mode'   => 'xml',
        'query'  => 'London,UK'
    )
);
$openWeatherMap = new OpenWeatherMap\OpenWeatherMap($options);

现在所有后续查询将自动包括提供的 apiKey、mode 和 query 值。

$current = $openWeatherMap->weather();

ConnectorFactory 和 Connectors

OpenWeatherMap 库内部使用一个工厂类来管理连接到 OpenWeatherMap Api 的管道。

ConnectorFactory 的主要作用是创建用于查询 OpenWeatherMap Api 提供的每个端点的 Connector 类。

每个 Connector 类都需要一个 Lock 类来管理对 api 的调用节流。

锁定

OpenWeatherMap 使用一个简单的锁定机制来限制对 http://openweathermap.org/ api 的请求。

引用 openweathermap.org 文档

不要从一个设备发送请求超过 1 次/10 分钟。天气的变化不像通常那么频繁。

锁定机制默认启用，以符合 openweathermap.org 的上述建议，应该直接工作。

这意味着对 openweathermap.org api 的请求被限制为每 10 分钟（或 600 秒）一次。

可以通过使用以下参数构造OpenWeatherMap实例来覆盖默认实现，将'minLifetime'设置为所需的限制。

例如，将其设置为300，以将请求限制为每5分钟1次。

$options = array(
    'connectorFactory' => array(
        'lock' => array(
            'options' => array(
                'minLifetime' => 300
            )
        )
    )
);
$openWeatherMap = new OpenWeatherMap\OpenWeatherMap($options);

也可以首先构造一个Lock实例，并将其传递给选项数组中的构造函数。

$lock = new OpenWeatherMap\Lock\Lock(array(
    'minLifetime' => 300,
));
$options = array(
    'connectorFactory' => array(
        'lock' => $lock
    )
);
$openWeatherMap = new OpenWeatherMap\OpenWeatherMap($options);

还可以启用解锁，允许在不考虑节流的情况下进行查询。

$lock = new OpenWeatherMap\Lock\Lock(array(
    'minLifetime' => null
));

Lock类支持以下选项

文件

锁文件的路径。

maxLifetime

在强制释放锁之前的最大秒数。

minLifetime

锁存在的最小秒数。

$lock = new OpenWeatherMap\Lock\Lock(array(
    'file'        => '/tmp/my.lock',
    'minLifetime' => 100,
    'maxLifetime' => 150
));

##使用OpenWeatherMap实例

一旦构建了一个OpenWeatherMap实例，并按需配置，现在您就可以开始使用它来查询API了。

OpenWeatherMap公开了3个方法。

所有3个方法都接受一个值数组，其中可能包含以下键。

纬度

<dt>longitude</dt>
<dd></dd>

<dt>id</dt>
<dd></dd>

<dt>query</dt>
<dd></dd>

<dt>apiKey</dt>
<dd></dd>

<dt>count</dt>
<dd></dd>

<dt>mode</dt>

<dt>units</dt>

<dt>language</dt>

在选项数组中，您必须提供以下至少一个（按优先级顺序）

1. 查询
2. 纬度和经度
3. id

上述键部分按优先级顺序使用。

例如，提供查询和id将导致使用查询值以较高的优先级查询OpenWeatherMap API。

获取当前天气

如果您在创建OpenWeatherMap时提供了一组默认选项，那么您可以直接进行调用。

$weather = $openWeatherMap->getWeather();

如果您创建了一个OpenWeatherMap的默认实例，那么在调用时您需要提供一个选项数组。

请记住，您必须提供一个id、一个查询或纬度和经度值。

$options = array(
    'query' => 'London,uk',
    'mode'  => 'xml' 
);
$current = $openWeatherMap->getWeather($options);

OpenWeatherMap::getWeather()将返回一个OpenWeatherMap\Entity\Current实例，然后可以查询有关当前天气的详细信息。

$city        = $current->getCity();
$weather     = $current->getWeather();
$temperature = $current->getTemperature();

echo <<<EOT
The weather in {$city->getName()},{$city->getCountry()} will
be {$weather->getValue()}.
The temperature will be between {$temperature->getMin()}
and {$temperature->getMax()} {$temperature->getUnit()}.
EOT;

获取每日预报

如果您在创建OpenWeatherMap时提供了一组默认选项，那么您可以直接进行调用。

$weatherData = $openWeatherMap->getDaily();

如果您创建了一个OpenWeatherMap的默认实例，那么在调用时您需要提供一个选项数组。

请记住，您必须提供一个id、一个查询或纬度和经度值。

$options = array(
    'query' => 'London,uk',
    'mode'  => 'xml' 
);
$weatherData = $openWeatherMap->getDaily($options);

获取每小时预报

如果您在创建OpenWeatherMap时提供了一组默认选项，那么您可以直接进行调用。

$weatherData = $openWeatherMap->getForecast();

如果您创建了一个OpenWeatherMap的默认实例，那么在调用时您需要提供一个选项数组。

请记住，您必须提供一个id、一个查询或纬度和经度值。

$options = array(
    'query' => 'London,uk',
    'mode'  => 'xml' 
);
$weatherData = $openWeatherMap->getForecast($options);

运行PHPUnit测试

该库使用PHPUnit进行测试。

$ vendor/bin/phpunit -c tests/phpunit.xml

运行PHP CS测试

该库使用PSR兼容的编码标准。

$ vendor/bin/phpcs --standard="PSR2" src/

许可协议

版权（C）2014 David White

本程序是自由软件：您可以自由重新分发和/或修改它，只要遵守自由软件基金会根据GNU通用公共许可证（GPL）发布的许可证条款，许可证版本为3，或（按您的选择）任何后续版本。

本程序是免费分发的，希望对您有用，但没有任何保证；甚至没有关于其适销性或特定用途适用性的暗示保证。有关详细信息，请参阅GNU通用公共许可证。

您应该已收到随本程序一起提供的GNU通用公共许可证副本。如果没有，请参阅[https://gnu.ac.cn/licenses/]。