Added error handling and documentation, closes #1.

Author: cmfcmf

Examples.php

@@ -11,6 +11,7 @@
  * @see http://www.OpenWeatherMap.org
  * @see http://www.OpenWeatherMap.org/about
  * @see http://www.OpenWeatherMap.org/copyright
+ * @see http://openweathermap.org/appid
  */
 
 // Include api class
@@ -188,7 +189,37 @@
 echo OpenWeatherMap::getRawData('Berlin', $units, $lang, null, 'html');
 echo "<br />\n";
 
-// Example 14: Using an api key:
+// Example 14: Error handling.
+echo "<br /><br />\n\n\nEXAMPLE 14<hr />\n\n\n";
+
+// Try wrong city name.
+try {
+    $weather = OpenWeatherMap::getWeather("ThisCityNameIsNotValidAndDoesNotExist", $units, $lang);
+} catch(OpenWeatherMap_Exception $e) {
+    echo $e->getMessage() . ' (Code ' . $e->getCode() . ').';
+    echo "<br />\n";
+}
+
+// Try invalid $query.
+try {
+    $weather = OpenWeatherMap::getWeather(new DateTime('now'), $units, $lang);
+} catch(Exception $e) {
+    echo $e->getMessage() . ' (Code ' . $e->getCode() . ').';
+    echo "<br />\n";
+}
+
+// Full error handling would look like this:
+try {
+    $weather = OpenWeatherMap::getWeather(-1, $units, $lang);
+} catch(OpenWeatherMap_Exception $e) {
+    echo 'OpenWeatherMap exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
+    echo "<br />\n";
+} catch(Exception $e) {
+    echo 'General exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
+    echo "<br />\n";
+}
+
+// Example 15: Using an api key:
 
 # OpenWeatherMap::getWeather('Berlin', $units, $lang, 'Your-Api-Key-Here');
 # OpenWeatherMap::getRawData('Berlin', $units, $lang, 'Your-Api-Key-Here', 'json');

OpenWeatherMap.php

@@ -11,14 +11,58 @@
  * @see http://www.OpenWeatherMap.org
  * @see http://www.OpenWeatherMap.org/about
  * @see http://www.OpenWeatherMap.org/copyright
+ * @see http://openweathermap.org/appid
  */
 
 require_once('Util.php');
 
+/**
+ * Main static class for the OpenWeatherMap-PHP-API.
+ */
 class OpenWeatherMap
 {
+    /**
+     * @const $url The basic api url to fetch data from.
+     */
     const url = "http://api.openweathermap.org/data/2.5/weather?";
 
+    /**
+     * Directly returns the xml/json/html string returned by OpenWeatherMap.
+     *
+     * @param array|int|string $query The place to get weather information for. For possible values see below.
+     * @param string $units Can be either 'metric' or 'imperial' (default). This affects almost all units returned.
+     * @param string $lang The language to use for descriptions, default is 'en'. For possible values see below.
+     * @param string $appid Your app id, default ''. See http://openweathermap.org/appid for more details.
+     * @param string $mode The format of the data fetched. Possible values are 'json', 'html' and 'xml' (default).
+     *
+     * @return bool|string Returns false on failure and the fetched data in the format you specified on success.
+     *
+     * @warning If an error occured, OpenWeatherMap returns data in json format ALWAYS 
+     *
+     * There are three ways to specify the place to get weather information for:
+     * - Use the city name: $query must be a string containing the city name.
+     * - Use the city id: $query must be an integer containing the city id.
+     * - Use the coordinates: $query must be an associative array containing the 'lat' and 'lon' values.
+     *
+     * Available languages are (as of 17. July 2013):
+     * - English - en
+     * - Russian - ru
+     * - Italian - it
+     * - Spanish - sp
+     * - Ukrainian - ua
+     * - German - de
+     * - Portuguese - pt
+     * - Romanian - ro
+     * - Polish - pl
+     * - Finnish - fi
+     * - Dutch - nl
+     * - French - fr
+     * - Bulgarian - bg
+     * - Swedish - se
+     * - Chinese Traditional - zh_tw
+     * - Chinese Simplified - zh_cn
+     * - Turkish - tr
+     */
     static public function getRawData($query, $units = 'imperial', $lang = 'en', $appid = '', $mode = 'xml')
     {
         switch($query) {
@@ -45,6 +89,43 @@ static public function getRawData($query, $units = 'imperial', $lang = 'en', $ap
         return file_get_contents($url);
     }
 
+    /**
+     * Returns the current weather at the place you specified as an object.
+     *
+     * @param array|int|string $query The place to get weather information for. For possible values see below.
+     * @param string $units Can be either 'metric' or 'imperial' (default). This affects almost all units returned.
+     * @param string $lang The language to use for descriptions, default is 'en'. For possible values see below.
+     * @param string $appid Your app id, default ''. See http://openweathermap.org/appid for more details.
+     *
+     * @throws Exception If $query has a wrong format. For valid formats see below.
+     * @throws OpenWeatherMap_Exception If OpenWeatherMap returns an error.
+     *
+     * @return object Returns a new Weather object.
+     *
+     * There are three ways to specify the place to get weather information for:
+     * - Use the city name: $query must be a string containing the city name.
+     * - Use the city id: $query must be an integer containing the city id.
+     * - Use the coordinates: $query must be an associative array containing the 'lat' and 'lon' values.
+     *
+     * Available languages are (as of 17. July 2013):
+     * - English - en
+     * - Russian - ru
+     * - Italian - it
+     * - Spanish - sp
+     * - Ukrainian - ua
+     * - German - de
+     * - Portuguese - pt
+     * - Romanian - ro
+     * - Polish - pl
+     * - Finnish - fi
+     * - Dutch - nl
+     * - French - fr
+     * - Bulgarian - bg
+     * - Swedish - se
+     * - Chinese Traditional - zh_tw
+     * - Chinese Simplified - zh_cn
+     * - Turkish - tr
+     */
     static public function getWeather($query, $units = 'imperial', $lang = 'en', $appid = '')
     {
         return new Weather($query, $units, $lang, $appid);

README.md

@@ -4,6 +4,8 @@ An php api to parse weather data from [OpenWeatherMap.org](http://www.OpenWeathe
 
 If you are looking for an implementation for the [CMS Zikula](http://www.zikula.org), you may want to take a look at [cmfcmf/Weather](https://github.com/cmfcmf/Weather).
 
+For example code and how to use this api, please take a look into `Examples.php` or run it in your browser.
+
 **Notice:** This api is not made by OpenWeatherMap, nor their offical php api.
 
 License

Util.php

@@ -11,6 +11,7 @@
  * @see http://www.OpenWeatherMap.org
  * @see http://www.OpenWeatherMap.org/about
  * @see http://www.OpenWeatherMap.org/copyright
+ * @see http://openweathermap.org/appid
  */
 
 /**
@@ -46,7 +47,31 @@ class Weather
 
     public function __construct($query, $units = 'imperial', $lang = 'en', $appid = '')
     {
-        $xml = new SimpleXMLElement(OpenWeatherMap::getRawData($query, $units, $lang, $appid, 'xml'));
+        // Disable default error handling of SimpleXML (Do not throw E_WARNINGs).
+        libxml_use_internal_errors(true);
+        libxml_clear_errors();
+        
+        $answer = OpenWeatherMap::getRawData($query, $units, $lang, $appid, 'xml');
+        if ($answer === false) {
+            // $query has the wrong format, throw error.
+            throw new Exception('Error: $query has the wrong format. See the documentation of OpenWeatherMap::getRawData() to read about valid formats.');
+        }
+        
+        try {
+            $xml = new SimpleXMLElement($answer);
+        } catch(Exception $e) {
+            // Invalid xml format. This happens in case OpenWeatherMap returns an error.
+            // OpenWeatherMap always uses json for errors, even if one specifies xml as format.
+            $error = json_decode($answer, true);
+            if (isset($error['message'])) {
+                throw new OpenWeatherMap_Exception($error['message'], $error['cod']);
+            } else {
+                throw new OpenWeatherMap_Exception('Unknown fatal error: OpenWeatherMap returned the following json object: ' . print_r($error));
+            }
+        }
+        // Check for errors.
+        $errors = libxml_get_errors();
+        print_r($errors);
 
         $this->city = new _City($xml->city['id'], $xml->city['name'], $xml->city->coord['lon'], $xml->city->coord['lat'], $xml->city->country);
         $this->temperature = new _Temperature(new _Unit($xml->temperature['value'], $xml->temperature['unit']), new _Unit($xml->temperature['min'], $xml->temperature['unit']), new _Unit($xml->temperature['max'], $xml->temperature['unit']));
@@ -242,3 +267,8 @@ public function getIconUrl()
         return str_replace("%s", $this->icon, $this->iconUrl);
     }
 }
+
+class OpenWeatherMap_Exception extends Exception
+{
+
+}