monkeyphp/open-weather-map

Client library for accessing the OpenWeatherMap API

OpenWeatherMap

A PHP client library for accessing the OpenWeatherMap Api., _(*1)

, _(*2)

The OpenWeatherMap library is a client library for accessing weather data from the free OpenWeatherMap Api., _(*3)

You can read more about OpenWeatherMap here., _(*4)

The library is built on top of a number of Zend Framework 2 components., _(*5)

Links

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

Get the OpenWeatherMap library

The easiest way to get the library is to use Composer and Packagist., _(*6)

If you do not already have Composer in your application, you can install it as follows., _(*7)

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

Create the composer.json file., _(*8)

$ touch composer.json

Add the following to the composer.json file, _(*9)

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

Finally run Composer install, _(*10)

$ php composer.phar install

You should now have the library installed into your vendors directory., _(*11)

Autoloading the OpenWeatherMap library

The easiest way to start using OpenWeatherMap is to use the Composer autoloader., _(*12)

Include the Composer autoloader into your script, _(*13)

require_once "vendor/autoload.php";

Create an instance of OpenWeatherMap

The OpenWeatherMap library provides a top level class OpenWeatherMap that all available functionality can be accessed through., _(*14)

A default instance (without any parameters) can be constructed as follows:, _(*15)

$openWeatherMap = new OpenWeatherMap\OpenWeatherMap();

You can alos construct an instance of OpenWeatherMap you can also supply a set of constructor options., _(*16)

The accepted keys to the constructor are:, _(*17)

defaults

Supply an array of query values that will be used as parameters in subsequent queries

connectorFactory

For example, we can create an instance of OpenWeatherMap as follows, _(*18)

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

Now all subsequent queries will automatically include the supplied apiKey, mode and query value., _(*19)

$current = $openWeatherMap->weather();

ConnectorFactory and Connectors

Internally, the OpenWeatherMap library uses a factory class to manage the plumbing for connecting to the OpenWeatherMap Api., _(*20)

The primary role of the ConnectorFactory is to create Connector classes that are then used to query each of the endpoints that the OpenWeatherMap Api exposes., _(*21)

Each of the Connector classes requires a Lock classes that manages throttling calls to the api., _(*22)

Locking

The OpenWeatherMap utilises a simple locking mechanism to throttle requests to the http://openweathermap.org/ api., _(*23)

To quote the openweathermap.org docs, _(*24)

Do not send requests more then 1 time per 10 minutes from one device. The weather is changing not so frequently as usual., _(*25)

The locking mechanism is enabled by default to work in accordance with the above recommendation from openweathermap.org and should work out of the box., _(*26)

What this means is that requests to the openweathermap.org api are throttled to one request every 10 minutes (or 600 seconds)., _(*27)

It is possible to override the default implementation by constructing the OpenWeatherMap instance with the following parameters, setting 'minLifetime' to the limit you require., _(*28)

For example, set this value to 300 to throttle requests to 1 time per 5 minutes., _(*29)

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

It is also possible to construct a Lock instance first and pass that to the constructor in the options array., _(*30)

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

It is also possible to enable locking that allows queries to be made irrespective of throttling., _(*31)

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

The Lock class supports the following options, _(*32)

file

The path of the lock file.

maxLifetime

The maximum number of seconds before a lock if forceably released.

minLifetime

The minium number of seconds that a lock lives for.

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

Using the OpenWeatherMap instance

Once you have constructed an OpenWeatherMap instance, configured to your needs, you can now start using it to query the api., _(*33)

There are 3 methods that the OpenWeatherMap exposes., _(*34)

All 3 methods accept an array of values, which may contain the following keys., _(*35)

latitude

longitude

id

query

apiKey

count

mode

units

language

In the array of options, you must provide at least one of the following (in preference order):, _(*36)

1. query
2. latitude and longitude
3. id

The above keys are used in part of a preferential order., _(*37)

For example, supplying both query and id will result in the query value being used to query the OpenWeatherMap Api with as that has a higher preference., _(*38)

Get the current weather

If you supplied a set of default options when you created the OpenWeatherMap, then you can just make the call., _(*39)

$weather = $openWeatherMap->getWeather();

If you created a default instance of OpenWeatherMap, then you will need to supply an array of options when you make the call., _(*40)

Remember that you must provide an id, a query or a latitude and longitude value., _(*41)

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

OpenWeatherMap::getWeather() will return an instance of OpenWeatherMap\Entity\Current which can then be queried for the details about the current weather., _(*42)

$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;

Get the daily forecast

If you supplied a set of default options when you created the OpenWeatherMap, then you can just make the call., _(*43)

$weatherData = $openWeatherMap->getDaily();

If you created a default instance of OpenWeatherMap, then you will need to supply an array of options when you make the call., _(*44)

Remember that you must provide an id, a query or a latitude and longitude value., _(*45)

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

Get the hourly forecast

If you supplied a set of default options when you created the OpenWeatherMap, then you can just make the call., _(*46)

$weatherData = $openWeatherMap->getForecast();

If you created a default instance of OpenWeatherMap, then you will need to supply an array of options when you make the call., _(*47)

Remember that you must provide an id, a query or a latitude and longitude value., _(*48)

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

Run the PHPUnit tests

The library is tested with PHPUnit., _(*49)

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

Run the PHP CS tests

The library uses a PSR compatible coding standard., _(*50)

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

License

Copyright (C) 2014 David White, _(*51)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version., _(*52)

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details., _(*53)

You should have received a copy of the GNU General Public License along with this program. If not, see [http://www.gnu.org/licenses/]., _(*54)