Joomla! Documentation™

Vista general

El registro de Joomla le da la capacidad de registrar mensajes en archivos y en la pantalla (dentro de la consola de depuración de Joomla! en la parte inferior de la página web) y la clase principal de Joomla que sustenta esto es JLog. En la nueva convención de nomenclatura esta es la clase Log dentro del espacio de nombres Joomla\CMS\Log\Log.

El registro puede ser controlado dinámicamente a través de la Configuración Global de Joomla y configurando el plugin de Sistema - Depurador (que se suministra con Joomla). En general, estas instalaciones le permiten:

• Activar o desactivar el registro DEBUG - para que normalmente no consuma recursos innecesariamente, pero tenga la información de registro para ayudar a la solución de problemas cuando hay incidencias, por ejemplo en un sitio en vivo que tiene su extensión instalada.
• dirigir los mensajes de registro a un archivo de registro específico para su propia extensión.
• ver los mensajes de registro en la consola de depuración - puede seleccionar el grupo de usuarios a los que deben mostrarse los mensajes de registro, de modo que en un sitio en vivo los desarrolladores pueden ver los mensajes mientras que otros usuarios no se ven afectados.
• filtrar los mensajes de la consola de depuración por prioridad (es decir, INFO, DEBUG, WARNING, etc.) y por categoría. (Usted es libre de definir sus propias categorías).

Además, los mensajes de registro pueden traducirse a diferentes idiomas.

A continuación se muestran las principales opciones de configuración relacionadas con el registro. La activación de la depuración y la visualización de la consola de depuración de Joomla se controla a través de las opciones de configuración global.

El registro en el archivo de registro general se controla a través de la pestaña de registro de la configuración del plugin de Joomla "Sistema - Depurador". (En el menú del administrador, haga clic en Extensiones / Plugins, busque el plugin Sistema - Depurador. Haga clic en él para editar sus opciones configurables).

Y las opciones dentro de la pestaña de control del plugin se muestran en la consola de depuración de Joomla.

Archivo de Registro Básico

Para registrar un mensaje se utiliza la función JLog::add(). Por ejemplo:

JLog::add('my error message', JLog::ERROR, 'my-error-category');

Utilizando la nueva convención de nomenclatura de clases, utilice en su lugar:

use Joomla\CMS\Log\Log;
Log::add('my error message', Log::ERROR, 'my-error-category');

Los parámetros son

1. Una cadena de mensajes. Puede utilizar la traducción con estos. (Por ejemplo, JText::_('MY_EXTENSION_ERR_MSG') También puede mostrar los valores de las variables, siempre que los convierta a un formato de cadena. (Por ejemplo, utilizando __toString() si el tipo de la variable lo soporta).
2. Una prioridad, que puede ser una de las siguientes: JLog::EMERGENCY, JLog::ALERT, JLog::CRITICAL, JLog::ERROR, JLog::WARNING, JLog::NOTICE, JLog::INFO, JLog::DEBUG (basado en los niveles de gravedad estándar de syslog / RFC 5424 - ver artículo de wikipedia sobre syslog).
3. Una categoría, que es sólo una cadena de texto. Puedes definir las categorías que quieras, pero es mejor definirlas para evitar posibles choques con las de otras extensiones.

Puede ser muy útil para solucionar problemas si incluye mensajes de depuración de diagnóstico en su extensión. En este caso, incluya su mensaje de registro dentro de una comprobación de JDEBUG:

if (JDEBUG)
{
    JLog::add('my debug message', JLog::DEBUG, 'my-debug-category');
}

Código de ejemplo de registro básico

A continuación se muestra el código de un módulo simple de Joomla que puede instalar y ejecutar para demostrar el uso de la funcionalidad de registro. Si no estás seguro sobre el desarrollo y la instalación de un módulo de Joomla, entonces siguiendo el tutorial en Crear un módulo simple te ayudará.

En una carpeta mod_sample_log cree los siguientes 2 archivos:

mod_sample_log.xml

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1" client="site" method="upgrade">
    <name>Joomla Log demo</name>
    <version>1.0.1</version>
    <description>Code demonstrating use of Joomla Log class to log messages</description>
    <files>
        <filename module="mod_sample_log">mod_sample_log.php</filename>
    </files>
</extension>

mod_sample_log.php

<?php
defined('_JEXEC') or die('Restricted Access');

use Joomla\CMS\Log\Log;

Log::add('my error message', Log::ERROR, 'my-error-category');

JLog::add('my old error message', JLog::WARNING, 'my-old-error-category');

echo "Error message logged";

Comprima el directorio mod_sample_log para crear mod_sample_log.zip.

Dentro de tu administrador de Joomla ve a Instalar Extensiones y a través de la pestaña Subir Archivo del Paquete sube este archivo zip para instalar este módulo de registro de ejemplo.

Haz visible este módulo editándolo (haz clic en él dentro de la página de Módulos) entonces:

1. modificando su estado a Publicado
2. seleccionando una posición en la página para que se muestre
3. en la pestaña de asignación de menú, especifique las páginas en las que debe aparecer

Compruebe la configuración de los ajustes mostrados en la parte superior de esta página web. En particular, asegúrese de que el plugin Sistema - Depurador está activado y que "Registro de casi todo" está configurado como "Sí". Anote también la carpeta donde se almacenan sus archivos de registro.

Muestra tu sitio Joomla y deberías ver el módulo de registro de ejemplo que aparece. En su carpeta de archivos de registro debe encontrar sus mensajes de error en el archivo everything.php.

Encienda también la consola de depuración y confirme que puede ver los mensajes de error en su sección de mensajes de registro.

Registro en un archivo de registro específico

Puede utilizar JLog::addLogger() para configurar el registro en un archivo de registro adicional, filtrando los mensajes de registro que se enviarán allí por prioridad (el "nivel de gravedad") y/o categoría. Los parámetros de JLog::addLogger() son:

1. un array con los detalles de configuración - incluyendo el nombre del archivo de registro.
2. los niveles de gravedad a registrar en ese archivo.
3. un array con las categorías a registrar en ese fichero. (Si el parámetro 4 se establece como true, este array define las categorías que NO deben registrarse en el archivo).
4. (a menudo omitido) un booleano que especifica si el parámetro 3 es una lista de inclusión. (Por defecto, P4 = false) o una lista de exclusión (P4 = true.)

Por ejemplo, si has desarrollado una extensión com_helloworld podrías utilizar lo siguiente:

JLog::addLogger(
    array(
         // Sets file name
         'text_file' => 'com_helloworld.log.php'
    ),
    // Sets messages of all log levels to be sent to the file.
    JLog::ALL,
    // The log category/categories which should be recorded in this file.
    // In this case, it's just the one category from our extension.
    // We still need to put it inside an array.
    array('com_helloworld')
);

Entonces, cuando registre un mensaje, especifique la categoría como com_helloworld, como en el ejemplo siguiente

JLog::add(JText::_('COM_HELLOWORLD_ERROR_MESSAGE_123'), JLog::ERROR, 'com_helloworld');

Esto hará que su mensaje de registro se escriba en com_helloworld.log.php. Si la configuración del plugin Sistema - Depurador tiene la opción " Registro de casi todo" establecida en Sí, el mensaje aparecerá también en el archivo de registro común everything.php.

"'Nota:"' Puedes desear combinar esto con la sección Mostrar mensajes de error y avisos para mostrar notificaciones de error visibles a los usuarios.

También puedes agregar un registrador adicional que capture sólo las notificaciones críticas y de emergencia:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php'
    ),
    // Sets critical and emergency log level messages to be sent to the file.
    JLog::CRITICAL + JLog::EMERGENCY,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

También puede excluir un nivel de prioridad específico para que no se incluya. Por ejemplo, para registrar todos los mensajes menos los de DEBUG:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.all_but_debug.php'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Los niveles de prioridad de JLog se implementan como bits separados de un entero, por lo que puedes utilizar operaciones bitwise (bitwise AND, &; y bitwise NOT, ~) para calcular los niveles de registro apropiados. JLog::All es un entero constante que tiene todos los bits relevantes configurados, de modo que se incluyen todos los niveles de prioridad de Joomla.

Formato del archivo de registro

El primer parámetro de addLogger puede tener algunos ajustes adicionales opcionales además de la entrada text_file.

Hay, por ejemplo, la entrada text_entry_format, especificando el formato de cada línea en el archivo de registro.

El formato predeterminado es:

   '{DATETIME} {PRIORITY}      {CATEGORY}      {MESSAGE}'

Aquí hay un ejemplo de un formato diferente, que muestra cómo omitir la categoría:

JLog::addLogger(
    array(
         // Sets file name.
         'text_file' => 'com_helloworld.critical_emergency.php',
         // Sets the format of each line.
         'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
    ),
    // Sets all but DEBUG log level messages to be sent to the file.
    JLog::ALL & ~JLog::DEBUG,
    // The log category which should be recorded in this file.
    array('com_helloworld')
);

Además de los marcadores de posición que se muestran arriba en la cadena predeterminada, los valores siguientes están disponibles:

   {CLIENTIP}      (this is the IP address of the client)
   {TIME}
   {DATE}

Existe un parámetro booleano opcional adicional text_file_no_php, que especifica si al archivo de registro se le añade el prefijo habitual de:

   #
   #<?php die('Forbidden.');?>

"'Nota:"' por lo general, no debes establecer este valor a false. Los archivos de registro no deben ser legibles desde el exterior, ya que pueden proporcionar información valiosa acerca de tu sistema para los atacantes. ¡Sólo hazlo si sabes lo que estás haciendo!

Además, si quieres almacenar el archivo de registro en algún lugar distinto a la ruta de registro configurada en los ajustes de Joomla!, existe el ajuste text_file_path.

Registro en otros lugares

Además de registrar en archivos, puede registrar en otros lugares también, como

• el área de mensajes de Joomla (donde se muestra el mensaje si llamas a JFactory::getApplication()->enqueueMessage()).
• una tabla de la base de datos.
• una simple sentencia echo.

De estos, probablemente el más útil es el registro en la barra de mensajes, que se puede configurar a través de:

JLog::addLogger(array('logger' => 'messagequeue'), JLog::ALL, array('msg-error-cat'));

Entonces cuando se hace:

JLog::add('un error a mostrar', JLog::ERROR, 'msg-error-cat');

obtendrás el mensaje copiado en la barra de mensajes. Tenga en cuenta que el código del núcleo de Joomla configura el registro en la cola de mensajes para la categoría 'jerror', de modo que si utiliza esta categoría en sus mensajes de registro, obtendrá el mensaje mostrado en la barra de mensajes. Por ejemplo:

JLog::add('error copiado a la barra de mensajes', JLog::Error, 'jerror');

hará que el mensaje se muestre en el área de mensajes de Joomla, aunque no hayas configurado explícitamente un registrador para que se registre allí.

Registrador PSR-3

Desde la versión 3.8 Joomla incorpora un registrador que se adhiere a la PSR-3 Logger Interface. Esto permite a las bibliotecas que siguen esta recomendación estándar integrarse con el sistema de registro de Joomla. Para usar esto, primero haz:

use Joomla\CMS\Log\Log;
$psr3Logger = Log::createDelegatedLogger();

Esto devuelve un objeto en el que tiene disponibles los métodos del LoggerInterface de PSR-3, por ejemplo:

$psr3Logger->critical("critical error text", array("category" => "my-critical-category"));

Los registradores de Joomla por defecto sólo procesan los elementos "categoría" y "fecha" del array asociativo contexto (parámetro 2), mapeando los valores de estos elementos a la columna correspondiente en su archivo de registro.

Excepciones

JLog::add() lanzará una excepción si no puede escribir en el archivo de registro. Para evitar esto, tendrías que envolver la llamada en otra función, o implementar tu propia clase de registro y luego incluirla con:

JLog::addLogger(
    array(
         // Use mycustomlogger.
         'logger' => 'mycustomlogger',
         'text_file' => 'com_helloworld.errors.php'
    ),
    JLog::ALL,
    array('com_helloworld')
);

Otras lecturas

El registro de Joomla debe ser utilizado en conjunto con las excepciones de PHP, no como un reemplazo. Ver J2.5:Exceptions_and_Logging_in_Joomla_Platform_11.1_and_Joomla_2.5 para conocer la historia de esta clase y cómo surgió de las antiguas clases de error compatibles con PHP4.