An Introduction to the Joomla! 1.6 ACL API

Tuesday, 02 June 2009 20:24

There's been a lot of buzz about the new Joomla! 1.6 ACL system so I thought this would be a good opportunity to write up a quick introduction about how to use the new API in your extensions. We invested a lot of time and energy designing the 1.6 API and we are proud of the result because it offers a good balance between simplicity and power.

The Basic Rules

The most important thing to understand about the Joomla! 1.6 ACL system is the three (at the time of this writing) types of rules.

Type 1: Action

At it's most basic, a type 1 rule is a simple action like "manage" or "log in" or "edit". A type 1 rule is characterized as an action that is not being applied to a particular asset. For example, a common type 1 rule in Joomla! 1.6 is "manage" which is used to control who can access the administrator interface for a particular component.

Type 2: Action on an Asset

A type 2 rule is similar to a type 1 rule except that it is linked to exactly one asset. An asset could be an article or a contact or a web link or whatever. A type 2 rule is defined as a rule that links one action and one asset. If I want to control who can edit a particular piece of content, I would use a type 2 rule.

Type 3: View

A type 3 rule is specifically designed for viewing permissions. Type 3 rules are handled somewhat differently to make the system as fast as possible as users spend the vast majority of their time just browsing a web site. Type 3 rules are handled almost exactly like the Joomla! 1.5 `access` columns that most database tables utilize.

Performing Access Checks

View Permissions

If you've built any Joomla! extensions before you will probably be familiar with the JUser::aid variable that is used to check if a user is authorized to view access something. View permission checks in Joomla! 1.6 are very similar to the view permission checks in Joomla! 1.5. In Joomla! 1.5 you might do something like:

 
$db   = &JFactory::getDBO();
$user = &JFactory::getUser();
 
$query = 'SELECT *' . 
    ' FROM `#__content`' .
    ' WHERE `access` <= ' . (int)$user->get('aid');
 
$db->setQuery($query);
...
 

The concepts are exactly the same except that in Joomla! 1.5, a user was limited to one access level (Public, Registered, or Special) whereas in Joomla! 1.6, a user can be in one or more access levels. In Joomla! 1.6, you would do something like:

 
$db     = &JFactory::getDBO();
$user   = &JFactory::getUser();
$groups = implode(',', $user->authorisedLevels());
 
$query = 'SELECT *' . 
    ' FROM `#__content`' .
    ' WHERE `access` IN ('.$groups.')';
 
$db->setQuery($query);
...
 

That's it! That is all that you have to do to implement basic viewing access controls in your Joomla! 1.6 extensions. Pretty simple right? Right.

Action Permissions

Not that we've got the basic viewing permissions out of the way, let's take a quick look at performing a basic type 1 access check. Let's say we want to see whether a user is authorized to manage com_content which is to say, "should they have access to the com_content administrator interface?" I absolutely love how easy it is to perform these types of access checks:

 
// Get the user object.
$user = &JFactory::getUser();
 
// Check if the user is authorized to manage com_content.
if (!$user->authorise('com_content.manage')) {
    JError::raiseError(403, JText::_('ALERTNOTAUTH'));
    return false;
}
 

Done! We just performed an access check to see if the user has permission to manage com_content based on the configured access levels. You can even do it with less code in Joomla! 1.6 as we will only be supporting PHP 5.2 and up which means you can use chaining to reduce that to:

 
// Check if the user is authorized to manage com_content.
if (!$JFactory::getUser()->authorise('com_content.manage')) {
    JError::raiseError(403, JText::_('ALERTNOTAUTH'));
    return false;
}
 

Pretty cool huh? Yep!

Well, that is going to conclude this article. I'll dig in a little deeper next time to look at how to use the new ACL system to check if a user is authorized to perform an action on a specific asset and maybe we'll take a look at how to set up the ACL system for your custom extensions. Enjoy!