Documentation: Using PHPGeocache

Welcome to the documentation for PHPGeocache. This page lists all available methods of the different classes this package is comprised of together with a simple example showing how to use it.

PHPGeocache has been specifically designed to be as independent as possible which means that it does not require any special libaries or PEAR packages with one exception: to use the OCFParser included you must either have the domxml extension in PHP4 or simplexml in PHP5 compiled in.
If you do not have any of the required extensions installed you can simply not use the OCFParser, everything else (including exporting OCF data) works without any problems.


1. Installing PHPGeocache

After downloading the latest version simply extract the directory PHPGeocache contained into your document root or into a directory included in the include_path.

This is how your document root may look before
[htdocs]
|- [images]
|- [scripts]
|- [includes]
...

Extract the file so that the directory PHPGeocache with all files and directories contained therein is placed under the document root.

This is how your document root may look after unpacking the content
[htdocs]
|- [images]
|- [scripts]
|- [includes]
|- [PHPGeocache]
   |--- PHPGeocache.inc.php
   |--- Geocache.inc.php
   |--- Waypoint.inc.php
   |--- OCFParser.inc.php
   |--- db-mysql.inc.php
   |--- [demo]
   |--- [sql]
...


2. Database Setup

PHPGeocache currently support MySQL only, however an adaption to other databases should be quite simple. You can also use PHPGeocache if you do not have a database by using only the classes Geocache and Waypoint. To use the database functions you first have to setup the database.
  1. Create a new database named phpgeocache on your MySQL server. You can also choose a different name as PHPGeocache does not require the database to have that name.
  2. Execute the SQL statements found in the demo directory of the PHPGeocache distribution: caches.sql and waypoints.sql. This will create the required tables.
  3. You can create a specific user to access the phpgeocache database if you wish to do so.

3. Using PHPGeocache

PHPGeocache contains of several classes most of which can also be used without any of the others. Here is a quick information on the files and their implied use.
  • PHPGeocache.inc.php
    This class contains most of the functions used for handling geocaches and adding and retieving data to and from the database although the database functions are encapsulated in the db-mysql.inc.php to separate the database functions from the main code.
  • Geocache.inc.php
    This class encapsulates a single geocache with its attributes and methods.
  • Waypoint.inc.php
    This class encapsulates a single waypoint.
  • OCFParser.inc.php
    Parses geocache data in the OpenCacheFormat and returns it as an array.
  • db-mysql.inc.php
    MySQL database functions.
After extracting PHPGeocache you can simply use it as follows:
Example
<?php

   define("PHPGEOCACHE_DB_TYPE", "mysql");
   define("PHPGEOCACHE_DB_SERVER", "localhost");
   define("PHPGEOCACHE_DB_DB", "phpgeocache");
   define("PHPGEOCACHE_DB_USER", "root");
   define("PHPGEOCACHE_DB_PASSWORD", "");
   require_once "PHPGeocache/PHPGeocache.inc.php";

   $phpgc=&new PHPGeocache();
   $cache=$phpgc->getCacheByID(1);
   echo $cache->name." ".$cache->title;
?>

As stated before currently only MySQL is supported so setting the PHPGEOCACHE_DB_TYPE to anything else than MySQL will not work. If you wish to support other databases you simply have to create a new file named "db-$DBTYPE.inc.php" in the PHPGeocache directory where $DBTYPE is the value of PHPGEOCACHE_DB_TYPE you would like to use. If you would like to use SQLite your file would probably be named "db-sqlite.inc.php". You then have to define a class named GeocacheDB in the file containing all the functions listed in db-mysql.inc.php with their correct implementation to be used for that specific database.

Classes and Objects

The PHPGeocache class implements several functions regarding geocache handling. The Geocache class simply encapsulates a single geocache and is used by the PHPGeocache class internally. The Waypoint class is used by the Geocache class internally and represents a single waypoint.


PHPGeocache - Geocaching with PHP