Using own library in your extensions

There are several approaches how to register your own library with Joomla's autoloader and then use it in your extension. All these approaches are based on the JLoader class. For this tutorial we consider that your library is located in the /libraries/mylib folder.

Discovering Classes

Classes in a folder that follow a naming convention can be registered collectively with JLoader's discover() method. The discover method looks at the file names in a folder and registers classes based on those names. Additional arguments can be used to update the class register and recurse into sub-folders.

// Register all files in the /libraries/mylib folder as classes with a name like:  MyLib<Filename>
JLoader::discover('Mylib', JPATH_LIBRARIES . '/mylib');

As you can see this method is working if you follow special naming convention:

• /mylib/user.php will be equal to MylibUser
• /mylib/userhelper.php will be equal to MylibUserHelper

The Prefix Loader

Since Joomla Platform 12.1 (Joomla! CMS 3+), there is the ability to register where the auto-loader will look based on a class prefix (previously only the "J" prefix was supported, bound to the /libraries/joomla folder). This is done with the registerPrefix() method and allows for several scenarios:

• A developer can register the prefix of custom classes, and a root path to allow the auto-loader to find them.
• A developer can register an extra path for an existing prefix (for example, this allows the Joomla CMS to have custom libraries but still using the "J" prefix).
• A developer can register a force override for a prefix. This could be used to completely override the core classes with a custom replacement.

Convention

The class name must be in camel case and each segment of the name will represent a folder path where the last segment of the name is the name of the class file. If there is only one part to the class name, the auto-loader will look for the file in a folder of the same name. Folder names must be in lower case.

Examples:

• PrefixUserModel class should be located in PATH_TO_PREFIX/user/model.php
• PrefixUser class should be located in PATH_TO_PREFIX/user/user.php

Our scenario examples:

• MylibUserHelper class should be located in /libraries/mylib/user/helper.php
• MylibUser class should be located in /libraries/mylib/user/user.php

There is no limit to the depth to which the auto-loader will search, providing it forms a valid path based on the camel case natural of the class name. Note that while acronyms and names such as HTML, XML and MySQL have a standard presention in text, such terms should observe camel case rules programmatically ("HTML" becomes "Html", "XML" becomes "Xml" and so on).

Usage

// Tell the auto-loader to look for classes starting with "Mylib" in a specific folder.
JLoader::registerPrefix('Mylib', JPATH_LIBRARIES . '/mylib');

// Tell the auto-loader to also look in the /libraries/cms folder for "J" prefixed classes.
JLoader::registerPrefix('J', JPATH_PLATFORM . '/cms');

// Tell the auto-loader to reset the "J" prefix and point it to a custom fork of the platform.
JLoader::registerPrefix('J', '/my/platform/fork', true);

Accessing library from any place

To access our library from any place of an application we should create a system plugin which will register our library with the JLoader. This plugin should fire on onAfterInitialise event:

Manifest file

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="system" method="upgrade">
    <name>System - Mylib</name>
    <author>Joomla! Project</author>
    <creationDate>March 2013</creationDate>
    <copyright>Copyright (C) 2005 - 2013 Open Source Matters. All rights reserved.</copyright>
    <license>GNU General Public License version 2 or later.</license>
    <authorEmail>admin@joomla.org</authorEmail>
    <authorUrl>www.joomla.org</authorUrl>
    <version>1.0.0</version>
    <description>Simple example plugin to register custom library.</description>

    <files>
        <filename plugin="mylib">mylib.php</filename>
        <filename>index.html</filename>
    </files>
</extension>

Plugin file

<?php
/**
 * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
 * @license     GNU General Public License version 2 or later.
 */

defined('_JEXEC') or die;

/**
 * Mylib plugin class.
 *
 * @package     Joomla.plugin
 * @subpackage  System.mylib
 */
class plgSystemMylib extends JPlugin
{
    /**
     * Method to register custom library.
     *
     * return  void
     */
    public function onAfterInitialise()
    {
        JLoader::registerPrefix('Mylib', JPATH_LIBRARIES . '/mylib');
    }
}

Now you will be able to call classes from your library (located in /libraries/mylib) from any component, module or plugin.