How To Package Joomla Libraries

: Written by Joseph LeBlanc Joseph LeBlanc; Published: 13 October 2011 13 October 2011

You’ve seen it before: the monster Joomla installation package. It’s a giant component, several side modules, and at least one plugin. Once you dig through the code, you notice the plugin isn’t even responding to events: it’s merely there to load up code shared by the other extensions.

Fortunately, Joomla 1.6 and higher provide a better way of handling this. Reusable code libraries can now be installed into the libraries folder without creating extraneous plugins. Just like any other extension in Joomla, a library is packaged as a .zip file with an XML manifest to guide the installation.

If you’ve created Joomla XML manifest files before, creating one for a library is straightforward. The main thing you need to keep in mind is the added <libraryname> element. This element is the “system name” for the library: make sure it is valid as a directory name across platforms. When coming up with this “system name,” avoid spaces, capital letters, and special characters. Upon installation, Joomla will create a subfolder of libraries using name specified by <libraryname>. Contrast this with the <name> element, which identifies an extension with a human readable name.

<name>Missing Tools!</name>
<libraryname>missing</libraryname>

<files> element will be copied into the library’s folder. Just like any other extension, you must list every folder and file to be copied. To keep maintenance work to a minimum, organize your code inside of folders. This way, the only time you have to update the <files> portion of the manifest is when you add more folders to the base level.

<files>
    <folder>smart</folder>
</files>

Besides the <libraryname> element, the name of your XML file is important. Unlike other extensions, all of the library manifest files are stored together in administrator/manifests/libraries. If you choose manifest.xml as the name of your manifest file, it will get overwritten if another library chooses to do the same. To avoid this conflict, name the file after the value of the <libraryname> element. So if your library is named missing, name your manifest file missing.xml.

Place the manifest file inside of the folder with the code you want to use. Note that the method attribute can be set to upgrade on the <extension> element. Using upgrade allows site administrators to install newer copies of your library directly on top of older ones.

<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="1.7.0">

Finally, you will want to include the author’s name, creation date, copyright, license, email, website, version, and description. This information is the same as it is for any other extension. The complete XML file will look similar to this:

<?xml version="1.0" encoding="utf-8"?>
<extension type="library" method="upgrade" version="1.7.0">
    <name>Missing Tools!</name>
    <libraryname>missing</libraryname>
    <author>Joseph LeBlanc</author>
    <creationDate>October 2011</creationDate>
    <copyright>Copyright (C) 2011</copyright>
    <license>

    https://www.gnu.org/licenses/gpl-2.0.html GNU/GPL

    </license>
    <authorEmail>This email address is being protected from spambots. You need JavaScript enabled to view it.</authorEmail>
    <authorUrl>www.jlleblanc.com</authorUrl>
    <version>1.0</version>
    <description>

    Tools you need to scratch the itches you have

    </description>
    <files>
        <folder>smart</folder>
    </files>
</extension>

Aside from the XML manifest, the library will need the PHP code you’re wanting to package. Unless there is a specific reason for not doing so (such as a legacy codebase), place all of your code in PHP classes.

The core joomla library uses the prefix ‘J’ for all PHP class names. This prefix helps avoid namespace conflicts with other PHP classes, while maintaining compatibility with PHP 5.2. For your library classes, use the name of your library as the class name prefix.

In this case, we have the missing library with the folder smart and the file drops.php; this makes MissingSmartDrops a preferable class name. Although you can name your class as you wish, this convention reduces the risk of duplicate names. It also aids other developers in navigating your library.

<?php
defined( '_JEXEC' ) or die;
class MissingSmartDrops
{
    // ...
    // ...
    // ...
}

Create a .zip file of the folder with your manifest file and code. Once the .zip file is ready, install it into Joomla as you would any other extension. The library is now available for use in any extension.

Passing a dot-separated path into jimport() loads the library if it is not already in memory. Libraries are not loaded until explicitly requested through jimport(), so installing additional libraries does not create direct overhead. Once loaded, you can either call class functions statically or instantiate the classes as objects.

<?php
defined( '_JEXEC' ) or die;
jimport('missing.smart.drops');
$colors = array('Red', 'Yellow', 'Blue');
$color_drop = new MissingSmartDrops('color', $colors);
echo $color_drop;

Installable libraries make reusable code in Joomla a reality. Instead of shoehorning your reusable code into a plugin, package your code as a library. But don’t just package your library: distribute it and work with other developers to reduce code duplication. Together, we can share code and write better extensions for Joomla!

(Also, the missing library package can be downloaded here and forked here. Enjoy!)

The Joomlashack Blog

How To Package Joomla Libraries