Class: Geocache

Source Location: /Geocache.inc.php

Class Details

[line 48]
Defines the Geocache class.

Class Variables

$attributes =

[line 297]

An array of attribute values as an associative array.

Each value is either -1, 0 or 1, depending on whether the values does specifically not apply (-1) does neither apply nor not apply specifically (0) or apply specifically (1). A list of possible values is listed at the ocfAttributes attribute.

A complete list of available attributes with descriptions is available here: http://opencacheformat.sourceforge.net/ocf-tags.php

Tags:

link:	http://opencacheformat.sourceforge.net/ocf-tags.php
see:	Geocache::$ocfAttributes
since:	1.0
access:	public

Type:

array

[ Top ]

$city =

[line 190]

The name of the city where the cache is located. Normal capitalization is used here,

e.g. "Philadelphia" or "Gelsenkirchen"

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$country =

[line 171]

The country where the cache can be found in the two-letter-format as defined by ISO 3166-1-alpha-2, e.g. "us" for the United States, "de" for Germany, "fr" for France and so on.

Tags:

link:	http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/index.html
since:	1.0
access:	public

Type:

string

[ Top ]

$description =

[line 271]

A short textual description of the cache and further information on the surroundings if available.

If this cache is a multi-stage cache each single waypoint SHOULD be listed ONLY as a separate waypoint and NOT be listed in the description. However as most websites do not yet have this separation it is acceptable until this separation is fully implemented to list the full description here.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$difficulty =

[line 247]

This is an integer value between 1 and 10 indicating the difficulty of the complete hike, i.e. how easy it is to find the cache.

Tags:

since:	1.0
access:	public

Type:

integer

[ Top ]

$duration =

[line 237]

The _estimated_ duration of the complete hike in minutes.

This value is only set if the cache has different stations (multi cache etc.).

Tags:

since:	1.0
access:	public

Type:

integer

[ Top ]

$fields = array('srcid', 'name', 'src', 'lang', 'owner', 'placed', 'homepage', 'logurl', 'url', 'type', 'size', 'title', 'country', 'state', 'city', 'long', 'lat', 'length', 'duration', 'difficulty', 'terrain', 'description', 'waypoints', 'attributes')

[line 316]

Defines all fields given here for data import functions.

Tags:

since:	1.0
access:	public

Type:

array

[ Top ]

$homepage =

[line 115]

The URL of the cache homepage. This field is mostly empty unless someone has created a specific website just for this cache or a cache series. This might happen if it is an event cache. Please note: this is _not_ the URL of the website where the data was obtained from.

Tags:

see:	Geocache::$url
since:	1.0
access:	public

Type:

string

[ Top ]

$lang =

[line 83]

The ISO 639-1 code of the language of the description of the geocache and all additional texts, e.g. "en" for English and "de" for German.

http://en.wikipedia.org/wiki/ISO_639-1 contains more information.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$lastError =

[line 336]

Contains a textual description of the last error that occured.

Read-only value.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$lat =

[line 214]

The latitude in decimal form of the cache location to be displayed, e.g. 51.7064.

This location may differ from the real location if the cache is a puzzle-/mystery cache, a multi cache or something similar. The coordinates given here are the ones to be displayed to the end user.

Tags:

see:	Geocache::$long
since:	1.0
access:	public

Type:

float

[ Top ]

$length =

[line 227]

The complete hike length in meters (not in miles). To convert miles to kilometers you simply have to multiply the miles by 1.609344.

This value is only set if the cache has different stations (multi cache etc.). It only defines the sum of each way from one station to the next _excluding_ the way from a parking location to the first station.

Tags:

since:	1.0
access:	public

Type:

integer

[ Top ]

$logurl =

[line 125]

The URL where the log for this geocache can be accessed.

On most websites this is the same as the $url field.

Tags:

see:	Geocache::$url
since:	1.0
access:	public

Type:

string

[ Top ]

$long =

[line 202]

The longitude in decimal form of the cache location to be displayed, e.g. 7.18574.

This location may differ from the real location if the cache is a puzzle-/mystery cache, a multi cache or something similar. The coordinates given here are the ones to be displayed to the end user.

Tags:

see:	Geocache::$lat
since:	1.0
access:	public

Type:

float

[ Top ]

$name =

[line 65]

The unique name of the cache. This is a string with a length of max. 6 characters.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$ocfAttributes = array('wheelchair', 'camping', 'parking', 'publictransport', 'picnictables', 'drinkingwater', 'restrooms', 'telephone', 'stroller', 'museum', 'restaurant', 'night', 'winter', 'scenic','stealth', 'rocks', 'hunting', 'danger', 'plants', 'thorns', 'snakes', 'ticks', 'mine', 'dogs', 'bicycles', 'motorcycles','quads', 'offroad', 'snowmobiles', 'campfires', 'horses', 'fee', 'climbing', 'boat', 'scuba', 'kids', 'short', 'hike', 'wading', 'swimming', '247')

[line 326]

Defines all attributes of the OpenCacheFormat.

A complete list of available attributes with descriptions is available here: http://opencacheformat.sourceforge.net/ocf-tags.php

Tags:

since:	1.0
access:	public

Type:

array

[ Top ]

$owner =

[line 93]

The name of the owner of the cache. This _must_ be the name of the registered user on the website from which the cache information was obtained which is listed as the owner on the corresponding page.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$placed =

[line 104]

The date when the cache was placed as UNIX timestamp.

Please note that the value normally only contains a date with the time set to 00:00:00. All date values are GMT/UTC.

Tags:

todo:	Correctly convert the $placed value to a timestamp when reading it from the database via the PHPGeocache class
since:	1.0
access:	public

Type:

integer

[ Top ]

$size =

[line 153]

The size of the cache. This string must be in lower case and may only be one the the following:

micro | small | medium | large

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$src =

[line 73]

The source where this geocache was obtained from, e.g. "OPENCACHING.DE"

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$srcid =

[line 57]

The source ID of the geocache. If used in conjunction with the PHPGeocache class the srcid will always be the autoincrement value of the caches table - the field "cache_id".

Tags:

since:	1.0
access:	public

Type:

integer

[ Top ]

$state =

[line 181]

The name of the state in the locally defined short form, i.e. in the US it is a two-letter-code like "va" for Virginia, "ny" for "New York" and so on.

In Germany this is a three-letter code, e.g. "nrw" for North Rhine Westphalia and so on.

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$targetDistance =

[line 307]

This value is only set from other external functions.

It contains the distance of this cache to a given location in kilometers.

Tags:

since:	1.0
access:	public

Type:

float

[ Top ]

$terrain =

[line 259]

This is an integer value between 1 and 10 indicating the difficulty of the complete hike, i.e. how easy it is to reach the cache. On the website http://www.clayjar.com/gcrs/ you can calculate the difficulty, but please note that the value here has a maximum value of 10.

Tags:

link:	http://www.clayjar.com/gcrs/
since:	1.0
access:	public

Type:

integer

[ Top ]

$title =

[line 161]

The title of the cache. This is normally referred to as "the name of the cache".

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$type =

[line 144]

The type of the cache. This string must be in lower case and may only be one the the following:

traditional | multi | puzzle | event | letterbox

Tags:

since:	1.0
access:	public

Type:

string

[ Top ]

$url =

[line 135]

The URL where this geocache is listed. This URL should link directly to the page of the cache, not to the homepage of that website.

Tags:

see:	Geocache::$homepage
since:	1.0
access:	public

Type:

string

[ Top ]

$waypoints =

[line 280]

An array of Waypoint objects. Each entry is an instantiation of the Waypoint class.

Tags:

since:	1.0
access:	public

Type:

array

[ Top ]

Class Methods

constructor __construct [line 350]

Geocache __construct(
)

The PHP5 constructor

Tags:

since:

1.0

[ Top ]

constructor Geocache [line 343]

Geocache Geocache(
)

The PHP4 constructor

Tags:

since:

1.0

[ Top ]

method free [line 359]

void free(
)

Cleanup function which clears all values of this object.

This is useful for recycling this object.

Tags:

since:

1.0

[ Top ]

method geoDistance [line 1039]

float geoDistance(
float
$lat1, float
$lon1, float
$lat2, float
$lon2, [string
$unit = "k"])

Calculates the distance between two coordinates for distances under a few kilometers.

If the distances are higher you should use greatCircleDistance()

Tags:

see:	Geocache::greatCircleDistance()
since:	1.0

Parameters:

float	$lat1	The latitude of the first location
float	$lon1	The longitude of the first location
float	$lat2	The latitude of the second location
float	$lon2	The longitude of the second location
string	$unit	The unit the distance to be returned in, either "k" for kilometers or "m" for miles

[ Top ]

method getGPX [line 640]

string|bool getGPX(
[bool
$insertAllWaypoints = false])

If this object has at least a name, title, longitude and latitude set this function can return GPX code ("GPS Exchange Format") for this cache. This format is used by many programs working with GPS data.

Tags:

link:	http://www.topografix.com/gpx.asp
since:	1.0

Parameters:

bool

$insertAllWaypoints

Whether all waypoints of this cache should be included as waypoints in the GPX code. Please note that this would also include hidden coordinates of caches not to be displayed directly (puzzle cache/multi cache).

[ Top ]

method getHikeLength [line 1177]

float getHikeLength(
[string
$unit = "k"])

Returns the length of the complete hike in kilometers by adding the distances of each route from one waypoint to the next.

Tags:

see:	Geocache::getRealWaypoints()
since:	1.0

Parameters:

string

$unit

The unit the distance to be returned in, either "k" for kilometers or "m" for miles

[ Top ]

method getKML [line 695]

string|bool getKML(
[integer
$height = 50])

If this object has at least a name, title, longitude and latitude set this function can return KML code ("Keyhole Markup Language") for this cache. This format is used by Google Earth.

Tags:

link:	http://keyhole.com/kml/kml_doc.html
link:	http://earth.google.com
since:	1.0

Parameters:

integer

$height

The height in meters above the coordinates of this object to be displayed in Google Earth.

[ Top ]

method getLinearDistances [line 1130]

array|bool getLinearDistances(
[string
$unit = "k"])

Returns the distances of each single route between one waypoint and the next excluding parking waypoints.

This is only useful if the cache is a multi-stage cache (multi cache, puzzle cache etc.) Returns an array of float values (distances in kilometers).

Tags:

see:	Geocache::getRealWaypoints()
since:	1.0

Parameters:

string

$unit

The unit the distance to be returned in, either "k" for kilometers or "m" for miles

[ Top ]

method getLOC [line 731]

string|bool getLOC(
)

If this object has at least a name, title, url, longitude and latitude set this function can return LOC code for this cache. This format is used mainly on Geocaching.com.

Tags:

since:

1.0

[ Top ]

method getOCF [line 765]

string getOCF(
[string
$encoding = 'iso-8859-1'], [mixed
$lbr = "\n"], [bool
$stripNullAttributes = true])

This function returns OCF code ("OpenCacheFormat") for this cache.

The OCF format can include _all_ information of this object - including descriptions, waypoints etc. More information can be found at http://opencacheformat.sourceforge.net

Tags:

link:	http://opencacheformat.sourceforge.net
since:	1.0

Parameters:

string	$encoding	The encoding to be inserted into the file. Please note that this method does not automatically convert different encodings. This is your task.
bool	$stripNullAttributes	Defaults to true. If set to true all attributes with a value of 0 (default) will be stripped from the OCF code to save some space.

[ Top ]

method getRealWaypoints [line 1101]

array|bool getRealWaypoints(
)

Returns an array of all waypoints of this geocache which are not parking waypoints.

Tags:

see:	Geocache::getLinearDistances()
since:	1.0

[ Top ]

method greatCircleDistance [line 1069]

float greatCircleDistance(
float
$lat1, float
$lon1, float
$lat2, float
$lon2, [string
$unit = "k"])

Calculates the distance between two coordinates for distances greater than a few kilometers.

If the distances are lower you should use geoDistance() as it consumes less computing power.

Tags:

see:	Geocache::geoDistance()
since:	1.0

Parameters:

float	$lat1	The latitude of the first location
float	$lon1	The longitude of the first location
float	$lat2	The latitude of the second location
float	$lon2	The longitude of the second location
string	$unit	The unit the distance to be returned in, either "k" for kilometers or "m" for miles

[ Top ]

method loadCacheFromOCF [line 380]

bool loadCacheFromOCF(
string
$xmlFile, [integer
$cacheToLoad = 0])

Loads a single cache from an OCF file and parses the content into this object.

Returns true on success, false otherwise. Uses the OCFParser class included. Please note that an OCF file can contain an unlimited number of geocaches so you must explicitly give the number of the cache to be loaded into this object by giving the appropriate $cacheToLoad value.

Tags:

since:

1.0

Parameters:

string	$xmlFile
integer	$cacheToLoad

[ Top ]

method sendGPX [line 926]

bool sendGPX(
[string
$filename = "geocache.gpx"])

Sends the data of this object as a GPX file with the corresponding MIME type directly to the user�s browser prompting him to download the file.

Please note: Before and after calling this function no single bytes must have been sent to the user�s browser!

Tags:

see:	Geocache::getGPX()
since:	1.0

Parameters:

string

$filename

The filename to be shown to the user in the download prompt.

[ Top ]

method sendKML [line 947]

bool sendKML(
[string
$filename = "geocache.kml"])

Sends the data of this object as a KML file with the corresponding MIME type directly to the user�s browser prompting him to download the file.

Please note: Before and after calling this function no single bytes must have been sent to the user�s browser!

Tags:

see:	Geocache::getKML()
since:	1.0

Parameters:

string

$filename

The filename to be shown to the user in the download prompt.

[ Top ]

method sendLOC [line 905]

bool sendLOC(
[string
$filename = "geocache.loc"])

Sends the data of this object as a LOC file with the corresponding MIME type directly to the user�s browser prompting him to download the file.

Please note: Before and after calling this function no single bytes must have been sent to the user�s browser!

Tags:

see:	Geocache::getLOC()
since:	1.0

Parameters:

string

$filename

The filename to be shown to the user in the download prompt.

[ Top ]

method sendOCF [line 968]

bool sendOCF(
[string
$filename = "geocache.ocf"])

Sends the data of this object as a OCF file with the corresponding MIME type directly to the user�s browser prompting him to download the file.

Please note: Before and after calling this function no single bytes must have been sent to the user�s browser!

Tags:

see:	Geocache::getOCF()
since:	1.0

Parameters:

string

$filename

The filename to be shown to the user in the download prompt.

[ Top ]

method xmlPrep [line 1003]

string xmlPrep(
string
$str)

Automatically inserts the sring given in CDATA tags if it contains otherwise forbidden characters.

Tags:

since:

1.0

Parameters:

string

$str

[ Top ]

Documentation generated on Mon, 29 May 2006 19:21:40 +0200 by phpDocumentor 1.3.0RC6

Class: Geocache

Class Overview

Variables

Methods

Class Details

Class Variables

$attributes =

Tags:

$city =

Tags:

$country =

Tags:

$description =

Tags:

$difficulty =

Tags:

$duration =

Tags:

$fields = array('srcid', 'name', 'src', 'lang', 'owner', 'placed', 'homepage', 'logurl', 'url', 'type', 'size', 'title', 'country', 'state', 'city', 'long', 'lat', 'length', 'duration', 'difficulty', 'terrain', 'description', 'waypoints', 'attributes')

Tags:

$homepage =

Tags:

$lang =

Tags:

$lastError =

Tags:

$lat =

Tags:

$length =

Tags:

$logurl =

Tags:

$long =

Tags:

$name =

Tags:

Tags:

$owner =

Tags:

$placed =

Tags:

$size =

Tags:

$src =

Tags:

$srcid =

Tags:

$state =

Tags:

$targetDistance =

Tags:

$terrain =

Tags:

$title =

Tags:

$type =

Tags:

$url =

Tags:

$waypoints =

Tags:

Class Methods

constructor __construct [line 350]

Tags:

constructor Geocache [line 343]

Tags:

method free [line 359]

Tags:

method geoDistance [line 1039]

Tags:

Parameters:

method getGPX [line 640]

Tags:

Parameters:

method getHikeLength [line 1177]

Tags:

Parameters:

method getKML [line 695]

Tags:

Parameters: