XOOPS Kernel Classes¶

The XOOPS Kernel provides the foundational framework for bootstrapping the system, managing configurations, handling system events, and providing core utilities. These classes form the backbone of the XOOPS application.

System Architecture¶

graph TD
    A[XoopsKernel] -->|initializes| B[Configuration Manager]
    A -->|manages| C[Service Container]
    A -->|handles| D[System Hooks]
    A -->|registers| E[Core Services]

    B -->|loads| F[config.php]
    B -->|manages| G[Module Configs]

    C -->|contains| H[Database]
    C -->|contains| I[Logger]
    C -->|contains| J[Template Engine]
    C -->|contains| K[Module Manager]

    E -->|registers| L[User Service]
    E -->|registers| M[Module Service]
    E -->|registers| N[Database Service]

XoopsKernel Class¶

The main kernel class that initializes and manages the XOOPS system.

Class Overview¶

namespace Xoops;

class XoopsKernel
{
    private static ?XoopsKernel $instance = null;
    protected ServiceContainer $services;
    protected ConfigurationManager $config;
    protected array $modules = [];
    protected bool $isLoaded = false;
}

Constructor¶

private function __construct()

Private constructor enforces singleton pattern.

getInstance¶

Retrieves the singleton kernel instance.

public static function getInstance(): XoopsKernel

Returns: XoopsKernel - The singleton kernel instance

Example:

$kernel = XoopsKernel::getInstance();

Boot Process¶

The kernel boot process follows these steps:

Initialization - Set error handlers, define constants
Configuration - Load configuration files
Service Registration - Register core services
Module Detection - Scan and identify active modules
Database Initialization - Connect to database
Cleanup - Prepare for request handling

public function boot(): void

Example:

$kernel = XoopsKernel::getInstance();
$kernel->boot();

Service Container Methods¶

registerService¶

Registers a service in the service container.

public function registerService(
    string $name,
    callable|object $definition
): void

Parameters:

Parameter	Type	Description
`$name`	string	Service identifier
`$definition`	callable\|object	Service factory or instance

Example:

$kernel->registerService('custom.handler', function($c) {
    return new CustomHandler();
});

getService¶

Retrieves a registered service.

public function getService(string $name): mixed

Parameters:

Parameter	Type	Description
`$name`	string	Service identifier

Returns: mixed - The requested service

Example:

$database = $kernel->getService('database');
$logger = $kernel->getService('logger');

hasService¶

Checks if a service is registered.

public function hasService(string $name): bool

Example:

if ($kernel->hasService('cache')) {
    $cache = $kernel->getService('cache');
}

Configuration Manager¶

Manages application configuration and module settings.

Class Overview¶

namespace Xoops\Core;

class ConfigurationManager
{
    protected array $config = [];
    protected array $defaults = [];
    protected string $configPath;
}

Methods¶

load¶

Loads configuration from file or array.

public function load(string|array $source): void

Parameters:

Parameter	Type	Description
`$source`	string\|array	Config file path or array

Example:

$config = $kernel->getService('config');
$config->load(XOOPS_ROOT_PATH . '/include/config.php');
$config->load(['sitename' => 'My Site', 'admin_email' => 'admin@example.com']);

get¶

Retrieves a configuration value.

public function get(string $key, mixed $default = null): mixed

Parameters:

Parameter	Type	Description
`$key`	string	Configuration key (dot notation)
`$default`	mixed	Default value if not found

Returns: mixed - Configuration value

Example:

$siteName = $config->get('sitename');
$adminEmail = $config->get('admin.email', 'admin@example.com');

set¶

Sets a configuration value.

public function set(string $key, mixed $value): void

Parameters:

Parameter	Type	Description
`$key`	string	Configuration key
`$value`	mixed	Configuration value

Example:

$config->set('sitename', 'New Site Name');
$config->set('features.cache_enabled', true);

getModuleConfig¶

Gets configuration for a specific module.

public function getModuleConfig(
    string $moduleName
): array

Parameters:

Parameter	Type	Description
`$moduleName`	string	Module directory name

Returns: array - Module configuration array

Example:

$publisherConfig = $config->getModuleConfig('publisher');

System Hooks¶

System hooks allow modules and plugins to execute code at specific points in the application lifecycle.

HookManager Class¶

namespace Xoops\Core;

class HookManager
{
    protected array $hooks = [];
    protected array $listeners = [];
}

Methods¶

addHook¶

Registers a hook point.

public function addHook(string $name): void

Parameters:

Parameter	Type	Description
`$name`	string	Hook identifier

Example:

$hooks = $kernel->getService('hooks');
$hooks->addHook('system.startup');
$hooks->addHook('user.login');
$hooks->addHook('module.install');

listen¶

Attaches a listener to a hook.

public function listen(
    string $hookName,
    callable $callback,
    int $priority = 10
): void

Parameters:

Parameter	Type	Description
`$hookName`	string	Hook identifier
`$callback`	callable	Function to execute
`$priority`	int	Execution priority (higher runs first)

Example:

$hooks->listen('user.login', function($user) {
    error_log('User ' . $user->uname . ' logged in');
}, 10);

$hooks->listen('module.install', function($module) {
    // Custom module installation logic
    echo "Installing " . $module->getName();
}, 5);

trigger¶

Executes all listeners for a hook.

public function trigger(
    string $hookName,
    mixed $arguments = null
): array

Parameters:

Parameter	Type	Description
`$hookName`	string	Hook identifier
`$arguments`	mixed	Data to pass to listeners

Returns: array - Results from all listeners

Example:

$results = $hooks->trigger('system.startup');
$results = $hooks->trigger('user.created', $newUser);

Core Services Overview¶

The kernel registers several core services during boot:

Service	Class	Purpose
`database`	XoopsDatabase	Database abstraction layer
`config`	ConfigurationManager	Configuration management
`logger`	Logger	Application logging
`template`	XoopsTpl	Template engine
`user`	UserManager	User management service
`module`	ModuleManager	Module management
`cache`	CacheManager	Caching layer
`hooks`	HookManager	System event hooks

Complete Usage Example¶

<?php
/**
 * Custom module boot process utilizing kernel
 */

// Get kernel instance
$kernel = XoopsKernel::getInstance();

// Boot the system
$kernel->boot();

// Get services
$config = $kernel->getService('config');
$database = $kernel->getService('database');
$logger = $kernel->getService('logger');
$hooks = $kernel->getService('hooks');

// Access configuration
$siteName = $config->get('sitename');
$adminEmail = $config->get('admin.email');

// Register module-specific hooks
$hooks->listen('user.login', function($user) {
    // Log user login
    $logger->info('User login: ' . $user->uname);

    // Track in database
    $database->query(
        'INSERT INTO ' . $database->prefix('event_log') .
        ' (type, user_id, message, timestamp) VALUES (?, ?, ?, ?)',
        ['login', $user->uid(), 'User login', time()]
    );
});

$hooks->listen('module.install', function($module) {
    $logger->info('Module installed: ' . $module->getName());
});

// Trigger hooks
$hooks->trigger('system.startup');

// Use database service
$result = $database->query(
    'SELECT * FROM ' . $database->prefix('users') .
    ' LIMIT 10'
);

while ($row = $database->fetchArray($result)) {
    echo "User: " . htmlspecialchars($row['uname']) . "\n";
}

// Register custom service
$kernel->registerService('custom.repository', function($c) {
    return new CustomRepository($c->getService('database'));
});

// Later access custom service
$repo = $kernel->getService('custom.repository');

Core Constants¶

The kernel defines several important constants during boot:

// System paths
define('XOOPS_ROOT_PATH', '/var/www/xoops');
define('XOOPS_HTDOCS_PATH', XOOPS_ROOT_PATH . '/htdocs');
define('XOOPS_MODULES_PATH', XOOPS_ROOT_PATH . '/htdocs/modules');
define('XOOPS_THEMES_PATH', XOOPS_ROOT_PATH . '/htdocs/themes');

// Web paths
define('XOOPS_URL', 'http://example.com');
define('XOOPS_HTDOCS_URL', XOOPS_URL . '/htdocs');

// Database
define('XOOPS_DB_PREFIX', 'xoops_');

Error Handling¶

The kernel sets up error handlers during boot:

// Set custom error handler
set_error_handler(function($errno, $errstr, $errfile, $errline) {
    $kernel->getService('logger')->error(
        "Error: $errstr in $errfile:$errline"
    );
});

// Set exception handler
set_exception_handler(function($exception) {
    $kernel->getService('logger')->critical(
        "Exception: " . $exception->getMessage()
    );
});

Best Practices¶

Single Boot - Call boot() only once during application startup
Use Service Container - Register and retrieve services through the kernel
Handle Hooks Early - Register hook listeners before triggering them
Log Important Events - Use the logger service for debugging
Cache Configuration - Load config once and reuse
Error Handling - Always set up error handlers before processing requests

Module-System - Module system and lifecycle
Template-System - Template engine integration
User-System - User authentication and management
XoopsDatabase - Database layer

See also: XOOPS Kernel Source

XOOPS Kernel Classes¶

System Architecture¶