From 850705cfe218bffbc79d1e8370938151936f9605 Mon Sep 17 00:00:00 2001 From: Leonard Fischer Date: Wed, 24 Jan 2018 20:48:00 +0100 Subject: [PATCH] Updating code style, README and the license --- LICENSE | 2 +- README.md | 11 +- src/API.php | 251 ++++++++++---------- src/Request.php | 501 ++++++++++++++++++++-------------------- src/WunderException.php | 23 +- 5 files changed, 393 insertions(+), 395 deletions(-) diff --git a/LICENSE b/LICENSE index 1080f3a..f5ec05e 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2017 Leonard Fischer +Copyright (c) 2018 Leonard Fischer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 58db053..ee9985b 100644 --- a/README.md +++ b/README.md @@ -33,10 +33,15 @@ At some point I'd like to improve this client to be as readable as possible. For ```php use lfischer\wunderground; - + $weather = (new API('')) ->getConditions() ->byLocation('Germany', 'Dusseldorf') ->fetch() - ->asArray(); -``` \ No newline at end of file + ->asArray(); +``` + +## Contributors + + - **Leonard Fischer** - initial programming [Github profile](https://github.com/leonardfischer) + - **Stefano Borghi** - writing tests and improving code [Github profile](https://github.com/stebogit) \ No newline at end of file diff --git a/src/API.php b/src/API.php index af9d00a..bd5f40d 100644 --- a/src/API.php +++ b/src/API.php @@ -11,133 +11,124 @@ */ class API extends Request { - /** - * Retrieves weather data by a weather station ID. - * See https://www.wunderground.com/wundermap/ for more information - * - * @param string $id - * @return array - * @throws \ErrorException - */ - public function getByPWSId ($id) - { - return $this->fetch(['query' => 'pws:' . $id])->getResponseArray(); - } // function - - - /** - * Retrieves weather data by a airport code. - * - * @param string $code - * @return array - * @throws \ErrorException - */ - public function getByAirportCode ($code) - { - return $this->fetch(['query' => $code])->getResponseArray(); - } // function - - - /** - * Retrieves weather data by geo coordinates. - * - * @param float $lat - * @param float $lng - * @return array - * @throws \ErrorException - */ - public function getByCoordinates ($lat, $lng) - { - return $this->fetch(['query' => $lat . ',' . $lng])->getResponseArray(); - } // function - - - /** - * Retrieves weather data by a given country and city name. - * - * @param string $country - * @param string $city - * @return array - * @throws \ErrorException - */ - public function getByLocation ($country, $city) - { - return $this->fetch(['query' => $country . '/' . $city])->getResponseArray(); - } // function - - - /** - * Retrieves weather data by a given country and city name. - * - * @param string|int $zipcode - * @return array - * @throws \ErrorException - */ - public function getByUSZipcode ($zipcode) - { - return $this->fetch(['query' => $zipcode])->getResponseArray(); - } // function - - - /** - * Retrieves weather data by a given country and city name. - * - * @param string $state - * @param string $city - * @return array - * @throws \ErrorException - */ - public function getByUSCity ($state, $city) - { - $c = str_replace(' ', '_', $city); - return $this->fetch(['query' => $state . '/' . $c])->getResponseArray(); - } // function - - - /** - * Retrieves hourly and daily weather forecast data by a given location (country+city, coordinates, - * zipcode, etc) for the next three days (daily records) or 36 hours (hourly records). - * Daily records will include today, hourly records will include the current hour. - * - * @param string $location any valid Country/City, Lat,Lon, Airport code, etc. - * @return array - * @throws \ErrorException - */ - public function getForecast ($location) - { - return $this->setFeatures(['forecast', 'hourly'])->setQuery($location)->fetch()->getResponseArray(); - } // function - - - /** - * Retrieves hourly and daily weather forecast data by a given - * location (country+city, coordinates, zipcode, etc) for the next 10 days. - * Daily records will include today, hourly records will include the current hour. - * - * @param string $location Country/City, Lat,Lon, Airport code, etc. - * @return array - * @throws \ErrorException - */ - public function getExtendedForecast ($location) - { - return $this->setFeatures(['forecast10day', 'hourly10day'])->setQuery($location)->fetch()->getResponseArray(); - } // function - - - /** - * Retrieves observed weather records and the daily summary for the specified date. - * - * @param string $date any valid {@link http://php.net/manual/en/datetime.formats.date.php Date Formats} format - * @param string $location Country/City, Lat,Lon, Airport code, etc. - * @return array - * @throws \ErrorException - */ - public function getHistoric ($date, $location) - { - $d = date('Ymd', strtotime($date)); - - return $this->setFeature("history_$d")->setQuery($location)->fetch()->getResponseArray(); - } // function - - -} // class \ No newline at end of file + /** + * Retrieves weather data by a weather station ID. + * See https://www.wunderground.com/wundermap/ for more information + * + * @param string $id + * @return array + * @throws \ErrorException + */ + public function getByPWSId($id) + { + return $this->fetch(['query' => 'pws:' . $id])->getResponseArray(); + } + + /** + * Retrieves weather data by a airport code. + * + * @param string $code + * @return array + * @throws \ErrorException + */ + public function getByAirportCode($code) + { + return $this->fetch(['query' => $code])->getResponseArray(); + } + + /** + * Retrieves weather data by geo coordinates. + * + * @param float $lat + * @param float $lng + * @return array + * @throws \ErrorException + */ + public function getByCoordinates($lat, $lng) + { + return $this->fetch(['query' => $lat . ',' . $lng])->getResponseArray(); + } + + /** + * Retrieves weather data by a given country and city name. + * + * @param string $country + * @param string $city + * @return array + * @throws \ErrorException + */ + public function getByLocation($country, $city) + { + return $this->fetch(['query' => $country . '/' . $city])->getResponseArray(); + } + + /** + * Retrieves weather data by a given country and city name. + * + * @param string|int $zipcode + * @return array + * @throws \ErrorException + */ + public function getByUSZipcode($zipcode) + { + return $this->fetch(['query' => $zipcode])->getResponseArray(); + } + + /** + * Retrieves weather data by a given country and city name. + * + * @param string $state + * @param string $city + * @return array + * @throws \ErrorException + */ + public function getByUSCity($state, $city) + { + $c = str_replace(' ', '_', $city); + + return $this->fetch(['query' => $state . '/' . $c])->getResponseArray(); + } + + /** + * Retrieves hourly and daily weather forecast data by a given location (country+city, coordinates, + * zipcode, etc) for the next three days (daily records) or 36 hours (hourly records). + * Daily records will include today, hourly records will include the current hour. + * + * @param string $location any valid Country/City, Lat,Lon, Airport code, etc. + * @return array + * @throws \ErrorException + */ + public function getForecast($location) + { + return $this->setFeatures(['forecast', 'hourly'])->setQuery($location)->fetch()->getResponseArray(); + } + + /** + * Retrieves hourly and daily weather forecast data by a given + * location (country+city, coordinates, zipcode, etc) for the next 10 days. + * Daily records will include today, hourly records will include the current hour. + * + * @param string $location Country/City, Lat,Lon, Airport code, etc. + * @return array + * @throws \ErrorException + */ + public function getExtendedForecast($location) + { + return $this->setFeatures(['forecast10day', 'hourly10day'])->setQuery($location)->fetch()->getResponseArray(); + } + + /** + * Retrieves observed weather records and the daily summary for the specified date. + * + * @param string $date any valid {@link http://php.net/manual/en/datetime.formats.date.php Date Formats} format + * @param string $location Country/City, Lat,Lon, Airport code, etc. + * @return array + * @throws \ErrorException + */ + public function getHistoric($date, $location) + { + $d = date('Ymd', strtotime($date)); + + return $this->setFeature("history_$d")->setQuery($location)->fetch()->getResponseArray(); + } +} \ No newline at end of file diff --git a/src/Request.php b/src/Request.php index f9fb369..2f03a7a 100644 --- a/src/Request.php +++ b/src/Request.php @@ -9,257 +9,250 @@ */ class Request { - const URL = 'http://api.wunderground.com/api/:apiKey/:features/:settings/q/:query.json'; - - /** - * @var string - */ - protected $apiKey = ''; - - /** - * @var string - */ - protected $features = 'conditions'; - - /** - * @var string - */ - protected $settings = 'lang:EN'; - - /** - * @var string - */ - protected $query = 'CA/San_Francisco'; - - /** - * @var string - */ - protected $lastQuery = null; - - /** - * @var string - */ - protected $responseJSON = null; - - /** - * @var array - */ - protected $responseArray = null; - - - /** - * Constructor. - * - * @param $apiKey - */ - public function __construct ($apiKey) - { - $this->apiKey = $apiKey; - } // function - - - /** - * Set a API feature. Available features: - * - alerts - * - almanac - * - astronomy - * - conditions - * - currenthurricane - * - forecast - * - forecast10day - * - geolookup - * - history - * - hourly - * - hourly10day - * - planner - * - rawtide - * - tide - * - webcams - * - yesterday - * - * @param string|array $features - * @return $this - */ - public function setFeature ($features) - { - $this->setFeatures([$features]); - - return $this; - } // function - - - /** - * Set multiple API features. Available features: - * - alerts - * - almanac - * - astronomy - * - conditions - * - currenthurricane - * - forecast - * - forecast10day - * - geolookup - * - history - * - hourly - * - hourly10day - * - planner - * - rawtide - * - tide - * - webcams - * - yesterday - * - * @param array $features - * @return $this - */ - public function setFeatures ($features) - { - $this->features = implode('/', $features); - - return $this; - } // function - - - /** - * Set a API setting. Available settings are: - * - lang - * - pws - * - bestfct - * - * @param string $settings - * @return $this - */ - public function setSettings ($settings) - { - $this->settings = $settings; - - return $this; - } // function - - - /** - * Set a API query. Query examples: - * - / - * - / - * - / - * - , - * - - * - pws: - * - autoip - * - autoip.json?geo_ip= - * - * @param string $query - * @return $this - */ - public function setQuery ($query) - { - $this->query = $query; - - return $this; - } // function - - - /** - * API fetch method. - * - * @param array $parameters - * @return $this - * @throws \ErrorException - */ - public function fetch (array $parameters = []) - { - if (isset($parameters['features'])) { - $this->setFeature($parameters['features']); - } // if - - if (isset($parameters['settings'])) { - $this->setSettings($parameters['settings']); - } // if - - if (isset($parameters['query'])) { - $this->setQuery($parameters['query']); - } // if - - $url = strtr(self::URL, [ - ':apiKey' => $this->apiKey, - ':features' => $this->features, - ':settings' => $this->settings, - ':query' => $this->query, - ]); - - $this->lastQuery = $url; - - $this->responseJSON = $this->request($url); - $this->responseArray = json_decode($this->responseJSON, true); - - if (!is_array($this->responseArray)) { - throw new WunderException('The Weather Underground API response returned no valid JSON: ' . $this->responseJSON); - } // if - - if (!isset($this->responseArray['response'])) { - throw new WunderException('The Weather Underground API response is not set or empty: ' . $this->responseJSON); - } // if - - if (isset($this->responseArray['response']) && isset($this->responseArray['response']['error'])) { - throw new WunderException('The Weather Underground API responded with errors: ' . var_export($this->responseArray['response']['error'], true)); - } // if - - return $this; - } // function - - - /** - * Method for returning the raw response. - * - * @return string - */ - public function getResponseJSON () - { - return $this->responseJSON; - } // function - - - /** - * Method for returning the response array. - * - * @return array - */ - public function getResponseArray () - { - return $this->responseArray; - } // function - - - /** - * Method for returning the response as object. - * - * @return \stdClass - */ - public function getResponseObject () - { - return json_decode($this->responseJSON); - } // function - - - /** - * Method for getting the data from the API. - * - * @param $url - * @return string - */ - protected function request ($url) - { - return @file_get_contents($url); - } // function - - - /** - * Method for getting the last called query. - * - * @return string - */ - public function getLastQuery () - { - return $this->lastQuery; - } // function - - -} // class \ No newline at end of file + const URL = 'http://api.wunderground.com/api/:apiKey/:features/:settings/q/:query.json'; + + /** + * @var string + */ + protected $apiKey = ''; + + /** + * @var string + */ + protected $features = 'conditions'; + + /** + * @var string + */ + protected $settings = 'lang:EN'; + + /** + * @var string + */ + protected $query = 'CA/San_Francisco'; + + /** + * @var string + */ + protected $lastQuery = null; + + /** + * @var string + */ + protected $responseJSON = null; + + /** + * @var array + */ + protected $responseArray = null; + + /** + * Constructor. + * + * @param $apiKey + */ + public function __construct($apiKey) + { + $this->apiKey = $apiKey; + } // function + + /** + * Set a API feature. Available features: + * - alerts + * - almanac + * - astronomy + * - conditions + * - currenthurricane + * - forecast + * - forecast10day + * - geolookup + * - history + * - hourly + * - hourly10day + * - planner + * - rawtide + * - tide + * - webcams + * - yesterday + * + * @param string|array $features + * @return $this + */ + public function setFeature($features) + { + $this->setFeatures([$features]); + + return $this; + } + + /** + * Set multiple API features. Available features: + * - alerts + * - almanac + * - astronomy + * - conditions + * - currenthurricane + * - forecast + * - forecast10day + * - geolookup + * - history + * - hourly + * - hourly10day + * - planner + * - rawtide + * - tide + * - webcams + * - yesterday + * + * @param array $features + * @return $this + */ + public function setFeatures($features) + { + $this->features = implode('/', $features); + + return $this; + } + + /** + * Set a API setting. Available settings are: + * - lang + * - pws + * - bestfct + * + * @param string $settings + * @return $this + */ + public function setSettings($settings) + { + $this->settings = $settings; + + return $this; + } + + /** + * Set a API query. Query examples: + * - / + * - / + * - / + * - , + * - + * - pws: + * - autoip + * - autoip.json?geo_ip= + * + * @param string $query + * @return $this + */ + public function setQuery($query) + { + $this->query = $query; + + return $this; + } + + /** + * API fetch method. + * + * @param array $parameters + * @return $this + * @throws \ErrorException + */ + public function fetch(array $parameters = []) + { + if (isset($parameters['features'])) + { + $this->setFeature($parameters['features']); + } + + if (isset($parameters['settings'])) + { + $this->setSettings($parameters['settings']); + } + + if (isset($parameters['query'])) + { + $this->setQuery($parameters['query']); + } + + $url = strtr(self::URL, [ + ':apiKey' => $this->apiKey, + ':features' => $this->features, + ':settings' => $this->settings, + ':query' => $this->query, + ]); + + $this->lastQuery = $url; + + $this->responseJSON = $this->request($url); + $this->responseArray = json_decode($this->responseJSON, true); + + if (!is_array($this->responseArray)) + { + throw new WunderException('The Weather Underground API response returned no valid JSON: ' . $this->responseJSON); + } + + if (!isset($this->responseArray['response'])) + { + throw new WunderException('The Weather Underground API response is not set or empty: ' . $this->responseJSON); + } + + if (isset($this->responseArray['response']) && isset($this->responseArray['response']['error'])) + { + throw new WunderException('The Weather Underground API responded with errors: ' . var_export($this->responseArray['response']['error'], true)); + } + + return $this; + } + + /** + * Method for returning the raw response. + * + * @return string + */ + public function getResponseJSON() + { + return $this->responseJSON; + } + + /** + * Method for returning the response array. + * + * @return array + */ + public function getResponseArray() + { + return $this->responseArray; + } + + /** + * Method for returning the response as object. + * + * @return \stdClass + */ + public function getResponseObject() + { + return json_decode($this->responseJSON); + } + + /** + * Method for getting the data from the API. + * + * @param $url + * @return string + */ + protected function request($url) + { + return @file_get_contents($url); + } + + /** + * Method for getting the last called query. + * + * @return string + */ + public function getLastQuery() + { + return $this->lastQuery; + } +} \ No newline at end of file diff --git a/src/WunderException.php b/src/WunderException.php index b11b460..ec9ef5c 100644 --- a/src/WunderException.php +++ b/src/WunderException.php @@ -2,13 +2,22 @@ namespace lfischer\wunderground; - +/** + * Wunder exception. + * + * @author Stefano Borghi + */ class WunderException extends \ErrorException { - - public function __construct ($message = null, $code = 0, \ErrorException $previous = null) - { - parent::__construct($message, $code, $previous); - } - + /** + * WunderException constructor. + * + * @param string $message + * @param int $code + * @param \ErrorException|null $previous + */ + public function __construct($message = null, $code = 0, \ErrorException $previous = null) + { + parent::__construct($message, $code, $previous); + } } \ No newline at end of file