Joomla! Documentation™

XML-RPC changes in J2.5

This is a copy of the message send to the Google Groups "Joomla! CMS Development" group.

On Wed, Apr 8, 2009 at 10:43 AM, Louis Landry wrote:

What we have done is to remove the separate XMLRPC application from the trunk and made way for a new method of handling service requests. It is no longer necessary to have an XMLRPC plugin group to handle XMLRPC requests that end up proxying the logic and data structures within a component anyway.

In your component, we'll say com_foo, designed using the MVC pattern you may have a need to handle lots of "task-based" requests. Things like edit, save, delete, etc. Often, when this happens it is helpful to use more than one controller to break out code sections to smaller, more maintainable parts. Doing this you might have the following structure:

/components/com_foo/
/components/com_foo/controllers/c1.php
/components/com_foo/controllers/c2.php

/components/com_foo/models/

...
/components/com_foo/views/
...
/components/com_foo/controller.php
/components/com_foo/foo.php

This allows you to segment out grouped tasks into separate controllers. In this example you can see that there is a c1.php controller and a c2.php controller.

In 1.5, you would need to have some logic in your base foo.php to determine which controller gets included and executed based on some request variables, etc.

In 2.5, there is a new convention based way of achieving this behavior as well as adding in service requests.

/components/com_foo/
/components/com_foo/controllers/c1.php
/components/com_foo/controllers/c1.xmlrpc.php
/components/com_foo/controllers/c1.json.php
/components/com_foo/controllers/c2.php

/components/com_foo/models/

...
/components/com_foo/views/
...
/components/com_foo/controller.php
/components/com_foo/foo.php

If you have a look at this version of the com_foo component, you will notice a couple of extra files. In the controllers folder you now have c1.xmlrpc.php and c1.json.php. These controllers are where the logic to handle service calls to the c1 controller tasks would live. Lets assume that the controller class in c1.php has only one method/task, bar.

class FooControllerC1 extends JController
{
    function bar()
    {
        echo 'Hello World';


        // Exit the application.
    }
}

If you wanted to allow an XMLRPC service request for this controller, you would simply create c1.xmlrpc.php as shown in the second folder structure and define the methods/tasks that you want to handle:

class FooControllerC1 extends JController
{
    function bar()
    {
        // Get an XMLRPC server object and de-serialize the request payload.


        // Run method logic.


        // Build XMLRPC response payload.


        // Output XMLRPC response payload.


        // Exit the application.
    }

}

You will also notice in the second folder structure, that there is a c1.json.php. As you can imagine, this class is pretty straightforward as well.

class FooControllerC1 extends JController
{
    function bar()
    {
        echo json_encode('Hello World');


        // Exit the application.
    }
}

As you can see, controllers can be built up to handle as many different types of service requests as you want for whatever types of tasks you want, within your standard component folders. It would also be trivial to turn services on/off with simple conditional statements and component configuration settings.

The standard way of requesting these various controllers/methods by convention is something like:

   index.php?option=com_foo&task={CONTROLLER}.{TASK}&format={SERVICE_TYPE}

So, if we wanted to send a request to the bar method in controller c1 via XMLRPC the URL to use would simply be:

    index.php?option=com_foo&task=c1.bar&format=xmlrpc 

Similarly if we want the JSON service protocol:

    index.php?option=com_foo&task=c1.bar&format=json 

If your site is using multi-language support, add the language code to the URL or you will not be able to read the post raw data from (http://input):

    index.php/en?option=com_foo&task=c1.bar&format=xmlrpc 

Just to use the base c1.php controller you remove the &format={SERVICE_TYPE} variable from the request URL.

In Joomla 2.5, JController has a new getInstance() method that handles this dispatching of the correct controllers for you based on the request variables.

We most certainly are not getting rid of the ability to utilize XMLRPC in your components, we are simply trying to make it more consistent and cohesive with the rest of the system.

Hope that helps, Louis

Example component

Example component created to test XML-RPC web services: [1] (Thanks User:Aduran)