Uploading Pictures via XML-RPC and PHP to WordPress

Let's say you're familiar with the XML-RPC protocol and how it works, even in WordPress, and you've used it before. Adding posts, deleting pages, etc. All is well with text but what happens when you want to send files like pictures to WordPress?

In this tutorial we are going to take a look at a very easy way to send a picture over to WordPress, so that it shows up in the media section of the admin panel. We are going to use PHP to send this picture, so that you can use this code for a WordPress plugin, theme, or even just plain PHP, just like in our example.

Step 1 The Plan

Just to give a general idea of what we are going to do and how we are going to do it, I'm going to start this tutorial with a plan. Basically we are going to make a PHP script that uploads a file (a jpeg image to be more precise) to a local WordPress installation.

We are going to use a PHP library that creates the XML-RPC client in PHP, which we are going to use to connect to the WordPress XML-RPC server and send our data. This client is a PHP library called "The Incutio XML-RPC Library for PHP" and can be found at scripts.incutio.com

Please note: This example is for demonstration purposes of this tutorial only and is a very basic and straight-forward example

Step 2 Preparing the Environment

For this tutorial, the first thing you need is a working version of WordPress on an Apache Server with PHP and MySQL installed. You can also have this locally, which I recommend and is actually the example we are going to use in this tutorial.

Another thing you need is the XML-RPC library that we are using for this tutorial. The Library is free, under a BSD Licence, and can be found on scripts.incutio.com

The library is actually just a PHP file named IXR_Library.php that we are going to use in this tutorial. The next thing you need to do is to create a directory in your htdocs (or web root) folder of your local server installation where you will copy the IXR_Library.php file and also create a index.php file next to it. The index.php file needs to be empty for now.

The most important thing we need to do in the WordPress installation is activating the XML-RPC service. WordPress has this deactivated by default so we need to go into the settings in admin-panel and activate it. To do this, go to Settings -> Writing and just under the Remote Publishing title you will find XML-RPC with a checkbox right next to it that is deselected by default. Select it and click save changes.

Now, we are able to communicate to the XML-RPC Server that WordPress has built in.

Step 3 The Code, Explained

Here comes the fun part so let's get right to it! Open the index.php file mentioned earlier with your favorite code editor.

Including the Library

The first thing we need to do is include the library file we just downloaded so that we may use it later. So we edit the index.php file and we add the following code (don't forget to start with a PHP tag like in the example):

<?php
include_once('IXR_Library.php');
?>

This will basically cover all that we need to use for our script to work. In a nutshell, we are going to use the client part of the library we just included. We will do this in a moment.

Reading the Image (Jpeg File)

Because we need to send an image (a jpg file) over to WordPress, we need to send it somehow. The solution is sending it in a bits format, just like you will see later, the XML-RPC server function requests it. But to send it like that we need to convert it's contents into bits, and to do that we need to get its content. The file (any jpg picture file, we will name it test.jpg), will be placed right next to the index.php file (in the same directory) and in this next part, we are going to read its contents and store them in a variable for later use.

$myFile = "test.jpg";
$fh = fopen($myFile, 'r');
$fs = filesize($myFile); 
$theData = fread($fh, $fs);
fclose($fh);

What the above code does, first, it creates a new variable named $myfile with the string value of the name of the file, that, because it is in the same folder, does not require any other path information stuck to it, just the name, in this case, test.php.

Next we need to open the file, so we do this with the PHP function fopen, that we use with the first parameter of the previous variable, $myFile and the second parameter another string that indicates the operation we are going to make on the file. The string value of r means reading. We will add the result of the opened file to the variable $fh.

Then, because we require the file contents length, we will create the variable $fs with the value returned by the PHP function $filesize, function that uses the parameter, $myFile

Finally, we get to the reading part, where we give the variable $theData the value returned by the function that does the reading, namely fread. This function uses two parameters, the first is the previously opened file variable ($fh) and the second is the previously set file size ($fs).

Lastly, we close the opened file using the function fclose and its parameter $fh. At this point, we have the contents of the jpg file, that we are going to send to the XML-RPC server of WordPress.

Creating the XML-RPC Client

In this next part we will use the library we just imported to connect to our WordPress's installation XML-RPC server. To do this we will need the following 3 variables:

$usr (with the admin panel user name), $pwd(the admin panel password) and
$xmlrpc (the XML-RPC server path). Note, the XML-RPC server path is made out of the base WordPress installation url + the xmlprc.php file at the end after the slash.

$usr = 'admin';
$pwd = 'admin';
$xmlrpc = 'http://localhost/wordpress/xmlrpc.php';
$client = new IXR_Client($xmlrpc);

Next we need to create the call to the server. For that we will use the URL string we just created and the IXR_Client class that we inherit from the imported library file. At this point, the variable $client is declared as a new client for that link and all operations are going to be done using it.

This next part is optional, but just in case you want to, you can activate debugging like so:

$client->debug = true;

If you activate it, you will get a clearer view of what's going on if something goes wrong.

Placing the Data in Its Place

Before we send the data we must organize and format it properly, and because of the way we are required to send it, we must create an array with all the values. Let's name this array $params and give it the following values:

$params = array('name' => 'test.jpg', 'type' => 'image/jpg', 'bits' => new IXR_Base64($theData), 'overwrite' => false);

First, we need to give the array index name of name the value of 'test.jpg, as this is going to be the name of the file. After that we have the index name type, that we give the value of image/jpg. This is the file type that we are uploading. Then we have the index named bits that is actually the file we need to send. Now, WordPress XML-RPC API requires this value to be sent as base 64 bits. To do this correctly we will use the variable $theData, but we will need to run it through the class IXR_Base64 so that it is encoded accordingly into base64 bits. It's very important that the base64 encoding is formatted correctly in order for the file to be successfully sent to the server as it was requested. There are different Base64 encodings and if the incorrect one is used there will inevitably be an error. The IXR_Base64 class used in the above example is converting the content of the file just as the server requires it to. Lastly, the index type overwrite is set to false, giving the property of false to the option of overwriting existing files with the same name.

Sending the Data via XML-RPC

The last thing we need to do for this script to work is to send the data to WordPress by activating a request from the $client variable like so:

$res = $client->query('wp.uploadFile',1, $usr, $pwd, $params);

The $res variable is given the result of the query function called from inside the $client variable that represents the originally declared and initiated XML-RPC client implementation. Basically we are sending a request to the server. The server will receive a request with the following parameters:

wp.uploadFile - the required service function that we are calling and using to upload the file
1 - the blog ID (each WordPress blog has an ID, the default is 1
$usr - The user name variable previously declared.
$pwd - The password variable previously declared.
$params - The array of parameters that we just talked about.

The Full Code

All of the above code put together would look something like this:

<?php
include('IXR_Library.php');
$myFile = "test.jpg";
$fh = fopen($myFile, 'r');
$fs = filesize($myFile);
$theData = fread($fh, $fs);
fclose($fh);

$usr = 'admin';
$pwd = 'admin';
$xmlrpc = 'http://localhost/wordpress/xmlrpc.php';
$client = new IXR_Client($xmlrpc);

$client->debug = true;
$params = array('name' => 'test.jpg', 'type' => 'image/jpg', 'bits' => new IXR_Base64($theData), 'overwrite' => false);
$res = $client->query('wp.uploadFile',1, $usr, $pwd, $params);
?>

Conclusion

It's not hard to implement such a client, but because sometimes the code you are supposed to build is specific, you are required to know what you are doing so that you can achieve the desired effect. The XML-RPC client implementation in PHP for a WordPress XML-RPC upload file server request is such an example. If the data you are sending is not properly formatted, it might not get accepted. This example is just a few lines of code but it is very specific. The same client can be used to make any other kind of
request to WordPress using different XML-RPC request functions with the appropriate parameters.

HIGHLIGHTS OF THE DAY