Geocache Class

This class is contained in the file Geocache.inc.php and encapsulates a single geocache. It uses the class Waypoint.inc.php internally which itself use the OCFParser.inc.php and db-mysql.inc.php internally.

Distance Calculations

GeoDistance

Context: Geocache

Used for short distances under a few kilometers
Please note that this does not keep the earth radius in mind and assumes that the earth is flat which is okay for small distances which normally are found between multiple locations in a multi- or puzzle cache.
This function returns the distance in kilometers or miles of both coordinates given.

Return value
Float

$lat1, $long1 define the geographic coordinates of the first location.
$lat2, $long2 define the geographic coordinates of the second location.
$unit can be either "k" for kilometers or "m" for miles.

Usage
$geocache->geoDistance($lat1, $long1, $lat2, $long2 [, $unit="k"])
Example
<?php
    echo $geocache->geoDistance(51.49648, 7.11382, 51.4897, 7.11254, "k")." km";
?>

0.759055276494 km


GreatCircleDistance

Context: Geocache

Used for larger distances

Return value
Float

$lat1, $long1 define the geographic coordinates of the first location.
$lat2, $long2 define the geographic coordinates of the second location.
$unit can be either "k" for kilometers or "m" for miles.


Usage
$geocache->greatCircleDistance($lat1, $long1, $lat2, $long2 [, $unit="k"])
Example
<?php
    echo $geocache->greatCircleDistance(51.49648, 7.11382, 51.4897, 7.11254)." km";
?>

0.758561474561 km


GetRealWaypoints

Context: Geocache

Returns all waypoints that are not parking waypoints
Only useful if used on multi- or puzzle caches.

Return value
Array of Geocache Waypoint objects.

Usage
$geocache->getRealWaypoints()
Example
<?php
    if($waypoints=$geocache->getRealWaypoints()) {
        foreach($waypoints AS $waypoint)
        {
            echo $waypoint->title."<br>";
        }
    }
?>

Puzzle #1
Puzzle #2
The Cache


GetLinearDistances

Context: Geocache

Returns the distances between all waypoints that are not parking waypoints
Only useful if used on multi- or puzzle caches.

Return value
Array of float values.

$unit can be either "k" for kilometers or "m" for miles.

Usage
$geocache->getLinearDistances([$unit="k"])
Example
<?php
    if($distances=$geocache->getLinearDistances("k")) {
        $c=0;
        foreach($distances AS $distance)
        {
            $c++;
            echo "The distance between waypoint #".$c." and #".($c+1)." is ".$distance." km<br>";
        }
    }
?>

The distance between waypoint #1 and #2 is 4.61511361456 km
The distance between waypoint #2 and #3 is 6.88085775201 km


GetHikeLength

Context: Geocache

Returns the complete length of the hike between all waypoints that are not parking waypoints
Only useful if used on multi- or puzzle caches.

Return value
Float value: distance in kilometers or miles.

$unit can be either "k" for kilometers or "m" for miles.

Usage
$geocache->getHikeLength([$unit="k"])
Example
<?php
    if($length=$geocache->getHikeLength("k")) {
        echo "The complete hike length is ".$length." km";
    }
?>

The complete hike length is 11.4959713666 km


File export

sendOCF

Context: Geocache

Prompts the user to download the OCF file containing the data of the given geocache.
This function send specific headers prompting the user to download the file instead of directly displaying it in the browser. The filename automatically used by the browser can be defined by the optional parameter.

Please note:
You must not output any characters before or after this functions is called so if your script does not have to do anything else after this function is called you can safely exit here.

Return value
none

$filename is the filename to be displayed as default value when the user downloads the file.

Usage
$phpgc->sendOCF([$filename="geocache.ocf"])
Example
<?php
    
    if($_REQUEST["dl_ocf"]) {
            $cache=$phpgc->getCacheByID(1);
            $cache->sendOCF();
            exit;
        }
?>

<form>
<input type="submit" name="dl_ocf" value="Download OCF">
</form>




sendKML

Context: Geocache

Prompts the user to download the KML file containing the data of the given geocache.
This function send specific headers prompting the user to download the file instead of directly displaying it in the browser. The filename automatically used by the browser can be defined by the optional parameter.
As the KML format does not support most of the geocache data the export only includes the name, title and the coordinates of the given geocache.

Further information:
The KML format ("Keyhole Markup Language") is the file format used by Google Earth. KML documentation

Please note:
You must not output any characters before or after this functions is called so if your script does not have to do anything else after this function is called you can safely exit here.

Return value
none

$filename is the filename to be displayed as default value when the user downloads the file.

Usage
$phpgc->sendKML([$filename="geocache.kml"])
Example
<?php
    
    if($_REQUEST["dl_kml"]) {
            $cache=$phpgc->getCacheByID(1);
            $cache->sendKML();
            exit;
        }
?>

<form>
<input type="submit" name="dl_kml" value="Download KML">
</form>




sendGPX

Context: Geocache

Prompts the user to download the GPX file containing the data of the given geocache.
This function send specific headers prompting the user to download the file instead of directly displaying it in the browser. The filename automatically used by the browser can be defined by the optional parameter.
As the GPX format does not support most of the geocache data the export only includes the name, title, url and the coordinates of the given geocache.

Further information:
The GPX format ("GPS Exchange Format") is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks) between applications and Web services on the Internet. GPX documentation

Please note:
You must not output any characters before or after this functions is called so if your script does not have to do anything else after this function is called you can safely exit here.

Return value
none

$filename is the filename to be displayed as default value when the user downloads the file.

Usage
$phpgc->sendGPX([$filename="geocache.gpx"])
Example
<?php
    
    if($_REQUEST["dl_gpx"]) {
            $cache=$phpgc->getCacheByID(1);
            $cache->sendGPX();
            exit;
        }
?>

<form>
<input type="submit" name="dl_gpx" value="Download GPX">
</form>




sendLOC

Context: Geocache

Prompts the user to download the LOC file containing the data of the given geocache.
This function send specific headers prompting the user to download the file instead of directly displaying it in the browser. The filename automatically used by the browser can be defined by the optional parameter.
As the LOC format does not support most of the geocache data the export only includes the name and the coordinates of the given geocache.

Further information:
The LOC format is the original download format for the search results page on Geocaching.com.

Please note:
You must not output any characters before or after this functions is called so if your script does not have to do anything else after this function is called you can safely exit here.

Return value
none

$filename is the filename to be displayed as default value when the user downloads the file.

Usage
$phpgc->sendLOC([$filename="geocache.loc"])
Example
<?php
    
    if($_REQUEST["dl_loc"]) {
            $cache=$phpgc->getCacheByID(1);
            $cache->sendLOC();
            exit;
        }
?>

<form>
<input type="submit" name="dl_loc" value="Download LOC">
</form>




getOCF

Context: Geocache

Creates OCF code containing all data of the given geocache
The OpenCacheFormat (OCF) is currently the only format that allows for the complete data of a single geocache to be exported and imported in XML.

Further information:
The OpenCacheFormat (OCF) is a completely free XML schema definition.
More information is available on the SourceForge.net project page.

Return value
String

Usage
$phpgc->getOCF()
Example
<?php
            $cache=$phpgc->getCacheByID(1);
            $code=$cache->getOCF();
            echo $code;
?>


<?xml version="1.0" encoding="iso-8859-1"?>
<ocf xmlns="http://opencacheformat.sourceforge.net/xsd/1.0">
<version>1.0</version>
<date>2006-05-29 17:39:15</date>
<caches>
<cache>
<srcid>1</srcid>
<name>GCVXFF</name>
<src>GEOCACHING.COM</src>
<lang>de</lang>
<owner>cscout</owner>
<placed>2006-05-07</placed>
<logurl>http://www.geocaching.com/seek/cache_details.aspx?guid=51b7aaa1-e879-42e5-b763-81c051bbba55</logurl>
<url>http://www.geocaching.com/seek/cache_details.aspx?guid=51b7aaa1-e879-42e5-b763-81c051bbba55</url>
<type>traditional</type>
<size>small</size>
<title>GCVXFF</title>
<country>de</country>
<state>nrw</state>
<city>Haltern am See</city>
<long>7.18574</long>
<lat>51.7064</lat>
<difficulty>2</difficulty>
<terrain>4</terrain>
<description><![CDATA[Der Cache befindet sich an einer Kreuzung von einigen Wegen mitten
im Wald. <br>Dieser Cache eignet sich auch gut in Verbindung mit <a href=
"http://www.geocaching.com/seek/cache_details.aspx?wp=gcvada"
target="_blank">Gotteshäuser: Heilig Kreuz - Haltern am See</a>.
<br>
<br>
Ich würde auf jeden Fall jedem den Spoiler empfehlen.]]></description>
<waypoints>
<waypoint>
<pointtype></pointtype>
<name></name>
<title></title>
<description></description>
<long></long>
<lat></lat>
</waypoint>
<waypoint>
<pointtype>cache</pointtype>
<name>FINAL</name>
<title>Der Cache</title>
<description>Hier befindet sich der Cache.</description>
<long>7.18573</long>
<lat>51.7064</lat>
</waypoint>
</waypoints>
<attributes>
<attribute name="wheelchair" value="1"/>
<attribute name="parking" value="1"/>
<attribute name="stroller" value="1"/>
<attribute name="stealth" value="1"/>
<attribute name="dogs" value="1"/>
<attribute name="bicycles" value="1"/>
<attribute name="horses" value="1"/>
<attribute name="kids" value="1"/>
<attribute name="short" value="1"/>
<attribute name="247" value="1"/>
</attributes>
</cache>
</caches>
</ocf>


getKML

Context: Geocache

Creates KML code containing data of the given geocache
As the KML format does not support most of the geocache data the export only includes the name, title and the coordinates of the given geocache.

Further information:
The KML format ("Keyhole Markup Language") is the file format used by Google Earth. KML documentation

Return value
String

Usage
$phpgc->getKML()
Example
<?php
            $cache=$phpgc->getCacheByID(1);
            $code=$cache->getKML();
            echo $code;
?>


<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.0">
<Placemark>
<description>Haardliner</description>
<name>GCVXFF</name>
<LookAt>
<longitude>7.18574</longitude>
<latitude>51.7064</latitude>
</LookAt>
<visibility>0</visibility>
<Point>
<altitudeMode>relativeToGround</altitudeMode>
<coordinates>7.18574,51.7064,50</coordinates>
</Point>
</Placemark>
</kml>


getGPX

Context: Geocache

Creates GPX code containing data of the given geocache
As the GPX format does not support most of the geocache data the export only includes the name, title, url and the coordinates of the given geocache.

Further information:
The GPX format ("GPS Exchange Format") is a light-weight XML data format for the interchange of GPS data (waypoints, routes, and tracks) between applications and Web services on the Internet. GPX documentation

Return value
String

Usage
$phpgc->getGPX()
Example
<?php
            $cache=$phpgc->getCacheByID(1);
            $code=$cache->getGPX();
            echo $code;
?>


<gpx version="1.1" creator="OCFConverter">
<metadata>
<desc>GCVXFF</desc>
<link href="http://www.geocaching.com/seek/cache_details.aspx?guid=51b7aaa1-e879-42e5-b763-81c051bbba55"/>
<keywords>geocache</keywords>
</metadata>
<wpt lat="51.7064" long="7.18574">
<name>GCVXFF</name>
<desc>Haardliner</desc>
<sym>GEOCACHE</sym>
<type>GEOCACHE</type>
</wpt>
</gpx>


getLOC

Context: Geocache

Creates LOC code containing data of the given geocache
As the LOC format does not support most of the geocache data the export only includes the name, title, url and the coordinates of the given geocache.

Further information:
The LOC format is the original download format for the search results page on Geocaching.com.

Return value
String

Usage
$phpgc->getLOC()
Example
<?php
            $cache=$phpgc->getCacheByID(1);
            $code=$cache->getLOC();
            echo $code;
?>


<?xml version="1.0" encoding="UTF-8"?>
<loc version="1.0" src="OCF">
<waypoint>
<name id="GCVXFF">Haardliner</name>
<coord lat="51.7064" lon="7.18574"/>
<type>Geocache</type>
<link text="Cache Details">http://www.geocaching.com/seek/cache_details.aspx?guid=51b7aaa1-e879-42e5-b763-81c051bbba55</link>
</waypoint>
</loc>
PHPGeocache - Geocaching with PHP