Usando bibliotecas propias en tus extensiones

From Joomla! Documentation

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

Outdated translations are marked like this.
Other languages:
Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎Nederlands

Hay varias formas de registrar tus propias bibliotecas con el autoloader de Joomla y luego usarlas en tu extensión. Todas estas formas están basadas en la clase JLoader. En este tutorial vamos a asumir que la biblioteca está localizada en la carpeta /libraries/mylib.

Descubrir clases

Las clases en una carpeta que tienen una convención de nomenclatura pueden ser registradas colectivamente con el método discover() de JLoader. El método discover busca los nombres de archivo en una carpeta y registra las clases basado en esos nombres. Argumentos adicionales pueden ser usados para actualizar el registro de clases y buscar en subcarpetas.

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

Como puedes ver este método funciona si tienes una convención especial para los nombres:

  • /mylib/user.php es igual a MylibUser
  • /mylib/userhelper.php es igual a MylibUserHelper

El cargador de prefijos

Dede Joomla Platform 12.1 (Joomla! CMS 3+), es posible registrar donde buscará el autoloader según un prefijo de clase (antes solo el prefijo "J" era permitido, en la carpeta /libraries/joomla). Esto se hace con el método registerPrefix() y permite varios escenarios:

  • Un desarrollador puede registrar el prefijo de clases personalizadas y una ruta raíz para que el autoloader las encuentre.
  • Un desarrollador puede registrar una ruta extra para un prefijo existente (por ejemplo, esto permite al CMS Joomla tener bibliotecas personalizadas aún usando el prefijo "J").
  • Un desarrollador puede registrar una sustitución (override) para un prefijo. Esto podría usarse para sobreescribir completamente las clases del núcleo con un reemplazo personalizado.

Convención

El nombre de la clase debe estar en camel case y cada segmento del nombre representará una carpeta donde el último segmento del nombre es el nombre del archivo de la clase. Si solo hay una parte del nombre de la clase, el autoloader buscará el archivo en una carpeta del mismo nombre. Los nombres de las carpetas deben estar en minúsculas.

"'Ejemplos:"'

  • La clase PrefixUserModel debe estar ubicada en RUTA_DE_PREFIX/user/model.php
  • La clase PrefixUser debe estar ubicada en RUTA_DE_PREFIX/user/user.php

"'Nuestros escenarios ejemplo:"'

  • La clase MylibUserHelper debe estar ubicada en /libraries/mylib/user/helper.php
  • La clase MylibUser debe estar ubicada en /libraries/mylib/user/user.php

No hay límite en la profundidad en la que el autoloader debe buscar, mientras sea una ruta válida en camel case del nombre de la clase. Ten en cuenta que los acrónimos y nombres tales como HTML, XML y MySQL tienen una presentación estándar en texto, dichos términos deberían seguir las reglas de camel case de forma programática ("HTML" se convierte en "Html", "XML" se convierte en "Xml", etc).

Uso

// 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);

Nota en registerPrefix

En Joomla CMS 2.5, los prefijos no pueden iniciar con la misma letra, de lo contrario se intentará cargar el primero que coincida. Por ejemplo, si registramos el prefijo 'JM', y teniendo en cuenta que el prefijo 'J' ya existe, JLoader encontrará el prefijo 'J' y no el 'JM'. Cuando intente cargar clases en la ruta registrada de 'J', no encontrará ninguna.

Cargador de namespaces

A partir de Joomla CMS v3.1.2, el autoloader del núcleo es compatible con la autocarga de bibliotecas con namespace estilo PSR-0. (Puedes leer sobre namespaces en PHP aquí). Si solo utilizas Joomla en PHP 5.3+ (lo cual debería ser si solo usas Joomla CMS v3.x o superior), entonces puedes utilizar código que use namespaces nativos en PHP. Siguiendo las reglas PSR-0, la convención de minúsculas/mayúsculas del directorio y el archivo deben coincidir con el namespace de PHP y la clase.

"'Ejemplo"'

  • La clase MyLib\Usuario\UserHelper debe estar ubicada en JPATH_LIBRARIES/src/MyLib/User/UserHelper.php

Uso

// Tell the auto-loader to look for namespaced classes starting with MyLib in the JPATH_LIBRARIES/src directory
JLoader::registerNamespace('MyLib', JPATH_LIBRARIES . '/src');

Accediendo la biblioteca desde cualquier lugar

Para acceder nuestra biblioteca desde cualquier lugar de una aplicación, debemos crear un plugin de sistema que registre nuestra biblioteca con JLoader. Este plugin debe activarse con el evento onAfterInitialise:

Archivo de manifiesto

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

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

Ahora podrás llamar las clases de tu biblioteca (ubicada en /libraries/mylib) desde cualquer componente, módulo o plugin.