Using own library in your extensions
From Joomla! Documentation
There are several approaches to registering 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, assume 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 working by following the special naming convention:
/mylib/user.php
will be equal toMylibUser
/mylib/userhelper.php
will be equal toMylibUserHelper
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 CamelCase 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 inPATH_TO_PREFIX/user/model.php
PrefixUser
class should be located inPATH_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 CamelCase natural of the class name. Note that while acronyms and names such as HTML, XML and MySQL have a standard presentation in text, such terms should observe CamelCase 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);
Note on registerPrefix
For Joomla CMS 2.5, the prefix cannot start with the same letter. The system will try to load the first matched. For example, if we register prefix JM, as J prefix exists, the JLoader will find J prefix. When it searches for the class in the registered path of J, no class will be found.
Namespace Loader
As of Joomla CMS v3.1.2, the core autoloader has support for autoloading PSR-0 style namespaced libraries. (You can study PHP namespaces here.) If you only support Joomla on PHP 5.3+ (which you do if you only support Joomla CMS v3.x or greater), you can utilize code that uses native PHP namespaces. In accordance with PSR-0 rules, the directory and file casing must match that of the PHP namespace and class.
Example
MyLib\User\UserHelper
class must be located inJPATH_LIBRARIES/src/MyLib/User/UserHelper.php
Usage
// Tell the auto-loader to look for namespaced classes starting with MyLib in the JPATH_LIBRARIES/src directory
JLoader::registerNamespace('MyLib', JPATH_LIBRARIES . '/src');
Accessing the Library from Anywhere
To access our library from any place in the application, 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.