XML-RPC for WordPress Developers

    Narayan Prusty
    Share

    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.

    XML-RPC for WordPress

    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.