pxweather/README.txt

   1 pxWeather - Readme\r
   2 ==================\r
   3 \r
   4     A PHP class to retrieve, parse, and organize weather data for easy\r
   5     access.\r
   6         \r
   7     Version 0.1\r
   8     -----------\r
   9     http://pxweather.abbett.org/\r
  10     \r
  11         \r
  12         Copyright (C) 2005 Jonathan M. Abbett\r
  13                            <jonathan_at_abbett_dot_org>\r
  14                            \r
  15 \r
  16         This program is free software; you can redistribute it and/or modify \r
  17         it under the terms of the GNU General Public License version 2, as \r
  18         published by the Free Software Foundation.\r
  19 \r
  20         This program is distributed in the hope that it will be useful, but \r
  21         WITHOUT ANY WARRANTY; without even the implied warranty of \r
  22         MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU \r
  23         General Public License for more details.\r
  24 \r
  25         You should have received a copy of the GNU General Public License\r
  26         along with this program; if not, write to the Free Software\r
  27         Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307\r
  28         USA\r
  29     \r
  30     \r
  31     Requirements:\r
  32         PHP 4.1.0 or later, installed with cURL support\r
  33         \r
  34     \r
  35     Summary:\r
  36         pxWeather gives you easy access to National Weather Service forecasts\r
  37         and current conditions for integration into your PHP application. To\r
  38         improve performance and decrease load on the data source, pxWeather\r
  39         can cache weather data locally.\r
  40 \r
  41         \r
  42     Download:\r
  43         The latest version will always be available at\r
  44         https://sourceforge.net/projects/pxweather/\r
  45 \r
  46         \r
  47     Credits:\r
  48         Many thanks go to Hans Anderson for his XMLize utility, which makes\r
  49         short work of XML parsing.  XMLize, which is included in this \r
  50         distribution, can be found at http://www.hansanderson.com/php/xml/\r
  51 \r
  52         \r
  53     Installation:\r
  54         - Decompress your .zip or .tar.gz file.\r
  55         - Copy pxweather.inc.php to your PHP-enabled website.\r
  56         - If you use PHP5, copy xmlize-php5.inc.php to the same directory\r
  57           on your website.  If you use PHP4, copy xmlize-php4.inc.php.\r
  58         - If you intend to use caching, create a new directory for cache\r
  59           files to live.  Make sure it has proper read/write permissions set.\r
  60 \r
  61           (NOTE: by default, pxWeather will use the local subdirectory \r
  62           "cache" to read/write cache files. You may use pxWeather's\r
  63           setOption method to set a different directory.)\r
  64 \r
  65 \r
  66     Testing Your Installation:\r
  67         Test your installation with the following bit of code.  This code\r
  68         assumes it's running in the same directory as pxweather/xmlize and\r
  69         that caching uses the default settings.\r
  70         \r
  71         <?php\r
  72         \r
  73             require_once("pxweather.class.php");\r
  74             $w = new Weather();\r
  75             $w->load();\r
  76             echo $w->getCurrent("temp.string");\r
  77         \r
  78         ?>\r
  79         \r
  80         When you run it, you should see the current temperature for\r
  81         Boston, MA in degrees Farenheit and Celsius.\r
  82 \r
  83         \r
  84     Configuring pxWeather:\r
  85         All pxWeather configuration is done through the class constructor\r
  86         and the class's setOption method.  The examples below assume you've\r
  87         already loaded pxweather.class.php, as above.\r
  88         \r
  89         To set a city other than Boston, MA, call the constructor with the\r
  90         $city variable set:\r
  91         \r
  92         <?php\r
  93         \r
  94             $w = new Weather($city = "Miami");\r
  95         \r
  96         ?>\r
  97         \r
  98         Sometimes, two cities (i.e. Portland, ME and Portland, OR) have the\r
  99         same name.  So, in any case where there might be ambiguity, consider\r
 100         using the ICAO location code for your city.  The FAA maintains a \r
 101         list of codes for the USA at\r
 102         https://pilotweb.nas.faa.gov/qryhtml/icao/USA.html\r
 103         \r
 104         <?php\r
 105         \r
 106             // Portland, OR\r
 107             $w = new Weather($city = "KPDX");\r
 108             \r
 109             // Portland, ME\r
 110             $w = new Weather($city = "KPWM");\r
 111             \r
 112         ?>\r
 113         \r
 114         To force pxWeather to ignore its cache, and retrieve data directly\r
 115         from the source, you can call the constructor with the $force \r
 116         variable set to true:\r
 117         \r
 118         <?php\r
 119         \r
 120             $w = new Weather($city = "Austin", $force = true);\r
 121             \r
 122         ?>\r
 123         \r
 124         Other, less-common settings can be changed with the setOption method.\r
 125         For example, to disable caching:\r
 126         \r
 127         <?php\r
 128         \r
 129             $w = new Weather();\r
 130             $w->setOption("PXWEATHER_CACHE", false);\r
 131             \r
 132         ?>\r
 133         \r
 134         Four options may be set this way:\r
 135         \r
 136             PXWEATHER_URL         (URL)\r
 137             The URL used to retrieve XML weather data.\r
 138 \r
 139             PXWEATHER_CACHE       (true/false)\r
 140             Enable/disable caching; enabled by default.\r
 141 \r
 142             PXWEATHER_CACHEFOR    (number)\r
 143             Number of minutes to keep cached data; 60 by default.\r
 144 \r
 145             PXWEATHER_CACHEAT     (path)\r
 146             The directory where cache files should be stored; 'cache' by\r
 147             default.\r
 148 \r
 149             \r
 150     Accessing Data:\r
 151         pxWeather extracts four kinds of data from the XML feed:\r
 152         \r
 153             1. Current conditions\r
 154             2. Almanac times\r
 155             3. Forecasts\r
 156             4. Daycasts\r
 157         \r
 158         Current conditions can be retrieved with the getCurrent()\r
 159         method, which takes a field name as argument.  The following are\r
 160         valid field names:\r
 161         \r
 162             FIELD NAME         EXAMPLE VALUE\r
 163             -----------------  ---------------------\r
 164             city               Boston, MA\r
 165             longname           Boston, MA\r
 166             ident              KBOS\r
 167             latitude           42.37\r
 168             longitude          -71.03\r
 169             timezone           -5\r
 170             daylight_saving    1\r
 171             night              0\r
 172             weather_code       PC\r
 173             observation_name   KBOS (Boston, MA)\r
 174             time               5 PM EDT 24 JUN 05\r
 175             temp.string        86 F (30 C)\r
 176             temp.F             86\r
 177             temp.C             30\r
 178             dewpt.string       53 F (11 C)\r
 179             dewpt.F            53\r
 180             dewpt.C            11\r
 181             rel_hum.string     32 %\r
 182             rel_hum.percent    32\r
 183             wind.string        SW at 17 knt\r
 184             wind_direct        SW\r
 185             wind_speed.knt     17\r
 186             heat_index.F       84\r
 187             pressure.string    1016.7 mb (30.03 in)\r
 188             pressure.mb        1016.7\r
 189             pressure.in        30.03\r
 190             skies              mostly cloudy\r
 191             text_weather       haze\r
 192             \r
 193         The example from above:\r
 194         \r
 195         <?php\r
 196         \r
 197             require_once("pxweather.class.php");\r
 198             $w = new Weather();\r
 199             $w->load();\r
 200             echo $w->getCurrent('temp.string');\r
 201         \r
 202         ?>\r
 203         \r
 204         Almanac times (sunrise, sunset) can be retrieved with the methods\r
 205         getSunrise() and getSunset().  They take no arguments, and return\r
 206         time strings in 12-hour format (i.e. 5:08 AM).\r
 207         \r
 208         Forecasts include a day name, a weather code, a low or high\r
 209         temperature, and a text description of the forecast.  Forecasts for\r
 210         approximately the next six days and nights can be retrieved with the\r
 211         getForecasts() method, which takes no arguments.  The method returns\r
 212         an array containing all forecasts.  The example below cycles through\r
 213         each forecast, translates its weather code into a readable string\r
 214         with the weatherString() method, and prints high/low temperatures\r
 215         and text forecast.\r
 216         \r
 217         <?php\r
 218         \r
 219             require_once("pxweather.class.php");\r
 220             $w = new Weather();\r
 221             $w->load();\r
 222             \r
 223             echo "<pre>";\r
 224             \r
 225             foreach($w->getForecasts() as $forecast)\r
 226             {\r
 227                 echo "FORECAST FOR " . $forecast['day']. ":\n";\r
 228                 echo $w->weatherString($forecast['weather']) . "\n";\r
 229                 \r
 230                 if (isset($forecast['low_temp']))\r
 231                     echo "Low temperature: " . $forecast['low_temp'] . "\n";\r
 232 \r
 233                 if (isset($forecast['high_temp']))\r
 234                     echo "High temperature: " . $forecast['high_temp'] . "\n";\r
 235                     \r
 236                 echo "Description: " . $forecast['text'] . "\n\n";\r
 237                 \r
 238             }\r
 239             \r
 240             echo "</pre>";\r
 241         \r
 242         ?>\r
 243         \r
 244         Daycasts are very similar to forecasts, but are not split into \r
 245         individual day and night reports and do not have text forecast\r
 246         descriptions.  An example like above:\r
 247         \r
 248         <?php\r
 249 \r
 250             require_once("pxweather.class.php");\r
 251             $w = new Weather();\r
 252             $w->load();\r
 253             \r
 254             echo "<pre>";\r
 255             \r
 256             foreach($w->getDaycasts() as $daycast)\r
 257             {\r
 258                 echo "DAYCAST FOR " . $daycast['day']. ":\n";\r
 259                 echo $w->weatherString($daycast['weather']) . "\n";\r
 260 \r
 261                 if (isset($daycast['low_temp']))\r
 262                     echo "Low temperature: " . $daycast['low_temp'] . "\n";\r
 263 \r
 264                 if (isset($daycast['high_temp']))\r
 265                     echo "High temperature: " . $daycast['high_temp'] . "\n\n";\r
 266             }\r
 267             \r
 268             echo "</pre>";\r
 269         \r
 270 \r
 271         ?>\r
 272         \r
 273         If you want to inspect the entire weather data structure, use the \r
 274         toString() method:\r
 275         \r
 276         <?php\r
 277         \r
 278             require_once("pxweather.class.php");\r
 279             $w = new Weather();\r
 280             $w->load();\r
 281             \r
 282             $w->toString();\r
 283         \r
 284         ?>\r
 285 \r
 286         \r
 287     Feedback and Requests:\r
 288         SourceForge hosts a variety of forums to express your constructive\r
 289         feedback:\r
 290         \r
 291             - Feature Requests\r
 292             http://sourceforge.net/tracker/?atid=753105&group_id=142667\r
 293             - Support Requests\r
 294             http://sourceforge.net/tracker/?atid=753103&group_id=142667\r
 295             - Open Discussion\r
 296             http://sourceforge.net/forum/forum.php?forum_id=477711\r
 297             \r
 298         All feedback and requests should be channeled through those outlets,\r
 299         and not sent by e-mail.\r
 300         \r
 301         \r
 302     Thank you for using pxWeather!\r