A Custom Drupal XMLRPC Service

I have written earlier about using Drupal as an XMLRPC client - via a custom module that hooks into the persistence lifecycle of a Drupal node in order to send XMLRPC requests out to an external publishing system containing an embedded XMLRPC server. Drupal can also act as an XMLRPC server, receiving and acting on XMLRPC requests from external clients.

We have been using one of the built-in services (the comment.save from Comment Services Module). However, we recently decided to build an external Comment Moderation tool, since we have outgrown the rather rudimentary comment moderation form available in Drupal, and that needs services exposed on Drupal to publish, unpublish and delete a comment, which are not available from the comment services module.

My initial explorations on Google pointed me to the this post on the Riff Blog, and thence to the XMLRPC hook, available in core Drupal. However, the results were not too satisfying (it didn't show up on the Services page at /admin/build/services) so I quickly abandoned this path and went looking for something better.

I found my answer in the source code for the Comment Services Module - it implemented hook_service(), so that pointed me to the Services Module, which in turn led me to the Services Handbook, and buried in the links on the right navigation toolbar on this page, some information that I could actually use.

Interestingly, not only does Drupal allow you to build/install custom services, it also allows for custom servers (such as JSON or SOAP). However, since I already had an XMLRPC server installed for the pre-installed services, I did not explore this option. There is more information about this on Deja Augustine's post here, along with some skeletal code for a simple service.

My example is a bit more involved, but uses the same ideas as Deja's post. Build a custom module that is in the "Services - services" package and depends on the services package (to the best of my knowledge, these are required, when I tried putting it under a different package, it would not show up on the Services page). Therefore, although I physically put the code under the sites/all/modules/custom/cmxs directory, the package name is "Services - services". Here is the .info file for my module.

1 2 3 4 5

name = cmxs description = Comment Moderation XMLRPC Services package = Services - services dependencies[] = services core = 6.x

The module code is also quite simple. The hook_service() declares the methods that the service makes available, along with name, input and output parameter name and types, and the names of callback functions each method must call. You can install the module immediately after your hook_service() declarations are done (along with stubs for the callback functions) by going to the Modules (admin/build/modules) page and enabling the new module. The new services will show up on the Services (admin/build/services) page, along with forms to manually test the services.

Here is the complete code for my services module:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167

<?php define('CMXS_SUCCESS', 0); define('CMXS_COMMENT_PUBLISHED', 0); define('CMXS_COMMENT_NOT_PUBLISHED', 1); /** * Implementation of hook_service(). * Describes the methods that are exposed by this service module. */ function cmxs_service() { return array ( // comment_publish array ( '#method' => 'cmxs.comment_publish', '#callback' => 'cmxs_comment_publish', '#access callback' => 'cmxs_user_access', '#args' => array ( array ( '#name' => 'cids', '#type' => 'string', '#description' => t('Comma-separated list of Comment IDs, eg. $cid1,$cid2,...') ) ), '#return' => 'int', '#help' => t('Publishes the specified comment.') ), // comment_unpublish array ( '#method' => 'cmxs.comment_unpublish', '#callback' => 'cmxs_comment_unpublish', '#access callback' => 'cmxs_user_access', '#args' => array ( array ( '#name' => 'cids', '#type' => 'string', '#description' => t('Comma-separated list of Comment IDs, eg. $cid1,$cid2,...') ) ), '#return' => 'int', '#help' => t('Unpublishes the specified comment.') ), // comment_delete array ( '#method' => 'cmxs.comment_delete', '#callback' => 'cmxs_comment_delete', '#access callback' => 'cmxs_user_access', '#args' => array ( array ( '#name' => 'cids', '#type' => 'string', '#description' => t('Comma-separated list of Comment IDs, eg. $cid1,$cid2,...') ) ), '#return' => 'int', '#help' => t('Deletes the specified comment.') ), ); } /** * Implementation of hook_disable(). * Actions that need to happen when this module is disabled. */ function cmxs_disable() { cache_clear_all('services:methods', 'cache'); } /** * Implementation of hook_enable(). * Actions that need to happen when this module is enabled. */ function cmxs_enable() { cache_clear_all('services:methods', 'cache'); } /** * Custom user access function to short circuit user_access() since * we want to bypass Drupal's authentication, since the tool will * always send authenticated requests. */ function cmxs_user_access() { return TRUE; } /** * Finds the comments corresponding to the cids specified that are in * state NOT_PUBLISHED and updates their status to PUBLISHED, then saves * them. */ function cmxs_comment_publish($cids) { watchdog('cmxs', 'cmxs_comment_publish(cids=' . $cids . ')'); $comments = _cmxs_find_comments($cids, CMXS_COMMENT_NOT_PUBLISHED); foreach ($comments as $comment) { $comment->status = CMXS_COMMENT_PUBLISHED; comment_save((array) $comment); watchdog('cmxs', 'Comment (cid=' . $comment->cid . ') published'); } return CMXS_SUCCESS; } /** * Finds the comments corresponding to the cids specified that are in * state PUBLISHED and updates their status to PUBLISHED, then saves them. */ function cmxs_comment_unpublish($cids) { watchdog('cmxs', 'cmxs_comment_unpublish(cids=' . $cids . ')'); $comments = _cmxs_find_comments($cids, CMXS_COMMENT_PUBLISHED); foreach ($comments as $comment) { $comment->status = CMXS_COMMENT_NOT_PUBLISHED; comment_save((array) $comment); watchdog('cmxs', 'Comment (cid=' . $comment->cid . ') unpublished'); } return CMXS_SUCCESS; } /** * Since deleting a comment requires administrator privileges, we cannot * call comment_delete($cid) directly (since our service has no privileges). * So we unpublish first, and then delete using a direct SQL call. */ function cmxs_comment_delete($cids) { watchdog('cmxs', 'cmxs_comment_delete(cids=' . $cids . ')'); $comments = _cmxs_find_comments($cids); foreach ($comments as $comment) { $comment->status = CMXS_COMMENT_NOT_PUBLISHED; comment_save((array) $comment); // UDXI unpublished called here _cmxs_delete_comment($comment->cid); watchdog('cmxs', 'Comment (cid=' . $comment->cid . ') deleted'); } return CMXS_SUCCESS; } /** * Given a comma-separated list of CIDs, return a list of comments that * correspond to these CIDs. CIDs that don't correspond to a Comment in * Drupal are silently ignored. If the optional parameter status is provided * only comments with the specified status are returned. */ function _cmxs_find_comments($cids, $status = NULL) { $comments = array(); $cid_array = explode(',', $cids); if ($cid_array == FALSE) { return $comments; } else { foreach ($cid_array as $cid) { $comment = _comment_load($cid); if ($comment != NULL) { if ($status != NULL) { if ($comment->status != $status) { continue; } } $comments[] = $comment; } } } return $comments; } /** * Deletes a comment corresponding to the specified cid from the Drupal * database. There is no authorization check. */ function _cmxs_delete_comment($cid) { $db_result = db_query('DELETE FROM {comments} WHERE cid = %d', $cid); }

As you can see, the hook_service() is purely declarative. I also have hook_enable() and hook_disable() implementations to make it a bit quicker to develop (changes in method signature only needs a module disable followed by a module enable, no update.php run required).

I also have a custom user_access() function which does nothing. Because I am using non-authenticated XMLRPC requests, and the Drupal comment API for saving the updated comment object, I figured that Drupal would insist (as it should) on an authorized user to do the updates. So the cmxs_user_access() function is there to bypass Drupal's authentication.

I have mentioned before about how impressed I am by Drupal's overall design, and the Services module is no exception. Like the rest of Drupal, it follows the convention over configuration philosophy, and once you understand the convention, building a custom service is really quite simple.