Joomla Component Tutorial – Login Authentication From an External App

I wanted to give a quick and dirty tutorial on how to create a Joomla 2.5 component. I’m going to show you how to create a very quick Joomla MVC component…hold the M…hold the V. This is not for the MVC purists out there. Hence quick and dirty.

You should really understand the benefits of the MVC and why that exists before you do any Joomla component development. However I want to break the rules a bit. I should also mention before I get started that the Joomla MVC documentation is pretty good. You can stop reading here and get a nice detailed tutorial from start to finish on how to do Joomla component development. If you haven’t looked here already then you are doing yourself a disservice.

For today, I’m going to show you how to create a quick API for authenticating anyone via a query string. What’s the point of this? Let’s say you have an external program that you want to interface with Joomla. It could be anything, a bug tracking system a mobile device or anything that doesn’t exist in the Joomla framework. So what I plan to do is build an API where an external app can communicate via a query string with the username and password. This API would then authenticate the user if the credentials already exist in Joomla.

I’m actually only going to edit one file (yes, only one)  to create this but in actual fact you need many more files to get this right. If you do this properly you can follow the Joomla MVC tutorial, create the files manually and you’ll have a nice component. But remember the quick and dirty part? I’m going to use a tool to generate the templates of everything I need. It is called the Joomla Component Creator.

Sign up for a free account and it creates the template of what you need. It is way, way, way overkill for what we are doing here today, but trust me you will thank me later for the headache you will receive one day when you realize you mispelled the class name of your component. Boy does that blow.

Once you sign up for an account you just need add a new component, fill in the data of name of the component, author, etc. Then on the right hand side there will be a build component button. You don’t need to add a table or anything else. The build component button will generate a zip file with all the files you need.

This builds all template files you would ever need (and then some). Now let’s edit our component. For my case I created a component called com_test. Open up the file site/controller.php:
// No direct access
defined('_JEXEC') or die;
jimport('joomla.application.component.controller');

class TestController extends JController
{

}

This is simply a class that has been created for you just waiting for you to fill it in. Let’s do that:

class TestController extends JController
{
function __construct() {
// params
$jinput = JFactory::getApplication()->input;
$this->username = $jinput->get('username', '', 'STRING');
$this->password = $jinput->get('password', '', 'STRING');
$this->checkRequiredParameters();
}

{
echo "W00t! Success";
}
}
}

Okay, so let me explain. First of all I use the constructor to retrieve the username and password sent via the query string. All the gory details of retrieving data with JInput can be found here. Why the constructor, you ask? No reason for this example as I could have easily put everything in the execute() function but nice if you ever expand on this.

Next we added a function called checkRequiredParameters(). This simply returns a header with a bad request if an empty username or password are provided. Be sure to expand upon this and check all parameters that you want to use with a query string.

Finally we have the execute() function. If you look at one of the template files generated with the Joomla Component Creator you will see that it actually calls this function. In my case the file is called site/test.php.

Inside the execute() function we use the authenticate function of JAuthentication, check the status and Bob’s your uncle. I’m struggling to find my original reference as Joomla just has some outdated documentation for this. But this SO post really helped me on my way and really deserves the credit.

All done. Let’s test it. Zip up the directory site, admin and test.xml then install in the extensions manager.

Now go to your site and type:

http://www.mysite.com/index.php?option=com_test&username=foo&password=foo

Replace with your site and the proper username and password. Did you get the right message?

I’m sure there may be a more efficient and elegant ways but this is quick. I’d like to see how this can be achieved any faster. From start to finish of this tutorial I’d say it should only take you 5 mins. Remember that this code is crazy bloated but it gets you started. I should also note that this is designed and tested with Joomla 2.5 but I’ve taken into account 3.x (3.1 at that time of this writing) and it should work as well (although untested).

Here at Camcloud we have used this in the past as the basis for mobile devices to communicate with Joomla. Pretty cool, huh? I’m far from an expert so I love to hear your comments and approaches you may have taken yourself.

UPDATE: Thanks to a user comment below it has been verified it works with J!3.x with one slight change to a deprecated API. Replace this line:

if ($response->status != JAUTHENTICATE_STATUS_SUCCESS)

with

if ($response->status != JAuthentication::STATUS_SUCCESS)