MODULES - index

A definition of a THIS Module.

All this is going to change as we are moving to eliminate all global data.

For THIS, a module is a PHP source file that has some internal data that it, and it alone, manages. A module is one step above an API. (An API is just a number of related functions all in one file.)

A module is like a class without a class (which is discussed below). A module has the following attributes:

  • Is only included by INDEX.PHP.
  • Exists in the same location as INDEX.PHP.
  • Will create and/or initialize it's own data when included.
  • Will provide an interface (functions) to access it's data.
  • Has a limited API.

Conceptually, a module has four "sections":

  • Header Comments briefly describing the module.
  • Module Support function calls (see below).
  • Internal Data initialization (can be a function call).
  • Functions.

There are two support functions for modules:

        setmodule()			set global to module name
        debug( string )			log string to logging array

They are described below. Usually, a module initializes it's internal data with a function named after the module name, and that function is called near the top of the file:

        _module_config();

Here is a sample module, "gnomo":

        <?php

        
/* GNOMO.PHP - This sets up the Factory Object Pattern View Modeler */

        
setmodule();
        
_gnomo_config();

        function 
gnomostart() {
            global 
$gnomo;
            ...
        }

        function 
gnomoaccess() {
            global 
$gnomo;
            ...
        }

        function 
_gnomo_config() {
            global 
$gnomo;

            
$gnomo['name'] = "some name or something";
            
$gnomo['whatever'] = "anything goes here";
            ...
        }
        
?>

A module's data is a module's data and a module's data is not visible to the main code or any other module — not directly. A module can define a function that returns any or all of it's data, or not. A module does not even have to have data (but then it is just an API and not a module and belongs in the INC directory). For example, gnomoaccess() could return $gnomo;.

If you hate globals (or if you have been told to hate globals), see the end of this file for a discussion.

Support Functions

Modules "connect" with the main code in two ways: a "current module name" string, and a debug() function — used while a module initializes itself.

(Note that while this documentation is taking up a lot of words, the actual implementation details of modules is quite small.)

During initialization a developer just might want to know what is happening, and the support functions, um, support this.

The setmodule() function tells the message logging code which module is currently initializing and stores the module's name. A companion to this is the modules_loaded() function which will display all loaded modules (useful as a shutdown function if there is an error with one of the modules starting up and you are not sure which one; i.e. a "blank screen" error).

The debug() function keeps an array of strings to be printed, if enabled, upon program termination. The debug setting is set in CONFIG.INI:

        debug = 1

See file DEBUGGING for more information about the debug() function.

For example, if we had these files:

        INDEX.PHP

        	include "error.php";
        	include "config.php";
        	include "html.php";

        	setmodule();
        	debug("all's well that end's well!");

        CONFIG.PHP

        	setmodule()
        	debug("okay!");

        HTML.PHP

        	setmodule()
        	debug("yes!");

The debug() output at program termination would be:

        config.php:okay!
        html.php:yes!
        all's well that end's well!

There is a companion debug setting, debugmod which can be set the the name of the module you want only see messages for:

        debugmod = html.php

Two one more things. The debug setting can be changed within the code by the errorlog() function:

        errorlog(-1);

for example would make all subsequent debug statements print immediately.

The debug setting can be changed by the URL if you are logged in as Administrator: if you see an error in the output, just add debug=-1 on the URL and re-run the program — chances are you'll see what went wrong.