XML-RPC for WordPress Developers

XML-RPC is a remote procedure call (one process calling the function of another process via a remote connection) protocol which uses XML to represent data and HTTP to make the calls. Although applications can explicitly provide their own REST APIs for RPC, a standard protocol can help security and provide many other benefits. For example, developers don’t have to design a REST API architecture from scratch and also a single client can be used to make remote procedure calls to various server applications which support the standard protocol. Therefore, XML-RPC was introduced as a standard protocol for RPC. In this tutorial we’ll look at the different core WordPress functions which can be executed remotely using XML-RPC. This can help us to build tools which can perform various operations on a WordPress installation. One of the greatest examples of this is the WordPress Mobile App.

Overview of an XML-RPC Protocol Request and Response

To make an XML-RPC request you need to wrap the remote function name and parameters in XML format and then send a POST request using HTTP. This is an example of a XML-RPC HTTP request:

POST /xmlrpc HTTP 1.0
User-Agent: myXMLRPCClient/1.0
Host: 192.168.124.2
Content-Type: text/xml
Content-Length: 169
<?xml version="1.0"?>
<methodCall>
<methodName>circleArea</methodName>
<params>
<param>
<value><double>2.41</double></value>
</param>
</params>
</methodCall>

Here’s a sample response to the above request:

HTTP/1.1 200 OK
Date: Sat, 06 Oct 2001 23:20:04 GMT
Server: Apache.1.3.12 (Unix)
Connection: close
Content-Type: text/xml
Content-Length: 124

<?xml version="1.0"?>
<methodResponse>
<params>
<param>
<value><double>18.24668429131</double></value>
</param>
</params>
</methodResponse>

In this tutorial we’ll use PHP to send XML-RPC requests to WordPress and display the raw response. We would generally write code to wrap our function name and parameters in XML format and then make an HTTP request using cURL, but writing code for this from scratch is lengthy. Instead we can use the PHPXMLRPC library, which provides abstraction to all of these steps and lets us make XML-RPC requests much more easily. XML-RPC libraries are available for all popular programming languages, you can find one for your preferred language using your favorite search engine.

WordPress XML-RPC Functions

There are lots of WordPress core functions that WordPress exposes via XML-RPC. All of the XML-RPC exposed functions are categorized into 9 categories: Posts, Taxonomies, Media, Comments, Options, Users, Categories, Tags and Pages.

A List of the Functions

Here’s the complete list of all functions: Posts functions: Available from WordPress 3.4. Here is the list of functions that belong to posts category:

wp.getPost
wp.getPosts
wp.newPost
wp.editPost
wp.deletePost
wp.getPostType
wp.getPostTypes
wp.getPostFormats
wp.getPostStatusList

Taxonomies functions: Available from WordPress 3.4. Here is the list of functions that belong to taxonomies category:

wp.getTaxonomy
wp.getTaxonomies
wp.getTerm
wp.getTerms
wp.newTerm
wp.editTerm
wp.deleteTerm

Media functions: Available from WordPress 3.1. Here is the list of functions that belong to taxonomies category:

wp.getMediaItem
wp.getMediaLibrary
wp.uploadFile

Comments functions: Available from WordPress 2.7. Here is the list of functions that belong to the comments category:

wp.getCommentCount
wp.getComment
wp.getComments
wp.newComment
wp.editComment
wp.deleteComment
wp.getCommentStatusList

Options functions: Available from WordPress 2.6. Here is the list of functions that belong to the options category:

wp.getOptions
wp.setOptions

Users functions: Available from WordPress 3.5. Here is the list of functions that belong to the users category:

wp.getUsersBlogs
wp.getUser 
wp.getUsers 
wp.getProfile 
wp.editProfile
wp.getAuthors

Categories functions: Available from WordPress 3.4. Here is the list of functions that belong to the categories category:

wp.getCategories
wp.suggestCategories
wp.newCategory
wp.deleteCategory

Tags functions: Available from WordPress 3.4. Here is the list of functions that belong to the tags category:

wp.getTags

Pages functions: Available from WordPress 3.4. Here is the list of functions that belong to the pages category:

wp.getPage
wp.getPages
wp.getPageList
wp.newPage
wp.editPage
wp.deletePage
wp.getPageStatusList
wp.getPageTemplates

All of the category names and function names, as well as the use and purposes are quite self explanatory. Let’s see some examples of the above functions:

Getting a List of WordPress Authors

Here is the code to get list of all authors of a remote WordPress installation using PHP:

<?php
include("lib/xmlrpc.inc");
$function_name = "wp.getAuthors";
$url = "https://www.sitepoint.com/xmlrpc.php";

$client = new xmlrpc_client($url);
$client->return_type = "phpvals";
$message = new xmlrpcmsg($function_name, array(new xmlrpcval(0, "int"), new xmlrpcval("username", "string"), new xmlrpcval("password", "string")));
$resp = $client->send($message);

if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else foreach ($resp->val as $key => $value) {
echo "User id: " . $value["user_id"];
echo "<br><br>";
echo "Username: " . $value["user_login"];
echo "<br><br>";
echo "Display name: " . $value["display_name"];
echo "<br><br>";
};
?>

Let’s see how the above code works:

• First we included PHPXMLRPC library.
• Then we create a variable $function_name to hold the function name.
• We created an another variable which points to the xmlrpc.php file of the WordPress installation. This file always exists in the root of WordPress.
• Then we create an XML-RPC client object and pass the URL to the constructor.
• We then instruct the library to convert the response data into a PHP array variable so it will be easy to read and work with the response data. Working with raw XML response data will be difficult as we have to parse the XML.
• Then we construct a request message object with the parameters for the wp.getAuthors function. First parameters is the blog id, the other two parameters are the username and password of the administrator.
• Next, we send the XML-RPC request.
• Finally we get the response. If there’s an error we display the error, otherwise we loop the response object’s value property to print the authors basic information.

Creating a Post

We just saw how easy it is to retrieve a list of authors, here’s how you can create a post:

<?php
include("lib/xmlrpc.inc");
$function_name = "wp.newPost";
$url = "https://www.sitepoint.com/xmlrpc.php";

$client = new xmlrpc_client($url);
$client->return_type = 'phpvals';

$message = new xmlrpcmsg(
$function_name,
array(
new xmlrpcval(0, "int"),
new xmlrpcval("my_cool_username", "string"),
new xmlrpcval("my_super_secret_password", "string"),
new xmlrpcval(
array(
"post_type" => new xmlrpcval("post", "string"),
"post_status" => new xmlrpcval("draft", "string"),
"post_title" => new xmlrpcval("Sitepoint is Awesome", "string"),
"post_author" => new xmlrpcval(1, "int"),
"post_excerpt" => new xmlrpcval("excerpt", "string"),
"post_content" => new xmlrpcval("content", "string")
),
"struct"
)
)
);

$resp = $client->send($message);

if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo "Post id is: " . $resp->value();
?>

Here, we called the function wp.newPost. Along with the blog id, username and password. We also passed a struct type containing post type, status, title, content, author and excerpt.

Note: Detecting the XML-RPC Request

A quick note: If you’re a plugin or theme developer, then you might want your code to function differently for XML-RPC requests. WordPress allows a way for themes and plugin to detect if WordPress is processing a XML-RPC request. Here is the code to detect XML-RPC requests:

if(defined('XMLRPC_REQUEST'))
{
// XML-RPC request
}
else
{
// Normal HTTP request
}

Conclusion

In this article we covered the fundamentals of XML-RPC for WordPress, including the basics of XML-RPC and how WordPress exposes this protocol. We also demonstrated how to perform various operations on a WordPress installation using XML-RPC. You can now create a mobile, desktop or a web application XML-RPC client for WordPress.

Frequently Asked Questions (FAQs) about XML-RPC for WordPress Developers