Joomla! Documentation™

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

Depuis Joomla Platform 12.1 (Joomla! CMS 3+), il est possible d’enregistrer le chargeur automatique en fonction d’un préfixe de classe (auparavant, seul le préfixe "J" était pris en charge, lié au dossier /libraries/joomla). Ceci s'effectue avec la méthode registerPrefix() et permet plusieurs scénarios:

• 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

Le 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

Nos exemples de scénario:

• MylibUserHelper class doit être définie dans /libraries/mylib/user/helper.php
• MylibUser class doit être définie dans /libraries/mylib/user/user.php

Il n'y a pas de limite à la profondeur de recherche du chargeur automatique, à condition qu'il constitue un chemin valide basé sur le cas naturel des camel case du nom de la classe. Notez que bien que les acronymes et les noms tels que HTML, XML et MySQL aient une présence standard dans le texte, ces termes doivent respecter les règles de cas de camel case en programmation ("HTML" devient "Html", "XML" devient "Xml", etc.).

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 sur registerPrefix

Pour Joomla CMS 2.5, le préfixe ne peut pas commencer par la même lettre, sinon le premier correspondant tentera de se charger. Par exemple, si nous enregistrons le préfixe 'JM', comme le préfixe 'J' existe, JLoader trouvera le préfixe 'J'. Lorsqu'il tente de rechercher une classe dans le chemin d'accès enregistré de 'J', aucune classe n'est trouvée.

Namespace Loader

À compter de la version 3.1.2 d u CMS Joomlaǃ, l'autoloader principal prend en charge le chargement automatique de bibliothèques d'espace de noms de style PSR-0. (Pour en savoir plus, consultez cet article sur les espaces de noms PHP). Si vous ne supportez que Joomla sur PHP 5.3+ (ce que vous faites si vous ne supportez que Joomla CMS v3.x ou supérieur), vous pouvez utiliser un code utilisant des espaces de noms PHP natifs.Selon les règles PSR-0, le répertoire et la structure de fichier doivent correspondre à ceux de l’espace de noms et de la classe PHP.

Exemple

• MyLib\User\UserHelper la class doit être définie dans 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');

Accéder à la bibliothèque de n’importe quel endroit

Pour accéder à notre bibliothèque à partir de n'importe quel endroit d'une application, nous devons créer un plug-in système qui enregistrera notre bibliothèque avec JLoader. Ce plugin doit se déclencher lors de l'événement onAfterInitialise:

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');
    }
}

Vous pourrez maintenant appeler des classes de votre bibliothèque (situées dans /libraries/mylib) à partir de n'importe quel composant, module ou plug-in.