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,
could gnomoaccess()
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
function:errorlog()
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.