Application - xoopscube/legacy GitHub Wiki

XOOPSCube

Web Application Platform

index.php

> html/index.php

Summary of the key points from the index.php file and the mainfile.php file:

The index.php file is the entry point for the XoopsCube application. It requires the header.php file and sets up some global options using the $xoopsOption array.
It then calls a delegate event, 'Legacypage.Top.Access', which allows other modules to modify the page content before it is rendered.
Finally, it includes the footer.php file and outputs the page content using XCube's rendering engine.

The index.php file is responsible for bootstrapping the application by requiring the necessary files and calling an event to modify the page content before rendering. It also sets up some global options using the $xoopsOption array and outputs the page content using XCube's rendering engine.

The $xoopsOption array and the delegate event 'Legacypage.Top.Access' are key components of your XoopsCube application. Here's a summary of what each of them does:

The $xoopsOption array is used to store various configuration options for the application. It contains information such as whether or not to display blocks, whether or not to show system messages, and other settings that affect the behavior of the application.
The delegate event 'Legacypage.Top.Access' is called at the beginning of the index.php file to allow other modules to modify the page content before it is rendered. This can be useful for adding custom blocks or modifying system messages, among other things.

[!NOTE] You should focus on working with the $xoopsOption array and the delegate event 'Legacypage.Top.Access' when refactoring your XoopsCube application and fixing deprecated warnings and bugs.

mainfile.php

> html/mainfile.php // read-only permissions

Summary of the key points from the mainfile.php file:

This file is used to set up the XoopsCube environment by defining various configuration options using predefined constants and including necessary files.
It sets the physical path, virtual path, database type, table prefix, salt, database hostname, username, password, and database name for the application.
If a trusted path is specified in the XOOPS_TRUST_PATH constant, it includes the autoload file from that directory to ensure compatibility with Composer vendor autoloader.
It then checks if the main XOOPS directory path and the trusted path are provided using the XOOPS_ROOT_PATH and XOOPS_TRUST_PATH constants, respectively. If they are not provided, it includes the precheck file from the protector module to perform some initial checks.
After that, it includes the cubecore_init.php file to initialize the XoopsCube root object and the controller class. It also checks if $xoopsOption['nocommon'] is set or if the constant _LEGACY_PREVENT_EXEC_COMMON_ is defined before including the common.php file to execute common module process subset.
Finally, it includes the postcheck file from the protector module to perform some final checks before the XoopsCube application can proceed.

[!WARNING]
The mainfile.php file sets up the XoopsCube environment by defining various configuration options using predefined constants and including necessary files. It also checks for the presence of the main XOOPS directory path and the trusted path, and includes the necessary files to initialize the application environment.

Cube Core Initialization

> html/include/cubecore_init.php

Summary of the key points from the cubecore_init.php file:

This file initializes the XoopsCube framework by including necessary files and setting up the main controller using the XCube_Root class.
It first checks if the XOOPS_MAINFILE_INCLUDED constant is defined, which indicates that mainfile.php has been included and sets up the XoopsCube environment. If not, it exits with an error message.
It then checks if the XOOPS_TRUST_PATH constant is defined, which points to the trusted directory for Composer vendor autoloader. If not, it displays an error message and exits.
After that, it defines two constants XOOPS_CUBE_LEGACY and LEGACY_BASE_VERSION to indicate that this is a XoopsCube system and provide version information for module developers.
It then includes the necessary files for XCube core initialization: XCube_Root.class.php, XCube_Controller.class.php, and IniHandler.class.php.
The script defines five file paths related to site configuration using constants: XCUBE_SITE_SETTING_FILE, XCUBE_SITE_CUSTOM_FILE, XCUBE_SITE_CUSTOM_FILE_SALT, XCUBE_SITE_DIST_FILE, and the file path for CorePack custom settings.
Finally, it initializes the XoopsCube root object using XCube_Root::getSingleton() and calls the loadSiteConfig method to load site configuration files from the trusted directory. The method takes four parameters: the default setting file, the dist file (for CorePack), and the custom setting file and its salted version. The setupController method is then called to set up the main controller for the XoopsCube application.

[!IMPORTANT]
The cubecore_init.php file initializes the XoopsCube framework by including necessary files and setting up the main controller using the XCube_Root class. It also defines constants and file paths related to site configuration.


//
// XCube Core
//
require_once XOOPS_ROOT_PATH . '/core/XCube_Root.class.php';
require_once XOOPS_ROOT_PATH . '/core/XCube_Controller.class.php';
require_once XOOPS_ROOT_PATH . '/core/libs/IniHandler.class.php';

//
// IniHandler - default site, custom and distribution settings
// The code snippets provided are various configuration files used in an XOOPSCube-based platform
//
define('XCUBE_SITE_SETTING_FILE', XOOPS_TRUST_PATH . '/settings/site_default.ini');
define('XCUBE_SITE_CUSTOM_FILE', XOOPS_TRUST_PATH . '/settings/site_custom.ini');
define('XCUBE_SITE_DIST_FILE', XOOPS_TRUST_PATH . '/settings/site_default.dist.ini'); // for CorePack
define('XCUBE_SITE_CUSTOM_FILE_SALT', XOOPS_TRUST_PATH . '/settings/site_custom_' . XOOPS_SALT . '.ini');

//
// How does the system decide the main controller
//
$root=&XCube_Root::getSingleton();
// Added XCUBE_SITE_DIST_FILE for distribution CorePack
$root->loadSiteConfig(XCUBE_SITE_SETTING_FILE, XCUBE_SITE_DIST_FILE, XCUBE_SITE_CUSTOM_FILE, XCUBE_SITE_CUSTOM_FILE_SALT);
$root->setupController();

> trust_path/settings/

definition.inc.php: This file contains various constants used throughout the XoopsCube framework. It defines enumerations for side block positions, center block positions, visibility flags, match conditions, Smarty template paths and directories, cache and module/theme paths, library paths, PEAR paths, vendor paths, URLs, and user-related modules and utility classes.

site_default.ini: This is the default site configuration INI file for XoopsCube. It contains various settings and configurations such as the root path, controller class, recommended modules, role manager class, salt value, primary preloads, components, and jQuery settings. The [RenderSystems] section specifies the available rendering systems and their paths, while other sections define specific configuration options for each component.

site_custom.ini.php: This custom settings INI file is used to define additional rendering systems for the platform. It includes a [RenderSystems] section where you can specify different rendering system configurations. Each rendering system entry consists of a unique key and corresponding class path and name.

xupdate_mystores.ini.dist: This configuration file is an example of how to register custom stores for the XoopsUpdater module. It defines the settings for one store named "My1". Each section represents a different store, and they are listed under the "My1" key. The properties include unique keys, store IDs, names, types (modules or themes), setting types (ini or json), and addon URLs.

XCube Core

> html/core/

XCube Root Class

The XCube_Root class is a central class in the XCL framework, responsible for managing various aspects of the application. Here's a summary of its key methods:

The constructor initializes several member variables like mSiteConfig, mController, etc., and sets up the root path ($root) if not provided.
getConfig() retrieves a configuration value from the site configuration (SiteConfig), handling cases with multiple parameters.
setupController() creates an instance of the controller based on the configuration settings and calls its prepare method.
getController() returns the current controller object.
Various setter and getter methods for managing language, delegate, service, render system, permission, text filter, role manager, context, and session objects.
The _createInstance() is a private helper method that dynamically creates an instance of a class from a given path and name, handling cases with multiple parameters and special cases related to the root path and loading files.

XCube Controller Class

The XCube_Controller class is a base class for all controllers in the XCL framework. It provides various methods and properties to manage the lifecycle of the web application. Here's a summary of its key members:

mExecute, mSetupTextFilter, mSetupUser: These are callable objects representing the main object, text filter setup method, and user setup method respectively.
_mFilterChain: An array to store action filters added to the controller.
_mLoadedFilterNames: A map to track which filter classes have already been loaded.
addActionFilter(): Adds an ActionFilter instance to the internal filter chain.
_setupFilterChain(), _processFilter(), _processPreBlockFilter(), _processPostFilter(), _setupBlock(), _processBlock(): These methods are responsible for setting up and processing the action filters, blocks, and other aspects of the controller lifecycle.
_processPreload( $path ): A utility method to load files from a given path, instantiate sub-class objects, and add them to the filter chain.
Other protected methods for creating and setting up various components like delegate manager, service manager, permission manager, role manager, context, and session.

XCube IniHandler Class

The XCube_IniHandler class is a simple INI file parser that provides a convenient way to read and manipulate INI files in PHP. It reads an INI file into an array, allowing you to easily access individual values or sections of the configuration data.

Here's a breakdown of the class:

The constructor takes two parameters: $filePath, which is the path to the INI file to be loaded, and $section, which determines whether the INI file should be treated as having sections. If $section is true, each section in the INI file will be stored as a key in an associative array under its corresponding section name.
The _loadIni() method reads the INI file and populates the internal configuration array with key-value pairs or sections. It uses regular expressions to identify comment lines, empty lines, and sections. Each line that isn't a comment or an empty line is treated as either a key-value pair or a section header.
The getConfig() method retrieves a specific value from the configuration array based on the provided key and optional section name. If sections are enabled and no section name is given, it will default to retrieving values from the first section in the INI file.
The getSectionConfig() method retrieves all the key-value pairs for a given section. If sections are not enabled, this method returns null.
The getAllConfig() method returns the entire configuration array.

Overall, the XCube_IniHandler class provides a straightforward way to work with INI files in PHP applications that require configuration data.

XCube ActionFilter Class

The XCube_ActionFilter class is an abstract base class that defines the interface for action filters in the XCL framework. Action filters are responsible for modifying or enforcing certain rules during the initialization and execution of controllers. These filters can be used to perform authentication, authorization, input validation, logging, caching, and other tasks.

In XCL, an action filter is typically added to a controller using the addActionFilter() method. The XCube_Controller class manages an internal filter chain that is executed in order when the controller's filters are called.

The XCube_ActionFilter class has three abstract methods:

preFilter(): This method is called at the very beginning of the controller initialization process, before any other action filters are executed.
preBlockFilter(): This method is called when the controller's pre-block filter chain is executed. It can be used for tasks such as setting up template data or manipulating module options.
postFilter(): This method is called at the end of the controller's post-filter chain, after all other action filters have been executed.

To create a custom action filter, you should extend the XCube_ActionFilter class and implement one or more of its abstract methods according to your specific requirements. For example:

class MyCustomFilter extends XCube_ActionFilter {
    public function preFilter() {
        // Custom logic before controller initialization
    }

    public function preBlockFilter() {
        // Custom logic during pre-block filter chain execution
    }

    public function postFilter() {
        // Custom logic after controller execution
    }
}

Then, you can add your custom filter to a controller using the addActionFilter() method:

$controller = new MyController();
$filter = new MyCustomFilter($controller);
$controller->addActionFilter($filter);

XCube Delegate Class

The XCube_Delegate class in XoopsCube-based platforms is a fundamental component of the framework, which allows for modular and extensible event-driven programming. It serves as a way to decouple different parts of your code by allowing you to define delegates or events, and then register callbacks (functions) that will be executed when those events occur.

Here are some key points about the XCube_Delegate mechanism:

Decoupling: The delegate mechanism helps in decoupling modules and components within a larger system. Each module can define its own delegates, allowing other modules to subscribe to these events without needing to directly interact with them. This promotes modularity and enhances extensibility.
Event-Driven Programming: By using delegates, you can create a more dynamic and flexible architecture where changes in one part of the system don't necessarily require significant changes in other parts. When an event is triggered, all subscribed callbacks are executed in sequence, allowing for customized behavior based on the specific requirements of each module or component.
Registration and Callbacks: To use a delegate, you first need to create an instance of it. You can then register one or more callback functions with the delegate using the register() method. When an event is triggered, all registered callbacks are called in the order they were registered. Each callback function receives the same set of parameters passed when the event was triggered.
Delegates and Delegate Managers: In XoopsCube, delegates are typically managed by a delegate manager (XCube_DelegateManager), which is responsible for creating and managing delegate instances. The delegate manager provides methods to register delegates, retrieve them by name, and reset their states (clear all callbacks).
Utility Class: There's also a utility class, XCube_DelegateUtils, which provides static methods for calling delegates and handling string filters. This can be useful in various scenarios, such as triggering events or applying custom formatting to strings based on delegate functions.

[!IMPORTANT] Overall, the XCube_Delegate mechanism is an essential feature of XoopsCube's architecture that facilitates communication between different parts of a system, promoting both modularity and extensibility.

XCube_Ref class is an adapted reference pointer for XCube_Delegate.

XCube_Ref : virtual function pointer

XCube_Delegate : Simple mechanism for common delegation in XCube

Because of XCube_Delegate virtual function pointers, it is impossible to pass variables as references to XCube_Delegate::call(). In a such case, use this class as an adapter.

A virtual function is a member function that you expect to be redefined in derived classes. When you refer to a derived class object using a pointer or a reference to the base class, you can call a virtual function for that object and execute the derived class's version of the function.

[Final] a.k.a. Java the C++ way. This class is an expression of reference in delegation mechanism since PHP4.

$object = new Object;
$delegate->call($object); // since PHP4, functions will receive the copied value of $object.

$object = new Object;
$delegate->call(new XCube_Delegate($object)); // since PHP4, functions will receive the object.