pxWeather - Readme ================== A PHP class to retrieve, parse, and organize weather data for easy access. Version 0.1 ----------- http://pxweather.abbett.org/ Copyright (C) 2005 Jonathan M. Abbett This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2, as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Requirements: PHP 4.1.0 or later, installed with cURL support Summary: pxWeather gives you easy access to National Weather Service forecasts and current conditions for integration into your PHP application. To improve performance and decrease load on the data source, pxWeather can cache weather data locally. Download: The latest version will always be available at https://sourceforge.net/projects/pxweather/ Credits: Many thanks go to Hans Anderson for his XMLize utility, which makes short work of XML parsing. XMLize, which is included in this distribution, can be found at http://www.hansanderson.com/php/xml/ Installation: - Decompress your .zip or .tar.gz file. - Copy pxweather.inc.php to your PHP-enabled website. - If you use PHP5, copy xmlize-php5.inc.php to the same directory on your website. If you use PHP4, copy xmlize-php4.inc.php. - If you intend to use caching, create a new directory for cache files to live. Make sure it has proper read/write permissions set. (NOTE: by default, pxWeather will use the local subdirectory "cache" to read/write cache files. You may use pxWeather's setOption method to set a different directory.) Testing Your Installation: Test your installation with the following bit of code. This code assumes it's running in the same directory as pxweather/xmlize and that caching uses the default settings. load(); echo $w->getCurrent("temp.string"); ?> When you run it, you should see the current temperature for Boston, MA in degrees Farenheit and Celsius. Configuring pxWeather: All pxWeather configuration is done through the class constructor and the class's setOption method. The examples below assume you've already loaded pxweather.class.php, as above. To set a city other than Boston, MA, call the constructor with the $city variable set: Sometimes, two cities (i.e. Portland, ME and Portland, OR) have the same name. So, in any case where there might be ambiguity, consider using the ICAO location code for your city. The FAA maintains a list of codes for the USA at https://pilotweb.nas.faa.gov/qryhtml/icao/USA.html To force pxWeather to ignore its cache, and retrieve data directly from the source, you can call the constructor with the $force variable set to true: Other, less-common settings can be changed with the setOption method. For example, to disable caching: setOption("PXWEATHER_CACHE", false); ?> Four options may be set this way: PXWEATHER_URL (URL) The URL used to retrieve XML weather data. PXWEATHER_CACHE (true/false) Enable/disable caching; enabled by default. PXWEATHER_CACHEFOR (number) Number of minutes to keep cached data; 60 by default. PXWEATHER_CACHEAT (path) The directory where cache files should be stored; 'cache' by default. Accessing Data: pxWeather extracts four kinds of data from the XML feed: 1. Current conditions 2. Almanac times 3. Forecasts 4. Daycasts Current conditions can be retrieved with the getCurrent() method, which takes a field name as argument. The following are valid field names: FIELD NAME EXAMPLE VALUE ----------------- --------------------- city Boston, MA longname Boston, MA ident KBOS latitude 42.37 longitude -71.03 timezone -5 daylight_saving 1 night 0 weather_code PC observation_name KBOS (Boston, MA) time 5 PM EDT 24 JUN 05 temp.string 86 F (30 C) temp.F 86 temp.C 30 dewpt.string 53 F (11 C) dewpt.F 53 dewpt.C 11 rel_hum.string 32 % rel_hum.percent 32 wind.string SW at 17 knt wind_direct SW wind_speed.knt 17 heat_index.F 84 pressure.string 1016.7 mb (30.03 in) pressure.mb 1016.7 pressure.in 30.03 skies mostly cloudy text_weather haze The example from above: load(); echo $w->getCurrent('temp.string'); ?> Almanac times (sunrise, sunset) can be retrieved with the methods getSunrise() and getSunset(). They take no arguments, and return time strings in 12-hour format (i.e. 5:08 AM). Forecasts include a day name, a weather code, a low or high temperature, and a text description of the forecast. Forecasts for approximately the next six days and nights can be retrieved with the getForecasts() method, which takes no arguments. The method returns an array containing all forecasts. The example below cycles through each forecast, translates its weather code into a readable string with the weatherString() method, and prints high/low temperatures and text forecast. load(); echo "
";
            
            foreach($w->getForecasts() as $forecast)
            {
                echo "FORECAST FOR " . $forecast['day']. ":\n";
                echo $w->weatherString($forecast['weather']) . "\n";
            	
                if (isset($forecast['low_temp']))
                    echo "Low temperature: " . $forecast['low_temp'] . "\n";

                if (isset($forecast['high_temp']))
                    echo "High temperature: " . $forecast['high_temp'] . "\n";
            	    
                echo "Description: " . $forecast['text'] . "\n\n";
            	
            }
            
            echo "
"; ?> Daycasts are very similar to forecasts, but are not split into individual day and night reports and do not have text forecast descriptions. An example like above: load(); echo "
";
            
            foreach($w->getDaycasts() as $daycast)
            {
                echo "DAYCAST FOR " . $daycast['day']. ":\n";
                echo $w->weatherString($daycast['weather']) . "\n";

                if (isset($daycast['low_temp']))
                    echo "Low temperature: " . $daycast['low_temp'] . "\n";

                if (isset($daycast['high_temp']))
                    echo "High temperature: " . $daycast['high_temp'] . "\n\n";
            }
            
            echo "
"; ?> If you want to inspect the entire weather data structure, use the toString() method: load(); $w->toString(); ?> Feedback and Requests: SourceForge hosts a variety of forums to express your constructive feedback: - Feature Requests http://sourceforge.net/tracker/?atid=753105&group_id=142667 - Support Requests http://sourceforge.net/tracker/?atid=753103&group_id=142667 - Open Discussion http://sourceforge.net/forum/forum.php?forum_id=477711 All feedback and requests should be channeled through those outlets, and not sent by e-mail. Thank you for using pxWeather!