Service Module Example

Here is a commented example of a custom service module that uses hook_service() to become a service.

Drupal 6

Under drupal 6.x, one needs to implement hook_disable() and hook_enable() like this:

<?php
/*
* Implementation of hook_disable()
* Perform necessary actions before module is disabled. (like clear the services:methods cache)
*/
function yourModuleName_disable() {
  cache_clear_all('services:methods', 'cache');
}
/*
* Implementation of hook_enable()
* Perform necessary actions after module is enabled. (like clear the services:methods cache)
*/
function yourModuleName_enable() {
  cache_clear_all('services:methods', 'cache');
}
?>

otherwise any changes during development are unrecognised because they get cached.

Drupal 5 + 6

<?php
/*
 * Implementation of hook_service()
 * Required by all server modules
 * Returns array defining all the methods available in the service
 */
function recipe_service_service() {
  return array(
    
    /**
     * recipe.all
     * We define methods in hashed arrays
     */
    array(
      
      /**
       * #method - defines the namespace and method name
       * the namespace is everything before the last period, so you can do
       * methods like 'recipe.lunch.all' where 'recipe.lunch' is the namespace,
       * or service, and 'all' is the method
       */
      '#method' => 'recipe.all',
      
      // #callback - the php function to map the method call to
      '#callback' => 'recipe_service_all',
      
      /** 
       * #args - a list of method arguments
       * These may be in lazy form - array('string','array') with only an array
       * of datatypes.
       * Or, they may be in in the form of an array of hashed arrays like shown
       * below:
       */
      '#args' => array(
        array(
          
          // #name - the name of the argument
          '#name' => 'fields',
          
          // #type - the datatype of the argument
          '#type' => 'array',
          
          /**
           * #optional - the argument is optional, true or false
           * Because php functions cannot have a required argument after an 
           * optional argument, arguments after an optional argument are set
           * to optional regardless of the value of the #optional hash
           */
          '#optional' => true,
          
          // #description - Used in the service browser
          '#description' => 'A list of fields to filter.'
        )
      ),
      // #return - The return data type, may be used by certain server modules
      '#return' => 'array',
      
      // #help - Used in the service browser
      '#help' => 'Returns a list of recipes'
    )
    
  );
}

/**
 * Callback for "recipe.all"
 * We need to include the fields argument and set a default value because
 * it is optional,
 * We do not need to include an API key or SESSID field if these are enabled
 * for Services.  These arguments are handled by Services transparently and
 * stripped before we reach this callback.
 */
function recipe_service_all($fields = array()) {
  $result = db_query("SELECT nid FROM {node} WHERE type='recipe'");
  
  $nodes = array();
  while ($node = db_fetch_object($result)) {
    // services_node_load filters a node and returns only the requested fields.
    $nodes[] = services_node_load(node_load($node->nid), $fields);
  }
  
  // return the array result
  return $nodes;
}
?>