Adding the first API files - still some work to do :)

README.md

@@ -1 +1,27 @@
-# wunderground-api
+# Weather Underground API Client
+
+This library shall help you integrate the WeatherUnderground API to your webservice.
+It is extremely lightweight and provides all necessary code.
+
+## Code Example
+
+Using the API is very easy - you'll only need to provide a API key (Get one [here](https://www.wunderground.com/weather/api/)) in order to use it. There are functions for retrieving different weather data by predefined conditions, like "by country and city", "by latitude and longitude", "by airport code" or even "by IP address".
+
+```php
+// By default the current conditions will be requested in english language.
+$weather = (new \lfischer\wunderground\API('<API-key here>'))->getByLocation('Germany', 'Dusseldorf');
+```
+
+## Future to-dos / nice-to-have
+
+At some point I'd like to improve this client to be as readable as possible. For example:
+
+```php
+use lfischer\wunderground;
+
+$weather = (new API('<API-key here>'))
+    ->getConditions()
+    ->byLocation('Germany', 'Dusseldorf')
+    ->fetch()
+	->asArray();
+```

composer.json

@@ -0,0 +1,26 @@
+{
+	"name": "lfischer/wunderground-api",
+	"type": "library",
+	"description": "A simple PHP library for querying the Weather Underground API.",
+	"keywords": ["API", "weather"],
+	"homepage": "https://github.com/leonardfischer/wunderground-api",
+	"license": "MIT",
+	"authors": [{
+		"name": "Leonard Fischer",
+		"email": "[email protected]",
+		"homepage": "http://leonardfischer.de",
+		"role": "Developer"
+	}],
+    "support": {
+        "issues": "https://github.com/leonardfischer/wunderground-api/issues",
+        "source": "https://github.com/leonardfischer/wunderground-api"
+    },
+	"require": {
+		"php": ">=5.4.0"
+	},
+	"autoload": {
+		"psr-4": {
+			"lfischer\\wunderground\\": "src/"
+		}
+	}
+}

src/API.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace lfischer\wunderground;
+
+/**
+ * Basic Weather API class to execute predefined requests.
+ *
+ * @author Leonard Fischer <[email protected]>
+ */
+class API extends Request
+{
+	/**
+	 * Retrieves weather data by a (API internal) "city ID".
+	 *
+	 * @param string $id
+	 * @return array
+	 */
+	public function getByPWSId ($id)
+	{
+		return $this->fetch(['query' => 'pws:' . $id])->getResponseArray();
+	} // function
+
+
+	/**
+	 * Retrieves weather data by a (API internal) "city ID".
+	 *
+	 * @param string $code
+	 * @return array
+	 */
+	public function getByAirportCode ($code)
+	{
+		return $this->fetch(['query' => $code])->getResponseArray();
+	} // function
+
+
+	/**
+	 * Retrieves weather data by given coordinates.
+	 *
+	 * @param float $lat
+	 * @param float $lng
+	 * @return array
+	 */
+	public function getByCoordinates ($lat, $lng)
+	{
+		return $this->fetch(['query' => $lat . ',' . $lng])->getResponseArray();
+	} // function
+
+
+	/**
+	 * Retrieves weather data by given coordinates.
+	 *
+	 * @param string $city
+	 * @param string $country
+	 * @return array
+	 */
+	public function getByLocation ($city, $country)
+	{
+		return $this->fetch(['query' => $country . '/' . $city])->getResponseArray();
+	} // function
+} // class

src/Request.php

@@ -0,0 +1,208 @@
+<?php
+
+namespace lfischer\wunderground;
+
+/**
+ * API Request class.
+ *
+ * @author Leonard Fischer <[email protected]>
+ */
+class Request
+{
+	const URL = 'http://api.wunderground.com/api/:apiKey/:features/:settings/q/:query.json';
+
+	/**
+	 * @var string
+	 */
+	protected $apiKey = '';
+
+	/**
+	 * @var string
+	 */
+	protected $feature = 'conditions';
+
+	/**
+	 * @var string
+	 */
+	protected $settings = 'lang:EN';
+
+	/**
+	 * @var string
+	 */
+	protected $query = 'CA/San_Francisco';
+
+	/**
+	 * @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 $feature
+	 * @return $this
+	 */
+	public function setFeature ($feature)
+	{
+		$this->feature = $feature;
+
+		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:
+	 * - <US state>/<city>
+	 * - <US zipcode>/<city>
+	 * - <country>/<city>
+	 * - <latitude>,<longitude>
+	 * - <airport code>
+	 * - pws:<PWS id>
+	 * - autoip
+	 * - autoip.json?geo_ip=<IP address>
+	 *
+	 * @param string $query
+	 * @return $this
+	 */
+	public function setQuery ($query)
+	{
+		$this->query = $query;
+
+		return $this;
+	} // function
+
+
+	/**
+	 * API fetch method.
+	 *
+	 * @param array $parameters
+	 * @return $this
+	 */
+	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->feature,
+			':settings' => $this->settings,
+			':query' => $this->query
+		]);
+
+		$this->responseJSON = file_get_contents($url);
+		$this->responseArray = json_decode($this->response, true);
+
+		if (!is_array($this->responseArray))
+		{
+			// @todo  Throw exception.
+		} // if
+
+		if (!isset($this->responseArray['response']))
+		{
+			// @todo  Throw exception.
+		} // if
+
+		if (isset($this->responseArray['response']) && isset($this->responseArray['response']['error']))
+		{
+			// @todo  Throw exception.
+		} // 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
+} // class