Utiliser sa propre bibliothèque dans vos extensions

From Joomla! Documentation

This page is a translated version of the page Using own library in your extensions and the translation is 57% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎Nederlands

Il existe plusieurs approches pour enregistrer votre propre bibliothèque avec l'autoloader de Joomla, puis l'utiliser dans votre extension. Toutes ces approches sont basées sur la classe JLoader . Pour ce tutoriel, nous considérons que votre bibliothèque est située dans le dossier /libraries/mylib.

Découverte des classes

Les classes d'un dossier qui suivent une convention de dénomination peuvent être enregistrées collectivement avec la méthode de recherche JLoader discover(). La méthode de recherche examine les noms de fichiers dans un dossier et enregistre les classes en fonction de ces noms. Des arguments supplémentaires peuvent être utilisés pour mettre à jour le registre de classe et récursivement dans les sous-dossiers.

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

Comme vous pouvez le constater, cette méthode fonctionne si vous suivez une convention de dénomination particulière:

  • /mylib/user.php sera égal à MylibUser
  • /mylib/userhelper.php sera égal à MylibUserHelper

Le Chargeur de Préfixe

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:

  • Un développeur peut enregistrer le préfixe des classes personnalisées et un chemin racine pour permettre au chargeur automatique de les trouver.
  • Un développeur peut enregistrer un chemin supplémentaire pour un préfixe existant (par exemple, cela permet au CMS Joomla d'avoir des bibliothèques personnalisées tout en utilisant le préfixe "J").
  • Un développeur peut enregistrer une substitution de force pour un préfixe. Cela pourrait être utilisé pour remplacer complètement les classes principales par un remplacement personnalisé.

Convention

TLe nom de la classe doit être en camel case et chaque segment du nom représente un chemin de dossier où le dernier segment du nom est le nom du fichier de la classe. S'il n'y a qu'une partie dans le nom de la classe, le chargeur automatique recherchera le fichier dans un dossier du même nom. Les noms de dossier doivent être en minuscule.

Exemples:

  • PrefixUserModel class doit être localisée dans CHEMIN_DU_PREFIX/user/model.php
  • PrefixUser class doit être localisée dans CHEMIN_DU_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).

Utilisation

// 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, prefix cannot start with the same letter, otherwise the first matched will be tried to load. For example if we register prefix 'JM', as 'J' prefix exists so JLoader will find 'J' prefix. When it tries to search for class in the registered path of 'J', no class found.

Namespace Loader

As of Joomla CMS v3.1.2, the core autoloader has had support for autoloading PSR-0 style namespaced libraries. (You can read up on 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), then 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 in JPATH_LIBRARIES/src/MyLib/User/UserHelper.php

Utilisation

// 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 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:

Fichier Manifest

<?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>

Fichier du plugin

<?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.