CHAPTER 20 ■ XML-RPC

drupal_set_message(t('Could not get state name because the remote site gave an error: %message (@code).', array(

'%message' => $error->message, '@code' => $error->code

)

)

);

This code results in the following message being displayed to the user:

Could not get state name because the remote site gave an error: Can't evaluate the expression because the name “0” hasn’t been defined. (7).

Note that when you report errors, you should tell three things: what you were trying to do, why you can’t do it, and additional information to which you have access. Often a friendlier error is displayed using drupal_set_message() to notify the user, and a more detailed error is written to the watchdog and is viewable at Reports -> Recent log messages.

A Simple XML-RPC Server

As you’ve seen in the XML-RPC client examples, Drupal does most of the heavy lifting for you. Let’s go through a simple server example. You need to do three things to set up your server:

1.Define the function you want to execute when a client request arrives.

2.Map that function to a public method name.

3.Optionally define a method signature.

As usual with Drupal, you want to keep your code separate from the core system and just plug it in as a module. So here’s a brief module that says “hello” via XML-RPC. Create the sites/all/modules/ custom/remotehello/remotehello.info file:

name = Remote Hello

description = Greets XML-RPC clients by name. package = Pro Drupal Development

core = 7.x

Here’s remotehello.module:

<?php

/**

*Implements hook_xmlrpc().

*Map external names of XML-RPC methods to PHP callback functions.

*/

457

CHAPTER 20 ■ XML-RPC

function remotehello_xmlrpc() { $methods['remoteHello.hello'] = 'xmls_remotehello_hello'; return $methods;

}

/**

* Greet a user. */

function xmls_remotehello_hello($name) { if (!$name) {

return xmlrpc_error(1, t('I cannot greet you by name if you do not provide one.'));

}

return t('Hello, @name!', array('@name' => $name));

}

Mapping Your Method with hook_xmlrpc()

The xmlrpc hook describes external XML-RPC methods provided by the module. In our example, we’re providing only one method. In this case, the method name is remoteHello.hello. This is the name that requestors will use, and it’s completely arbitrary. A good practice is to build the name as a dot-delimited string using your module name as the first part and a descriptive verb as the latter part.

■ Note Although camelCase is generally shunned in Drupal, external XML-RPC method names are the exception.

The second part of the array is the name of the function that will be called when a request for remoteHello.hello comes in. In our example, we’ll call the PHP function xmls_remotehello_hello(). As you develop modules, you’ll be writing many functions. By including “xmls” (shorthand for XML-RPC Server) in the function name, you’ll be able to tell at a glance that this function talks to the outside world. Similarly, you can use “xmlc” for functions that call out to other sites. This is particularly good practice when you’re writing a module that essentially calls itself.

When your module determines that an error has been encountered, use xmlrpc_error() to define an error code and a helpful string describing what went wrong to the client. Numeric error codes are arbitrary and application-specific.

Assuming the site with this module lives at example.com, you’re now able to send your name from a separate Drupal installation (say, at example2.com) using the following code:

$url = 'http://example.com/xmlrpc.php'; $method_name = 'remoteHello.hello'; $name = t('Joe');

$result = xmlrpc($url, array($method_name => array($name)));

$result is now "Hello, Joe."

458

CHAPTER 20 ■ XML-RPC

Automatic Parameter Type Validation with hook_xmlrpc()

The xmlrpc hook has two forms. In the simpler form, shown in our remotehello.module example, it simply maps an external method name to a PHP function name. In the more advanced form, it describes the method signature of the method—that is, what XML-RPC type it returns and what the type of each parameter is (see www.xmlrpc.com/spec for a list of types). Here’s the more complex form of the xmlrpc hook for remotehello.module:

/**

*Implements hook_xmlrpc().

*Map external names of XML-RPC methods to callback functions.

*Verbose syntax, specifying data types of return value and parameters.

*/

t('Greets XML-RPC clients by name.') // Description.

);

return $methods;

}

Figure 19-2 shows the XML-RPC request life cycle of a request from an XML-RPC client to our module. If you implement the xmlrpc hook for your module using the more complex form, you’ll get several benefits. First, Drupal will validate incoming types against your method signature automatically and return -32602: Server error. Invalid method parameters to the client if validation fails. (This also means that your function will be pickier—no more automatic type coercion, like accepting the string '3' if the integer 3 is meant!) Also, if you use the more complex form of the xmlrpc hook, Drupal’s built-in XML-RPC methods system.methodSignature and system.methodHelp will return information about your method. Note that the description you provide in your xmlrpc hook implementation will be returned as the help text in the system.methodHelp method, so take care to write a useful description.

459

CHAPTER 20 ■ XML-RPC

Download from Wow! eBook <www.wowebook.com>

Figure 19-2. Processing of an incoming XML-RPC request

460