Building Web Apps with WordPress (2014)
Chapter 10. XML-RPC
WordPress is awesome, and you can build a lot of really cool applications just with it, but what if your application needs to communicate with other applications or other WordPress installations?
XML-RPC is a remote procedure call (RPC) protocol that uses XML to encode its calls and HTTP as a transport mechanism. WordPress uses an XML-RPC interface to easily allow developers to access and post data from other applications, including other WordPress sites.
We’ve compiled a list of some of the available methods of the wp_xmlrpc_server class along with the arguments that can be used and what values each function returns.
If you would like to follow along with the code examples for some of the following methods, set up the following function in a custom plugin or in your theme’s functions.php file. Also, be careful because some of the examples update and delete data:
<?php
add_action( 'init', 'wds_include_IXR' );
function wds_include_IXR() {
// You need to include this file in order to use the IXR class.
require_once ABSPATH . 'wp-includes/class-IXR.php';
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
// Another WordPress site you want to push and pull data from
$xmlrpc_url = 'http://anotherwordpresssite.com/xmlrpc.php';
$xmlrpc_user = 'admin'; // Hope you're not using "admin" ;)
$xmlrpc_pass = 'password'; // Really hope you're not using "password" ;)
}
?>
wp.getUsersBlogs
Calls the function wp_getUsersBlogs( $args ) and requires an array:
§ $username—A string of the username used to log in to the given WordPress URL.
§ $password—A string of the password used to log in to the given WordPress URL.
This function returns an array:
§ isAdmin
§ URL
§ blogid
§ blogName
§ xmlrpc—URL of XML-RPC endpoint
<?php
function bwawwp_xmlrpc_getUsersBlogs() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// returns all blogs in a multisite network
$rpc->query( 'wp.getUsersBlogs', $xmlrpc_user, $xmlrpc_pass );
echo '<h1>Blogs</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getUsersBlogs', 999 );
?>
wp.getPosts
Calls the function wp_getPosts( $args ) and requires an array:
§ $blog_id
§ $username
§ $password
§ $filter—An optional array of fields you would like to query posts by. The array can contain keys for post_type, post_status, number, offset, orderby, and/or order.
§ $fields—An optional array of the post fields and their values you would like to return.
This function returns an array of posts with the post fields you specified in the $fields parameter:
<?php
function bwawwp_xmlrpc_getPosts() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// returns all posts of post post_type
$rpc->query( 'wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass );
echo '<h1>posts</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
// returns all posts of page post_type (or any specific post type)
$filter = array( 'post_type' => 'page' );
$rpc->query( 'wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass, $filter );
echo '<h1>pages</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
// returns 5 published page titles in abc order
$filter = array(
'post_type' => 'page',
'status' => 'publish',
'number' => '5',
'orderby' => 'title',
'order' => 'ASC'
);
$fields = array( 'post_title' );
$rpc->query('wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass, $filter, $fields);
echo '<h1>5 published page titles</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getPosts', 999 );
?>
wp.getPost
Calls the function wp_getPost($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_id—A required integer of the post ID of the post you want to get.
§ $fields—An optional array of the post fields and values you would like to return.
This function returns an array of fields based on the $fields parameter. You can use any of the following fields:
§ post_id
§ post_title
§ post_date
§ post_date_gmt
§ post_modified
§ post_modified_gmt
§ post_status
§ post_type
§ post_name
§ post_author
§ post_password
§ post_excerpt
§ post_content
§ link
§ comment_status
§ ping_status
§ sticky
§ custom_fields
§ terms
§ categories
§ tags
§ enclosure
<?php
function bwawwp_xmlrpc_getPost() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$method = 'wp.getPost';
// return last post to get a post ID
$filter = array('number' => '1', 'orderby' => 'date', 'order' => 'DESC');
$fields = array('post_id');
$rpc->query('wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass, $filter,
$fields);
$response = $rpc->getResponse();
$post_id = $response[0]['post_id'];
// return all data on last $post_id
$rpc->query( 'wp.getPost', 0, $xmlrpc_user, $xmlrpc_pass, $post_id );
echo '<h1>Post ID: '.$post_id.'</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getPost', 999 );
?>
wp.newPost
Calls the function wp_newPost($args) and requires an array:
§ $blog_id—An integer of the blog ID to add the post to.
§ $username
§ $password
§ $content—An array of post data for creating a new post. This array can contain any of the fields the function wp_insert_post() supports.
This function returns a string of the post_id:
<?php
function bwawwp_xmlrpc_newPost() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// create an array with post data
$content = array(
'post_title' => 'New Post with XML-RPC'
);
$rpc->query( 'wp.newPost', 0, $xmlrpc_user, $xmlrpc_pass, $content );
$post_id = $rpc->getResponse();
echo '<h1>New Post ID: '. $post_id .'</h1>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_newPost', 999 );
?>
wp.editPost
Calls the function wp_editPost($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_id —A required integer of the post ID you want to update.
§ $content—An array of post data for updating an existing post. Only fields in the array will be updated.
This function returns true on success:
<?php
function bwawwp_xmlrpc_editPost() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// return last post to get a post ID
$filter = array('number' => '1', 'orderby' => 'date', 'order' => 'DESC');
$fields = array('post_id');
$rpc->query('wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass, $filter, $fields);
$response = $rpc->getResponse();
$post_id = $response[0]['post_id'];
// create an array with new post data
$content = array(
'post_title' => 'Updated Post with XML-RPC',
'post_status' => 'publish'
);
$rpc->query('wp.editPost', 0, $xmlrpc_user, $xmlrpc_pass, $post_id,
$content);
echo '<h1>Updated Post ID: '. $post_id .'</h1>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_editPost', 999 );
?>
wp.deletePost
Calls the function wp_deletePost($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_id
This function returns true on success:
<?php
function bwawwp_xmlrpc_deletePost() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// return last post to get a post ID
$filter = array('number' => '1', 'orderby' => 'date', 'order' => 'DESC');
$fields = array('post_id');
$rpc->query('wp.getPosts', 0, $xmlrpc_user, $xmlrpc_pass, $filter, $fields);
$response = $rpc->getResponse();
$post_id = $response[0]['post_id'];
// delete post by $post_id
$rpc->query( 'wp.deletePost', 0, $xmlrpc_user, $xmlrpc_pass, $post_id );
echo '<h1>Deleted Post ID: '. $post_id .'</h1>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_deletePost', 999 );
?>
wp.getTerms
Calls the function wp_getTerms($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $taxonomy—A required string of the taxonomy of the terms you want to retrieve.
§ $filter—An optional array of parameters used to alter the query used to retrieve the terms. The array can contain number, offset, orderby, order, hide_empty, and/or search.
This function returns an array of terms and their fields:
<?php
function bwawwp_xmlrpc_getTerms() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$rpc->query( 'wp.getTerms', 0, $xmlrpc_user, $xmlrpc_pass, 'category' );
echo '<h1>Category Terms</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getTerms', 999 );
?>
wp.getTerm
Calls the function wp_getTerm($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $taxonomy_name—A required string of the taxonomy of the term you want to retrieve.
§ $term_id—A required string of the term ID of the term you want to retrieve.
This function returns an array of term fields:
§ term_id
§ name
§ slug
§ term_group
§ term_taxonomy_id
§ taxonomy
§ description
§ parent
§ count
<?php
function bwawwp_xmlrpc_getTerm() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$rpc->query( 'wp.getTerm', 0, $xmlrpc_user, $xmlrpc_pass, 'category', 1 );
echo '<h1>Term ID 1</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getTerm', 999 );
?>
wp.newTerm
Calls the function wp_newTerm($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $content—An array of term data for adding a new term. The array can contain keys for name, taxonomy, parent, description, and slug.
This function returns a string of the term_id.
wp.editTerm
Calls the function wp_editTerm($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $term_id—A required string of the term ID of the term you want to update.
§ $content—An array of term data you would like to update. The array can contain keys for name, taxonomy, parent, description, and slug.
This function returns a string of the term_id.
wp.deleteTerm
Calls the function wp_deleteTerm($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $taxonomy_name—A required string of the taxonomy of the term you want to delete.
§ $term_id—A required string of the term ID of the term you want to delete.
This function returns true on success and an error message if it fails.
wp.getTaxonomies
Calls the function wp_getTaxonomies($args) and requires an array:
§ $blog_id
§ $username
§ $password
This function returns an array of taxonomies and their settings:
<?php
function bwawwp_xmlrpc_getTaxonomies() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$rpc->query( 'wp.getTaxonomies', 0, $xmlrpc_user, $xmlrpc_pass );
echo '<h1>Taxonomies</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getTaxonomies', 999 );
?>
wp.getTaxonomy
Calls the function wp_getTaxonomy($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $taxonomy—A required string of the taxonomy you want to retrieve.
This function returns an array of taxonomy settings.
wp.getUsers
Calls the function wp_getUsers($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $filter—An optional array of fields you would like to query users by. The array can contain keys for number (default: 50), offset (default: 0), role, who, orderby, and/or order.
§ $fields—An optional array of the user fields and values you would like to return. You can use any of the following fields:
§ user_id
§ username
§ first_name
§ last_name
§ registered
§ bio
§ nickname
§ nicename
§ url
§ display_name
§ roles
This function returns an array of users with the user fields you specified in the $fields parameter:
<?php
function bwawwp_xmlrpc_getUsers() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$rpc->query( 'wp.getUsers', 0, $xmlrpc_user, $xmlrpc_pass );
echo '<h1>Users</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
$filter = array( 'role' => 'administrator' );
$fields = array( 'username', 'email' );
$rpc->query('wp.getUsers', 0, $xmlrpc_user, $xmlrpc_pass, $filter, $fields);
echo '<h1>Filtered Users</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getUsers', 999 );
?>
wp.getUser
Calls the function wp_getUser($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $user_id—A required integer of a user ID of the user you would like to retrieve.
§ $fields—An optional array of user fields you would like to return. You can use the same fields as in the wp_getUsers() function.
This function returns an array of fields based on the $fields parameter.
wp.getProfile
Calls the function wp_getProfile($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $fields—An optional array of user fields you would like to return.
This function returns an array of user fields for the logged-in user from the $fields parameter. You can use the same fields as in the wp_getUser() function.
wp.editProfile
Calls the function wp_editProfile($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $content—An array of user data for updating the current user. The array can contain keys for first_name, last_name, website, display_name, nickname, nicename, and bio.
This function returns true on success.
wp.getCommentCount
Calls the function wp_getCommentCount($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_id
This function returns an array of the following comment counts:
§ approved
§ awaiting_moderation
§ spam
§ total_comments
wp.getPageTemplates
Calls the function wp_getPageTemplates($args) and requires an array:
§ $blog_id
§ $username
§ $password
This function returns an array of page templates.
wp.getOptions
Calls the function wp_getOptions($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $options—An optional array of options to return values for. If no options are passed in, then all options will be returned.
This function returns an array of options:
<?php
function bwawwp_xmlrpc_getOptions() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$rpc->query( 'wp.getOptions', 0, $xmlrpc_user, $xmlrpc_pass );
echo '<h1>All Options</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
$options = array( 'blog_url', 'template' );
$rpc->query( 'wp.getOptions', 0, $xmlrpc_user, $xmlrpc_pass, $options );
echo '<h1>Filter 2 Options</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getOptions', 999 );
?>
wp.setOptions
Calls the function wp_setOptions($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $options—A required key and value array of options to update.
This function returns an array of updated options:
<?php
function bwawwp_xmlrpc_setOptions() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$options = array(
'blog_title' => 'Site Title via XML-RPC',
'blog_tagline' => 'Just another WordPress site via XML-RPC'
);
$rpc->query( 'wp.setOptions', 0, $xmlrpc_user, $xmlrpc_pass, $options );
echo '<h1>Set Options</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_setOptions', 999 );
?>
wp.getComment
Calls the function wp_getComment($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $comment_id—A required integer of the comment ID of the comment you would like to retrieve.
This function returns an array of comment data:
§ date_created_gmt
§ user_id
§ comment_id
§ parent
§ status
§ content
§ link
§ post_id
§ post_title
§ author
§ author_url
§ author_email
§ author_ip
§ type
wp.getComments
Calls the function wp_getComments($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $filter—An optional array of filterable comment values. The array can contain keys for status, post_id, offset, and/or number (default: 10).
This function returns an array of comments with the same individual comment data that gets returned with the wp_getComment() function:
<?php
function bwawwp_xmlrpc_getComments() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
$filter = array( 'status' => 'approve', 'number' => '20' );
$rpc->query( 'wp.getComments', 0, $xmlrpc_user, $xmlrpc_pass, $filter );
echo '<h1>Approved Comments</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getComments', 999 );
?>
wp.deleteComment
Calls the function wp_deleteComment($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $comment_id—A required integer of the comment ID of the comment you would like to delete.
This function returns true on success.
wp.editComment
Calls the function wp_editComment($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $comment_id—A required integer of the comment ID of the comment you would like to update.
§ $content—A required array of comment keys and values. The array can contain keys for author, author_url, author_email, content, date_created_gmt, and/or status.
This function returns true on success.
wp.newComment
Calls the function wp_newComment($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_id—A required integer of the post ID of the post to which you would like to add a new comment.
§ $content—A required array of comment keys and values. The array can contain keys for author, author_url, author_email, content, date_created_gmt, and/or status.
This function returns the new comment ID.
wp.getMediaLibrary
Calls the function wp_getMediaLibrary($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $filter—An optional array of filterable attachment values. The array can contain keys for parent_id, mime_type, offset, and/or number.
This function returns an array of attachments with the same individual attachment data that gets returned with the getMediaItem() function:
<?php
function bwawwp_xmlrpc_getMediaLibrary() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT($xmlrpc_url);
$filter = array('number' => '20');
$rpc->query('wp.getMediaLibrary', 0, $xmlrpc_user, $xmlrpc_pass, $filter);
echo '<h1>Media Library</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getMediaLibrary', 999 );
?>
wp.getMediaItem
Calls the function wp_getMediaItem($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $attachment_id—A required integer of the attachment ID of the attachment you would like to retrieve.
This function returns an array of attachment data:
§ date_created_gmt
§ parent
§ link
§ thumbnail
§ title
§ caption
§ description
§ metadata
wp.uploadFile
Calls mw_newMediaObject($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $data—A required array of file data of the file you are uploading. The array must contain keys for name, type, and bits. The array can contain post_id if you want to attach to an uploaded file to a post and overwrite if you want to overwrite an existing file with the same name.
This function returns an array of file data:
<?php
function bwawwp_xmlrpc_uploadFile() {
global $xmlrpc_url, $xmlrpc_user, $xmlrpc_pass;
$rpc = new IXR_CLIENT( $xmlrpc_url );
// grab an image
$args = array(
'post_type' => 'attachment',
'post_status' => 'any',
'posts_per_page' => 1,
'post_mime_type' => 'image/jpeg'
);
$posts = get_posts( $args );
$name = basename( $posts[0]->post_title );
$type = $posts[0]->post_mime_type;
$bits = file_get_contents( $posts[0]->guid );
$data = array(
'name' => $name,
'type' => $type,
'bits' => new IXR_Base64( $bits ),
'overwrite' => true
);
$rpc->query( 'wp.uploadFile', 0, $xmlrpc_user, $xmlrpc_pass, $data );
echo '<h1>Uploaded File</h1>';
echo '<pre>';
print_r( $rpc->getResponse() );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_uploadFile', 999 );
?>
wp.getPostFormats
Calls the function wp_getPostFormats($args) and requires an array:
§ $blog_id
§ $username
§ $password
This function returns an array of post formats used by the site.
wp.getPostType
Calls the function wp_getPostType($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $post_type—A required string of the post type you would like to retrieve data for.
§ $fields—An optional array of post type fields you would like to return. The array can contain keys for labels, description, capability_type, cap, map_meta_cap, hierarchical, menu_position, taxonomies, and/or supports.
This function returns an array of the post type fields you specified with the $fields parameter.
wp.getPostTypes
Calls the function wp_getPostTypes($args) and requires an array:
§ $blog_id
§ $username
§ $password
§ $filter—An optional array of filterable post type field values. The array can contain keys for any post type fields; see the function get_post_types(). The default is public → true.
§ $fields—An optional array of post type fields you would like to return. The array can contain keys for labels, description, capability_type, cap, map_meta_cap, hierarchical, menu_position, taxonomies, and/or supports.
This function returns an array of the post types with the fields you specified with the $fields parameter:
<?php
function bwawwp_xmlrpc_getPostTypes() {
$rpc = new IXR_CLIENT( 'http://messenlehner.com/xmlrpc.php' );
$filter = array( 'public' => 1 );
$rpc->query( 'wp.getPostTypes', 0, $username, $password, $filter );
$response = $rpc->getResponse();
echo '<h1>Post Types</h1>';
echo '<pre>';
print_r( $response );
echo '</pre>';
exit();
}
add_action( 'init', 'bwawwp_xmlrpc_getPostTypes', 999 );
?>
The wp_xmlrpc_server class is located in /wp-includes/class-wp-xmlrpc-server.php. If you take a look at the class, you can see all of the available functions for interacting with WordPress data.