Joomla! 1.5 – Using JFactory and jimport() sensibly

David raised an interesting question in his very first post on the Joomla! forums, about using jimport() for classes that are deeply nested in the framework’s directory structure. The answer is simple: don’t load those classes. Problem solved! Right ?

Well, right, but why can’t you load them?

What is jimport?

Joomla!’s framework is located in /libraries/joomla. Instead of using require_once to load those files, you use the jimport() function. It uses a syntax with dots: to load /libraries/joomla/utilities/utility.php, you write jimport(‘joomla.utilities.utility’); The JUtility class is now available for you to use in your code.

echo JUtility::dump($myvar);
// dumps the contents of $myvar to the screen

The same thing goes for files that are nested deeper, like /libraries/joomla/application/component/view.php:

class MycomponentViewItems extends JView
{ /* ... */ }

In J!1.5RC4, jimport got a little smarter. When using PHP5, instead of loading the file right away, the filename and the classname are registered, and loading is deferred until the class is actually needed. So when looking at our first example:

// at this point, utility.php is not yet loaded

echo JUtility::dump($myvar);
// when the JUtility class is needed, utility.php is loaded.

(This may look a little unnecessary: why not load the file right away, if we’re going to need it anyway? For now, let me just say that there are a number of scenario’s where this is a good idea, like in legacy mode. We’ll deal with those in another blog post.)

So what’s happening? jimport looks at the last part of the ‘joomla.utilities.utility’ string, adds a ‘J’ prefix, and registers the resulting ‘JUtility’ as the class name for utility.php. When you use JUtility, in the example above, or in MyClass extends JUtility, or in class_exists(‘JUtility’), the file utility.php is loaded.

The problem

David wonders in his post what happens when you want to use JSessionStorageDatabase, located in /libraries/joomla/session/storage/database.php. According to what I wrote above, you need to use jimport(‘’). However, this would register JDatabase as the classname, but in fact it should be JSessionStorageDatabase. Trying to use the class results in an error, because the file containing it isn’t being loaded. In reality, we never need to load classes like JSessionStorageDatabase in our code. Joomla! has factories for that.

About JFactory

Your code doesn’t have to worry about how to instantiate certain objects. The specifics are all handled by JFactory and a bunch of getInstance methods. Eg. JFactory::getDBO() might give you a JDatabaseMySQL object or a JDatabaseMySQLi object, or perhaps even a JDatabasePostgresSQL object in a later version. JFactory::getSession() gives you a JSession object. This object contains a JSessionStorage object, which can be JSessionStorageDatabase or JSessionStorageApc or any other. The point is: you don’t need to worry about it. JFactory (and JSession::getInstance(), JDatabase::getInstance(), …) take care of all that.

The only classes you need to use jimport for are classes with a single name like JFoo, not classes like JFooBar. And most importantly, always look at JFactory first, to see if you can get what you need there.

Read more

DOCman – Category versus document permissions

There’s been a lot of confusion lately about category permissions in DOCman. Many people are trying to use categories in the same way they are using documents. Let me try to clear up the misunderstanding.

DOCman uses Joomla!’s category system. This design decision dates back from the Mambo days (before Joomla! was born — yes, DOCman has been around for a while!) As you may know, categories in Joomla! have very limited access control, just like everything else: you can assign them to the Public, the Registered or the Special group. You can think of a category as just a box, with a label on it. But as you know, a label doesn’t prevent you from opening the box.

Documents on the other hand is where the cool stuff happens. Documents have two sets(1) of permissions: one for viewers, or users who can download the document, and one for maintainers, or users who can edit and update documents. The viewer and maintainer can be set to either

  • a Joomla! group (Author, Editor etc…)
  • an individual user
  • a custom group (a collection of users)

These effectively control access to a document. If the user is not in one of these groups, he can’t access the document.

The important thing to remember is that permissions in DOCman are controlled at the document level, not at the category level. Setting a category to Special or unpublishing it, will hide the category, but will not prevent access to the documents inside the category. You need to set the permissions of the document itself.

Golden rule:
Categories are just boxes.
The documents are the ones that have the locks.

(1) Actually there is a third permission, for the creator, which is the user who uploaded the document. This creator can have viewer or maintainer rights as well, even if he is not in the viewer or maintainer group. You can’t change the creator of a document. By turning on Override View or Override Maintain in Configuration -> Permissions, you can give all creators the rights to their own documents.

Read more

Optimize your Joomla! 1.5 component installer

Most developers know that a component can have an install.componentname.php, containing a com_install() function with your custom instructions. For example, copying files to different locations or inserting localized sample data. When these instructions fail, you can of course print a message about that. The result however, is that the user sees both your ‘Failed’ message, as well as Joomla!’s ‘Success’ message. Users find this is very confusing.

The solution is actually extemely simple: inside com_install(), you need to return false. This tells the installer that your custom script has failed, and a relevant error message will be displayed. There is an added benefit as well: the installer will perform a rollback, removing all the files in the process.

By the way: I’m blogging live from the Joomlatools Bug Squashing event in Brussels!

Read more

Hello world! at the Joomlatools Blog

Joomlatools blog is launched and it has already two entries on it! … Yay!

We are happy to be finally up and buzzing in the blogosphere, a great place to be! We will be blogging about what’s cooking in the Joomlasphere and especially about the things we are doing at Joomlatools.

Exciting stuff happening behind the scenes. We have a few surprises cooking. It’s going to be an great start of 2008, hint. Stay tuned for more information !

Read more