/**
 *               _       _           
 *    __ _  __ _| |_ ___| |__   __ _ 
 *   / _` |/ _` | __/ __| '_ \ / _` |
 *  | (_| | (_| | || (__| | | | (_| |
 *   \__, |\__,_|\__\___|_| |_|\__,_|
 *    |___/    
 */
 
/** 
 * @copyright	Copyright 2010 Netlog NV
 * @link		http://www.gatcha.com/downloads/gatcha_api_clientlib_php
 * @license		http://www.apache.org/licenses/LICENSE-2.0.html
 * 
 */

//
// About this Library
//

This php library helps in accessing the Gatcha API. More information on 
http://www.gatcha.com/download/gatcha_api_clientlib_php.

//
// What's New?
//

See the "CHANGELOG" file for an overview of the history of this library

//
// Prerequisites
//

 - Gatcha API Account (http://www.gatcha.com)
 - PHP 5.2.1 or newer (http://www.php.net)
   This library uses, a.o., these php functionality
    - curl
    - json_decode() / json_encode()
    - md5()
    - optionally: debug_backtrace()

//
// Quick Start
//

This library comes with code samples for each available API method. To get 
started with the library, follow these steps:

 1. Obtain an application id (APP_ID) and application secret (APP_SECRET) to 
    access the Gatcha API. (http://www.gatcha.com)

 2. Extract the source zip file into a working directory or get the sources 
    form the subversion server.

 3. Edit the "configuration.inc.php" file. (See comments in that file for 
    further instructions. Use "configuration.inc.example.php" as a reference.)

 4. Create a class that implements the interface 
    Gatcha_Api_Tools_Debugging_ConsoleInterface (see 
    "/tools/debugging/class.gatcha_api_tools_debugging_consoleinterface.php") 
    and register it as Console Logging class by adding setting it in the 
    "configuration.inc.php" file.  

 5. Run the "gatcha.auth.getTicket" sample

        $ php samples/gatcha.auth.getticket.php

 6. You should see output that includes a string similar to the following:

        Your ticket is: pcer63bgv9rr13j7u0vorp0574
        
 7. The Gatcha_ApiClient is the main class of this library, this is the one
    you want to include in your project. From this class you can fetch a
    Gatcha, Container or Game API object.
    
     * Gatcha_ApiClient_Gatcha provides general functionality
     
     * Gatcha_ApiClient_Container provides functionality for site owners
       who want to integrate the Gatcha Platform in their website.
       More on http://www.gatcha.com/siteowners
       
     * Gatcha_ApiClient_Game provides functionality for Game Developers
       who want to use the Gatcha environment to enrich their game.
       More on http://www.gatcha.com/developers

 8. Experiment with the other samples. When ready, install the library in 
    your php include path, and start using if with the Gatcha_ApiClient
    as an entry point.

//
// Tips
//

 - To improve performance, fetch an API ticket only once, and store it
   eg. in your $_SESSION. You can pass a saved ticket as a paramater to the
   functions in the Gatcha_ApiClient class. 
   (If you get back an "invalid ticket" error, fetch a new one.)
   
 - Common API errors are documented here: 
   http://www.netlog.com/developers/apimethods/?view=errors

 - The class Gatcha_Api_Param holds a bunch of class constants you can use to 
   experiment with as function parameters, and avoid typos. 
   
 - Functions that return results other then single booleans or integers, mostly 
   return objects with documented getters for each object detail. This makes it
   easy for your IDE to display according documentation in order to understand
   the result you get back. 
   These objects also implement the ArrayAccess interface, so you can easily access 
   them as you would with normal arrays. 
   Result lists also implement the Iterator and Countable interfaces so you can 
   easily loop over them, as you would with normal arrays. 
   If you'd like to get these results as normal arrays, just call  the "toArray()" 
   function on any of these objects.
 
 - If you want to use this library for several of your Gatcha Applications, you 
   can specify the different APP_ID, APP_SECRET and APP_VERSION parameters as 
   constructor parameters of the Gatcha_Api_Container, Gatcha_Api_Game or 
   Gatcha_Api_Gatcha classes.
 
//
// Documentation
// 

 - Head over to http://www.gatcha.com for full API documentation. 
 
 - In the "/docs" folder of this library you get class and function documentation
   for the files in this library. This documentation is based on the inline phpDoc
   and generated by phpDoctor.

//
// Comments, Questions or Feedback
//

If you have any comments, questions or feedback on this library, please get 
in touch: http://www.gatcha.com/about

Happy coding!