Intent URL API

This (currently experimental) code acts as a central point for modules that rely on this to define specific URLs to perform certain actions.

Modules that come with Ajax buttons, one-time click URLs, flagging, and such features have to define a menu router item in order to get them called. For every implementation, there are many tasks that are common:

• Define the menu router
• Javascript fallback
• CSRF protection
• Access verification
• Ajax rendering and delivering
• etc

This module is an API module, and has no functionality for site builders. Instead, it exposes an API for other modules to easily define actions (not to be confused with Drupal core actions module or Views Bulk Operations module actions), and this module can do the heavy lifting of menu router items, CSRF protection, and URL validation.

An "Intent" in this module is an action that the user attempts to do. This module's goal is to make the Intents are responded with minimal server resources as possible, without compromising the security.

Suppose you are creating a module to let users subscribe to a piece of content.
You can call the Intent API to generate a specific URL for you:

  // Method 1:
  $intent = new Intent('favorite');
  $intent->setArgs($node->nid, $user->uid);
  print $intent->getUrl();

  // Method 2:
  print intent_get_url('favorite', $node->nid, $user->uid);

The output URL will contain all your passed arguments, a JS loader argument (ctools_js), and a signature of the arguments to prevent them from being tampered.

Intent API, by default, signs URLs with the current user session ID as well for enhanced security, but your "intent" can be defined to make them independent from the session. This is useful for links that must last a long period of time, and the intended user is different or possible have a different session ID.

The signed URL would look like this:

http://example.com/intent/favorite/123/1/nojs/g6YVoTkSKDsoGS_j1rs0xcD1k_oHm02D5f2afemMgy8

Modules do not have to define a menu router item to handle the URLs. Intent API handles the requests, and calls the relevant function after verifying the signature. It also detects Javascript support, and provide all these information to the callback function to do the rest.

In our example, the "favorite" intention needs to be defined first.

// Define the intent.
function MYMODULE_intent_info() {
  $intents = array();
  $intents['favorite'] = array(
    'page callback' => 'MYMODULE_favorite_perform',
    'file' => 'operations.mymodule.inc',
    'uses session' => TRUE,
  );
}

//This function will be called (after validating the signature, and including operations.mymodule.inc). 
function MYMODULE_favorite_perform(Intent $intent, $nid, $uid) {
  // You can use $intent object to perform further actions, such as force denying access, Ajax commands, etc.
  //db_merge('mymodule_favorite')...
}

The callback functions usually do not need to load the object to make sure they exist. But you can load them yourself or let the Intent API load them for you (similar to Drupal core menu routers).