Merge branch 'master' into timezone

Author: cmfcmf

Diff for: .gitattributes

@@ -0,0 +1 @@
+/docs export-ignore

Diff for: .github/workflows/main.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@master
+    - name: Use Node.js 10.x
+      uses: actions/setup-node@v1
+      with:
+        node-version: 10.x
+    - name: Build Docs
+      run: |
+        cd docs
+        yarn install
+        yarn build
+        touch build/.nojekyll
+    - name: Upload to GitHub Pages
+      if: github.ref == 'refs/heads/master'
+      uses: peaceiris/[email protected]
+      env:
+        GITHUB_TOKEN: ${{ secrets.GH_PAT }}
+        PUBLISH_BRANCH: gh-pages
+        PUBLISH_DIR: ./docs/build
+      with:
+        emptyCommits: false
+        keepFiles: false

Diff for: Cmfcmf/OpenWeatherMap.php

@@ -213,8 +213,7 @@ public function getWeatherGroup($ids, $units = 'imperial', $lang = 'en', $appid
     }
 
     /**
-     * Returns the forecast for the place you specified. DANGER: Might return
-     * fewer results than requested due to a bug in the OpenWeatherMap API!
+     * Returns the forecast for the place you specified.
      *
      * @param array|int|string $query The place to get weather information for. For possible values see ::getWeather.
      * @param string           $units Can be either 'metric' or 'imperial' (default). This affects almost all units returned.
@@ -244,8 +243,7 @@ public function getWeatherForecast($query, $units = 'imperial', $lang = 'en', $a
     }
 
     /**
-     * Returns the DAILY forecast for the place you specified. DANGER: Might return
-     * fewer results than requested due to a bug in the OpenWeatherMap API!
+     * Returns the DAILY forecast for the place you specified.
      *
      * @param array|int|string $query The place to get weather information for. For possible values see ::getWeather.
      * @param string           $units Can be either 'metric' or 'imperial' (default). This affects almost all units returned.

Diff for: Cmfcmf/OpenWeatherMap/Forecast.php

@@ -54,7 +54,15 @@ public function __construct(\SimpleXMLElement $xml, $units)
 
         $xml->temperature['value'] = round((floatval($xml->temperature['max']) + floatval($xml->temperature['min'])) / 2, 2);
 
-        $this->temperature = new Temperature(new Unit($xml->temperature['value'], $temperatureUnit), new Unit($xml->temperature['min'], $temperatureUnit), new Unit($xml->temperature['max'], $temperatureUnit), new Unit($xml->temperature['day'], $temperatureUnit), new Unit($xml->temperature['morn'], $temperatureUnit), new Unit($xml->temperature['eve'], $temperatureUnit), new Unit($xml->temperature['night'], $temperatureUnit));
+        $this->temperature = new Temperature(
+            new Unit($xml->temperature['value'], $temperatureUnit),
+            new Unit($xml->temperature['min'], $temperatureUnit),
+            new Unit($xml->temperature['max'], $temperatureUnit),
+            new Unit($xml->temperature['day'], $temperatureUnit),
+            new Unit($xml->temperature['morn'], $temperatureUnit),
+            new Unit($xml->temperature['eve'], $temperatureUnit),
+            new Unit($xml->temperature['night'], $temperatureUnit)
+        );
         $this->humidity = new Unit($xml->humidity['value'], $xml->humidity['unit']);
         $this->pressure = new Unit($xml->pressure['value'], $xml->pressure['unit']);
 

Diff for: Examples/AirPollution.php

@@ -42,7 +42,7 @@
 
 $owm = new OpenWeatherMap($myApiKey, $httpClient, $httpRequestFactory);
 
-// Example 1: Get current uv index in Berlin.
+// Example 1: Get current air pollution in Berlin.
 $o3 = $owm->getAirPollution("O3", "52", "13");
 $no2 = $owm->getAirPollution("NO2", "52", "13");
 $so2 = $owm->getAirPollution("SO2", "52", "13");

Diff for: Examples/UVIndex.php

@@ -29,12 +29,6 @@
     $cli = true;
 }
 
-// Language of data (try your own language here!):
-$lang = 'de';
-
-// Units (can be 'metric' or 'imperial' [default]):
-$units = 'metric';
-
 // You can use every PSR-17 compatible HTTP request factory
 // and every PSR-18 compatible HTTP client.
 $httpRequestFactory = new RequestFactory();

Diff for: Examples/WeatherForecast.php

@@ -61,7 +61,7 @@
 }
 
 // Example 2: Get forecast for the next 3 days for Berlin.
-$forecast = $owm->getWeatherForecast('Berlin', $units, $lang, '', 3);
+$forecast = $owm->getWeatherForecast('Berlin', $units, $lang, '', 16);
 echo "EXAMPLE 2<hr />\n\n\n";
 
 foreach ($forecast as $weather) {

Diff for: README.md

@@ -2,8 +2,8 @@ OpenWeatherMap PHP API
 ======================
 A PHP 7.0+ API to retrieve and parse global weather data from
 [OpenWeatherMap.org](http://www.OpenWeatherMap.org).
-This library aims to normalise the provided data and remove some inconsistencies.
-This library is neither maintained by OpenWeatherMap nor their official PHP API.
+This project aims to normalise the provided data and remove inconsistencies.
+It is not maintained by OpenWeatherMap and not an official API wrapper.
 
 [![Build Status](https://travis-ci.org/cmfcmf/OpenWeatherMap-PHP-Api.svg?branch=master)](https://travis-ci.org/cmfcmf/OpenWeatherMap-PHP-Api)
 [![license](https://img.shields.io/github/license/cmfcmf/OpenWeatherMap-PHP-Api.svg)](https://github.com/cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
@@ -13,74 +13,14 @@ This library is neither maintained by OpenWeatherMap nor their official PHP API.
 <br>
 [![SensioLabsInsight](https://insight.sensiolabs.com/projects/0addfb24-e2b4-4feb-848e-86b2078ca104/big.png)](https://insight.sensiolabs.com/projects/0addfb24-e2b4-4feb-848e-86b2078ca104)
 
-Installation
-============
-This library can be found on [Packagist](https://packagist.org/packages/cmfcmf/openweathermap-php-api).
-The recommended way to install and use it is through [Composer](http://getcomposer.org).
-
-    composer require "cmfcmf/openweathermap-php-api"
-
-You will also need to choose and install two additional dependencies separately:
-
-1. A [PSR-17](https://www.php-fig.org/psr/psr-17/) compatible HTTP factory implementation.
-A list of HTTP factory implementations is available at
-[Packagist](https://packagist.org/providers/psr/http-factory-implementation).
-2. A [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible HTTP client implementation.
-A list of HTTP client implementations is available at
-[Packagist](https://packagist.org/providers/psr/http-client-implementation).
-
-Example call
-============
-```php
-<?php
-use Cmfcmf\OpenWeatherMap;
-use Cmfcmf\OpenWeatherMap\Exception as OWMException;
-use Http\Factory\Guzzle\RequestFactory;
-use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
-
-// Must point to composer's autoload file.
-require 'vendor/autoload.php';
-
-// Language of data (try your own language here!):
-$lang = 'de';
-
-// Units (can be 'metric' or 'imperial' [default]):
-$units = 'metric';
-
-// You can use every PSR-17 compatible HTTP request factory
-// and every PSR-18 compatible HTTP client. This example uses
-// `http-interop/http-factory-guzzle` ^1.0 and `php-http/guzzle6-adapter` ^2.0 || ^1.0
-// which you need to install separately.
-$httpRequestFactory = new RequestFactory();
-$httpClient = GuzzleAdapter::createWithConfig([]);
-
-// Create OpenWeatherMap object.
-$owm = new OpenWeatherMap('YOUR-API-KEY', $httpClient, $httpRequestFactory);
-
-try {
-    $weather = $owm->getWeather('Berlin', $units, $lang);
-} catch(OWMException $e) {
-    echo 'OpenWeatherMap exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
-} catch(\Exception $e) {
-    echo 'General exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
-}
-
-echo $weather->temperature;
-```
+Documentation
+=============
 
-For more example code and instructions on how to use this library, please take
-a look into  the `Examples` folder. Make sure to get an API Key from
-http://home.openweathermap.org/ and put it into `Examples/ApiKey.ini`.
-
-- `CurrentWeather.php` shows how to receive the current weather.
-- `WeatherForecast.php` shows how to receive weather forecasts.
-- `UVIndex.php` shows how to receive uv index data.
-- `AirPollution.php` show how to receive air pollution data.
+You can find the latest documentation, including installation and usage instructions at https://cmfcmf.github.io/OpenWeatherMap-PHP-API.
 
 Contributing
 ============
-I'm happy about every **pull request** or **issue** you find and open to help
-make this API **more awesome**.
+I'm happy about every **pull request** you open and **issue** you find to help make this API **more awesome**. Please note that it might sometimes take me a while to get back to you. Feel free to ping me if I don't respond.
 
 ## Vagrant
 
@@ -105,13 +45,26 @@ And then execute an example:
 
     > php Examples/CurrentWeather.php
 
+## Documentation
+
+The documentation is built using [Docusuaurs v2](https://v2.docusaurus.io/).
+To run a local developnment server for the docs, execute
+
+```bash
+cd docs
+yarn install
+yarn start
+```
 
 License
 =======
-MIT — Please see the [LICENSE file](https://github.com/Cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
+
+This project is licensed under the MIT license.
+Please see the [LICENSE file](https://github.com/Cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
 distributed with this source code for further information regarding copyright and licensing.
 
-**Please check out the following official links to read about the terms, pricing
-and license of OpenWeatherMap before using the service:**
+Be aware that the OpenWeatherMap data is **not licensed under the MIT**.
+**Check out the following official links to read about the terms, pricing and license of OpenWeatherMap before using their service:**
+
 - [OpenWeatherMap.org/terms](http://OpenWeatherMap.org/terms)
 - [OpenWeatherMap.org/appid](http://OpenWeatherMap.org/appid)

Diff for: docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

Diff for: docs/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+```
+$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

Diff for: docs/docs/api-key.md

@@ -0,0 +1,21 @@
+---
+title: API Key
+---
+
+All requests require a free API key (sometimes called "APPID") from OpenWeaterMap.
+To retrieve your API key, [sign up for an OpenWeatherMap account](https://home.openweathermap.org/users/sign_up).
+
+After you received your API key, **it might take a ["couple of hours"](https://openweathermap.org/appid) for it to be activated! Other users [reported](https://github.com/cmfcmf/OpenWeatherMap-PHP-API/issues/46) that it took about 10 minutes** until the API key worked.
+
+Please also take note of the license OpenWeatherMap provides the data under. At the time of
+writing, all data is licensed under the **CC BY-SA 4.0**, even for paid accounts. However,
+remember that this project is not affiliated with OpenWeatherMap, this information may be
+outdated and I can't give you legal advice. Make sure to check on the terms and conditions
+yourself:
+
+- https://openweathermap.org/terms
+- https://openweathermap.org/price
+
+*If something with your API key or account does not work as expected,
+please [contact OpenWeatherMap directly](https://openweathermap.force.com/s/contactsupport)
+instead of opening an issue, since I most likely cannot help you with your account.*

Diff for: docs/docs/apis/air-pollution.md

@@ -0,0 +1,85 @@
+---
+title: Air Pollution API
+sidebar_label: 'API: Air Pollution'
+---
+
+This API allows you to retrieve the current, forecast and historic ultraviolet index (UV index).
+
+> Corresponding OpenWeatherMap documentation:
+>
+> - [Carbon Monoxide (CO)](https://openweathermap.org/api/pollution/co)
+> - [Ozone (O3)](https://openweathermap.org/api/pollution/o3)
+> - [Nitrogen Dioxide (NO2)](https://openweathermap.org/api/pollution/no2)
+> - [Sulfor Dioxide (SO2)](https://openweathermap.org/api/pollution/so2)
+
+## Usage
+
+- `$type`: Can be one of `"O3"`, `"NO2"`, `"SO2"`, or `"CO"`.
+- `$lat` / `$lng`: Latitude and longitude must be provided as strings, because
+  the number of digits after the decimal point determines the search radius.
+  Specifying more digits leads to closer results, but too many digits can lead
+  to no result at all.
+- `$date`: Date to retrieve data from. `"current"` requests the newest available
+  information. You can also specify a date in ISO 8601 format. More information on
+  that can be found [in the OpenWeatherMap documentation](https://openweathermap.org/api/pollution/co).
+
+```php
+// $type =
+$co = $owm->getAirPollution($type, $lat, $lng, $date = "current");
+```
+
+The return value depends on the `$type` and is discussed in the next sections.
+
+## Carbon Monoxide (CO)
+
+```php
+$co = $owm->getAirPollution("CO", "52", "13");
+if ($co === null) {
+    // No data available
+} else {
+    foreach ($co->values as $data) {
+        echo $data["value"];
+        echo $data["value"]->getPrecision();
+        echo $data["pressure"];
+    }
+}
+```
+
+## Ozone (O3)
+
+```php
+$o3 = $owm->getAirPollution("O3", "52", "13");
+if ($o3 === null) {
+    // No data available
+} else {
+    echo $o3->value;
+}
+```
+
+## Nitrogen Dioxide (NO2)
+
+```php
+$no2 = $owm->getAirPollution("NO2", "52", "13");
+if ($no2 === null) {
+    // No data available
+} else {
+    echo $no2->value;
+    echo $no2->valueStratosphere;
+    echo $no2->valueTroposphere;
+}
+```
+
+## Sulfor Dioxide (SO2)
+
+```php
+$so2 = $owm->getAirPollution("SO2", "52", "13");
+if ($so2 === null) {
+    // No data available
+} else {
+    foreach ($so2->values as $data) {
+        echo $data["value"];
+        echo $data["value"]->getPrecision();
+        echo $data["pressure"];
+    }
+}
+```