Ayudante de módulo XMF

La clase Xmf\Module\Helper proporciona una forma fácil de acceder a información relacionada con módulos, configuraciones, controladores y más. Usar el ayudante de módulo simplifica su código y reduce boilerplate.

Descripción general

El ayudante de módulo proporciona:

• Acceso simplificado a la configuración
• Recuperación de objeto de módulo
• Instanciación de controladores
• Resolución de rutas y URLs
• Ayudantes de permisos y sesión
• Gestión de caché

Obteniendo un ayudante de módulo

Uso básico

use Xmf\Module\Helper;

// Get helper for a specific module
$helper = Helper::getHelper('mymodule');

// The helper is automatically associated with the module directory

Desde el módulo actual

Si no especifica un nombre de módulo, usa el módulo activo actual:

$helper = Helper::getHelper('');
// or
$helper = Helper::getHelper(basename(__DIR__));

Acceso a la configuración

Manera tradicional de XOOPS

Obtener la configuración del módulo de la manera antigua es verboso:

$module_handler = xoops_gethandler('module');
$module = $module_handler->getByDirname('mymodule');
$config_handler = xoops_gethandler('config');
$moduleConfig = $config_handler->getConfigsByCat(0, $module->getVar('mid'));
$value = isset($moduleConfig['foo']) ? $moduleConfig['foo'] : 'default';
echo "The value of 'foo' is: " . $value;

Manera XMF

Con el ayudante de módulo, la misma tarea se vuelve simple:

$helper = \Xmf\Module\Helper::getHelper('mymodule');
echo "The value of 'foo' is: " . $helper->getConfig('foo', 'default');

Métodos del ayudante

getModule()

Devuelve el objeto XoopsModule para el módulo del ayudante.

$module = $helper->getModule();
$version = $module->getVar('version');
$name = $module->getVar('name');
$mid = $module->getVar('mid');

getConfig($name, $default)

Devuelve un valor de configuración de módulo o todas las configuraciones.

// Get single config with default
$itemsPerPage = $helper->getConfig('items_per_page', 10);
$enableCache = $helper->getConfig('enable_cache', true);

// Get all configs as array
$allConfigs = $helper->getConfig('');

getHandler($name)

Devuelve un controlador de objeto para el módulo.

$itemHandler = $helper->getHandler('items');
$categoryHandler = $helper->getHandler('categories');

// Use the handler
$item = $itemHandler->get($id);
$items = $itemHandler->getObjects($criteria);

loadLanguage($name)

Carga un archivo de idioma para el módulo.

$helper->loadLanguage('main');
$helper->loadLanguage('admin');
$helper->loadLanguage('modinfo');

isCurrentModule()

Verifica si este módulo es el módulo activo actual.

if ($helper->isCurrentModule()) {
    // We're in the module's own pages
} else {
    // Called from another module or location
}

isUserAdmin()

Verifica si el usuario actual tiene derechos de administrador para este módulo.

if ($helper->isUserAdmin()) {
    // Show admin options
    echo '<a href="' . $helper->url('admin/index.php') . '">Admin</a>';
}

Métodos de ruta y URL

url($url)

Devuelve una URL absoluta para una ruta relativa a módulo.

$logoUrl = $helper->url('images/logo.png');
// Returns: https://example.com/modules/mymodule/images/logo.png

$adminUrl = $helper->url('admin/index.php');
// Returns: https://example.com/modules/mymodule/admin/index.php

path($path)

Devuelve una ruta absoluta de sistema de archivos para una ruta relativa a módulo.

/var/www/html/modules/mymodule/templates/view.tpl

$templatePath = $helper->path('templates/view.tpl');
$includePath = $helper->path('include/functions.php');
require_once $includePath;

uploadUrl($url)

Devuelve una URL absoluta para archivos cargados del módulo.

$fileUrl = $helper->uploadUrl('documents/manual.pdf');

uploadPath($path)

Devuelve una ruta absoluta de sistema de archivos para archivos cargados del módulo.

$uploadDir = $helper->uploadPath('');
$filePath = $helper->uploadPath('images/photo.jpg');

redirect($url, $time, $message)

Redirige dentro del módulo a una URL relativa a módulo.

$helper->redirect('index.php', 3, 'Item saved successfully');
$helper->redirect('view.php?id=' . $newId, 2, 'Created!');

Soporte de depuración

setDebug($bool)

Habilitar o deshabilitar modo de depuración para el ayudante.

$helper->setDebug(true);  // Enable
$helper->setDebug(false); // Disable
$helper->setDebug();      // Enable (default is true)

addLog($log)

Agregue un mensaje al registro del módulo.

$helper->addLog('Processing item ID: ' . $id);
$helper->addLog('Cache miss, loading from database');

Clases de ayudante relacionadas

XMF proporciona ayudantes especializados que extienden Xmf\Module\Helper\AbstractHelper:

Ayudante de permisos

Vea ../Recipes/Permission-Helper para documentación detallada.

$permHelper = new \Xmf\Module\Helper\Permission('mymodule');

// Check permission
if ($permHelper->checkPermission('view', $itemId)) {
    // User has permission
}

// Check and redirect if no permission
$permHelper->checkPermissionRedirect('edit', $itemId, 'index.php', 3, 'Access denied');

Ayudante de sesión

Almacenamiento de sesión consciente del módulo con prefijación automática de claves.

$session = new \Xmf\Module\Helper\Session('mymodule');

// Store value
$session->set('last_viewed', $itemId);

// Retrieve value
$lastViewed = $session->get('last_viewed', 0);

// Delete value
$session->del('last_viewed');

// Clear all module session data
$session->destroy();

Ayudante de caché

Almacenamiento en caché consciente del módulo con prefijación automática de claves.

$cache = new \Xmf\Module\Helper\Cache('mymodule');

// Write to cache (TTL in seconds)
$cache->write('item_' . $id, $itemData, 3600);

// Read from cache
$data = $cache->read('item_' . $id, null);

// Delete from cache
$cache->delete('item_' . $id);

// Read with automatic regeneration
$data = $cache->cacheRead(
    'expensive_data',
    function() {
        // This runs only if cache miss
        return computeExpensiveData();
    },
    3600
);

Ejemplo completo

Aquí hay un ejemplo completo usando el ayudante de módulo:

<?php
use Xmf\Request;
use Xmf\Module\Helper;
use Xmf\Module\Helper\Permission;
use Xmf\Module\Helper\Session;

require_once dirname(dirname(__DIR__)) . '/mainfile.php';

// Initialize helpers
$helper = Helper::getHelper('mymodule');
$permHelper = new Permission('mymodule');
$session = new Session('mymodule');

// Load language
$helper->loadLanguage('main');

// Get configuration
$itemsPerPage = $helper->getConfig('items_per_page', 10);
$enableComments = $helper->getConfig('enable_comments', true);

// Handle request
$op = Request::getCmd('op', 'list');
$id = Request::getInt('id', 0);

require_once XOOPS_ROOT_PATH . '/header.php';

switch ($op) {
    case 'view':
        // Check permission
        if (!$permHelper->checkPermission('view', $id)) {
            redirect_header($helper->url('index.php'), 3, _NOPERM);
        }

        // Track in session
        $session->set('last_viewed', $id);

        // Get handler and item
        $itemHandler = $helper->getHandler('items');
        $item = $itemHandler->get($id);

        if (!$item) {
            redirect_header($helper->url('index.php'), 3, 'Item not found');
        }

        // Display item
        $xoopsTpl->assign('item', $item->toArray());
        break;

    case 'list':
    default:
        $itemHandler = $helper->getHandler('items');

        $criteria = new CriteriaCompo();
        $criteria->setLimit($itemsPerPage);
        $criteria->setSort('created');
        $criteria->setOrder('DESC');

        $items = $itemHandler->getObjects($criteria);
        $xoopsTpl->assign('items', $items);

        // Show last viewed if exists
        $lastViewed = $session->get('last_viewed', 0);
        if ($lastViewed > 0) {
            $xoopsTpl->assign('last_viewed', $lastViewed);
        }
        break;
}

// Admin link if authorized
if ($helper->isUserAdmin()) {
    $xoopsTpl->assign('admin_url', $helper->url('admin/index.php'));
}

require_once XOOPS_ROOT_PATH . '/footer.php';

Clase base AbstractHelper

Todas las clases auxiliares de XMF extienden Xmf\Module\Helper\AbstractHelper, que proporciona:

Constructor

public function __construct($dirname)

Instancia con un nombre de directorio de módulo. Si está vacío, usa el módulo actual.

dirname()

Devuelve el nombre del directorio del módulo asociado con el ayudante.

$dirname = $helper->dirname();

init()

Llamado por el constructor después de que se carga el módulo. Anule en ayudantes personalizados para lógica de inicialización.

Creando ayudantes personalizados

Puede extender el ayudante para funcionalidad específica del módulo:

mymodule/class/Helper.php

<?php
namespace XoopsModules\Mymodule;

class Helper extends \Xmf\Module\Helper\GenericHelper
{
    public function init()
    {
        // Custom initialization
    }

    public function getItemUrl($id)
    {
        return $this->url('item.php?id=' . $id);
    }

    public function getUploadDirectory()
    {
        $path = $this->uploadPath('');
        if (!is_dir($path)) {
            mkdir($path, 0755, true);
        }
        return $path;
    }
}

Ver también

• Getting-Started-with-XMF - Uso básico de XMF
• XMF-Request - Manejo de solicitudes
• ../Recipes/Permission-Helper - Gestión de permisos
• ../Recipes/Module-Admin-Pages - Creación de interfaz de administración

---

#xmf #module-helper #configuration #handlers #session #cache