Gatcha Api Client Library for PHP

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!