XMF 模組協助者

Xmf\Module\Helper 類別提供了一種簡單的方式來存取模組相關資訊、配置、處理常式等。使用模組協助者可簡化您的程式碼並減少重複程式碼。

概述

模組協助者提供：

簡化的配置存取
模組物件擷取
處理常式實例化
路徑和 URL 解析
權限和工作階段協助者
快取管理

取得模組協助者

基本用法

use Xmf\Module\Helper;

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

// The helper is automatically associated with the module directory

從目前模組

如果您未指定模組名稱，它將使用目前的作用中模組：

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

配置存取

傳統 XOOPS 方式

以舊方式取得模組配置很繁冗：

$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;

XMF 方式

使用模組協助者，相同的任務變得簡單：

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

協助者方法

getModule()

傳回協助者模組的 XoopsModule 物件。

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

getConfig($name, $default)

傳回模組配置值或所有配置。

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

傳回模組的物件處理常式。

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

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

loadLanguage($name)

載入模組的語言檔案。

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

isCurrentModule()

檢查此模組是否為目前作用中模組。

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

isUserAdmin()

檢查目前使用者是否擁有此模組的管理員權限。

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

路徑和 URL 方法

url($url)

傳回模組相對路徑的絕對 URL。

$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)

傳回模組相對路徑的絕對檔案系統路徑。

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

uploadUrl($url)

傳回模組上傳檔案的絕對 URL。

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

uploadPath($path)

傳回模組上傳檔案的絕對檔案系統路徑。

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

redirect($url, $time, $message)

重新導向至模組內的模組相對 URL。

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

偵錯支援

setDebug($bool)

啟用或停用協助者的偵錯模式。

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

addLog($log)

將訊息新增至模組記錄。

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

完整範例

以下是使用模組協助者的全面範例：

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

AbstractHelper 基礎類別

所有 XMF 協助者類別都擴充 Xmf\Module\Helper\AbstractHelper，其提供：

建構函式

public function __construct($dirname)

使用模組目錄名稱實例化。如果為空，則使用目前模組。

dirname()

傳回與協助者相關聯的模組目錄名稱。

$dirname = $helper->dirname();

init()

由建構函式在載入模組後呼叫。在自訂協助者中覆蓋以進行初始化邏輯。

建立自訂協助者

您可以擴充協助者以實現模組特定的功能：

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