Understanding API Classes
Agile Toolkit does not use any static elements or global variables. The only global variable you use in the "index.php" class is "$api". All additional classes are added into your API, or into other objects inside the API.
This leads to several interesting points:
- You can have more than one API running at the same time;
- APIs are independent, and will never share same ID, Cookie name or session name;
- You can create one API from inside another one, but the latter won't be able to access the former;
Controllers versus Singletons
Agile Toolkit does not use singletons. Singletons do not provide any performance or persistence benefits in PHP5.2 or higher. Instead, Agile Toolkit has the concept of "Controllers". A controller can be added into an object, but a controller of a certain type can only be added to a certain object once. This is a "soft" restriction: you can still add second controller of same type to the same object at your own risk, if you specify a different name for it.
For example: you can add a "Logger" controller into the API, which enhances the way errors are displayed. Adding another Logger into the API again will do nothing, and will simply return a reference to your existing Logger.
Because it's possible to have multiple APIs at the same time, this opens up new strategies for testing. For instance, a 'testing' API can initialize your 'real' API. Before executing a test, the 'test' API can destroy() some of the controllers in the 'real' API, and replace them with new ones. This implements a dependency-injection based testing framework, which is really close to the real-life environment of your application.
When the API class is initialized it expects only one argument: the "realm". A Realm must be unique to an application or even to an installation. The realm becomes the "name" of your $api, and it will also be used in all unique IDs (cookies, DOM id's, session variables).
Through combining the concept of multiple APIs with proper realms, you can implement some unique features - such as a "Login As User" feature, by actually using the frontend API and calling the "login" method of its auth object.