API

Let your add-on talk to other add-ons, as well as your add-on talking to them.

Add-ons can define an API for use inside of other add-ons. This means that add-ons don’t need to be their own little walled-garden, but can do complex tasks and share data with those that desire it.

Creating an API works the same as adding any other aspect to your add-on. Let’s say you have created a karma add-on. This add-on provides ways for other add-ons to increase or decrease the current member’s karma total, as well as a way for add-ons to look up the current totals for given members. All of this can be done with an API.

Our file structure for this might look something like:

_add-ons/
   karma/
      api.karma.php
      tasks.karma.php
      pi.karma.php

In this listing, we’ve also added in a plugin, let’s say that that’s for displaying the a given member’s karma level within a template. There’s a tasks file that is going to hold all of the functionality for the karma add-on. These methods are accessible by api.karma.php and pi.karma.php by calling them through the $this->tasks object. Centralizing functionality lets us keep things DRY.

Defining an API

A basic starting API object for karma might look something like this:

<?php
class API_karma extends API
{

}

Within this object, create any methods that you’d like to provide information to other add-ons. For our example, let’s create a way to get the number of points for a given member.

<?php
class API_karma extends API
{
   public function getPoints($uid)
   {
      $points = $this->cache->get('points.yaml', array());

      if (!isset($points[$uid])) {
         // member not found, return 0 points
         return 0;
      }

      return $points[$uid];
   }
}

In this example, the interface of getPoints requires a member’s _uid. If it’s stored in the saved list of point values, that value gets returned, otherwise we return 0.

Consuming an API

A new contextual object has been added to the Addon object, called addon. It has three methods that you can use in your add-ons to interact with other add-ons.

• isInstalled($addon) returns a boolean value, letting you check to see if a given $addon is installed on the current site
• hasAPI($addon) returns a boolean value, letting you check to see if a given $addon has an API that you can use; this check also first checks isInstalled and if either are false, will return false
• api($addon) returns the given $addon’s API object, this method will check for the add-on being installed as well as having an API, and will throw an exception if either are false

With these three methods, add-ons can now nicely communicate with one another. Let’s say the sample add-on wants to look up karma points for the current member. Within any of that add-on’s aspects (Plugin, Modifier, Hooks, etc), the author can do something like this:

<?php
public function example()
{
   // step 1, make sure someone's logged in and that there's a karma API we can access
   if (!Auth::isLoggedIn() || !$this->addon->hasAPI('karma')) {
      return false;
   }

   // get the current member
   $member = Auth::getCurrentMember();

   // get the points for this user
   $karma_points = $this->addon->api('karma')->getPoints($member->getUID());

   // use $karma_points however in our add-on
}
?>

Finally, note that this is just an example of how to read information, but an API can do anything, including writing information. For example, the karma add-on’s API probably makes more sense if we created a couple of methods for adding and subtracting points. These would work the same way.