File/program/init.php

Description

/program/init.php - setup database connection, sessions, configuration, etc.

This file is included from one of the main entry points. The following subsystems and global variables are initialised:

  • connection to the database
  • session handler
  • $CFG
  • etc.
This file is included at a fairly early stage in the process. It does not rely on any regular libraries which are include()'ed lateron. That is: all relevant libraries (such as waslib.php are included when necessary from within the function initialise().

Note that this file is _the_ place to defined truly global constants because it is always include()'d.

Constants
MAXIMUM_ITERATIONS = 50 (line 46)

This global constant defines the maximum number of iterations in database loops (prevent circular reference)

THUMBNAIL_PREFIX = zz_thumb_ (line 43)

This global constant is used to specify thumbnail files to be ignored in directory listings

WLOG_ALERT = 1 (line 52)

This global constant replaces a similar built-in constant LOG_ALERT which is defined as 1 in win32.h

WLOG_CRIT = 2 (line 55)

This global constant replaces a similar built-in constant LOG_CRIT which is erroneously defined as 1 in win32.h

WLOG_DEBUG = 7 (line 70)

This global constant replaces a similar built-in constant LOG_DEBUG which is erroneously defined as 6 in win32.h

WLOG_EMERG = 0 (line 49)

This global constant replaces a similar built-in constant LOG_EMERG which is erroneously defined as 1 in win32.h

WLOG_ERR = 3 (line 58)

This global constant replaces a similar built-in constant LOG_ERR which is erroneously defined as 4 in win32.h

WLOG_INFO = 6 (line 67)

This global constant replaces a similar built-in constant LOG_INFO which is defined as 6 in win32.h

WLOG_NOTICE = 5 (line 64)

This global constant replaces a similar built-in constant LOG_NOTICE which is erroneously defined as 6 in win32.h

WLOG_WARNING = 4 (line 61)

This global constant replaces a similar built-in constant LOG_WARNING which is erroneously defined as 5 in win32.h

Functions
diff_microtime (line 372)

Calculate the difference between two microtimes

  • return: interval between the two times (in seconds)
double diff_microtime (string $time_start, string $time_stop)
  • string $time_start: starting time as a string (fractional seconds, space, seconds)
  • string $time_stop: ending time as a string (fractional seconds, space, seconds)
error_exit (line 320)

emergency exit of program in case there is something really, really wrong

This routine outputs a short message and a 'cryptic' condition code and exits the program. It is called when something goes horribly wrong during the early stages of running the program, e.g. the database cannot be opened or there is a version mismatch between the program code (the .php-files) and the database. The complete condition code is the WAS release number followed by a slash followed by the WAS version number followed by a slash and the bare condition code. The message ends with a link to about.html with 'Powered by' or 'Based on', depending on the WAS original flag. Note that we try to show graphics (including logo) but that we switch back to text-only if it is too early, ie. before waslib.php is included.

Here is an overview of meaning of the condition codes used.

  • 010: cannot find config.php, is W@S installed at all?
  • 015: cannot find program/main_XXXXX.php, is W@S installed at all?
  • 017: cannot calculate wasentry_script_name, are we being tricked?
  • 020: configuration error, invalid database type
  • 030: cannot connect to database, busy or configuration error?
  • 040: error accessing the database, is W@S installed at all?
  • 050: version mismatch, update to new version necessary
  • 060: magic_quotes_sybase is On
  • 070: there is no (default) node available in this (default) area
  • 080: there is no area available
  • 090: there is no valid theme available
The condition code is numeric because it is easier to report for non-English speaking users than a complicated English sentence. (The language files are not yet loaded when error_exit() is called).

If the user was logged inwhen this fatal error happens, e.g. she requested a protected area, logged in but access was denied anyway, a small postfix is added to the condition code: an asterisk. This indicates that the logged in user was logged out as part of this error exit. This way (hopefully) the session will no longer be available after this error exit.

  • return: this function never returns
  • todo: Q: do we really want to 'leak' a link to the main site?
  • uses: WAS_VERSION - indicate internal version in 'cryptic' message
  • uses: $WAS_SCRIPT_NAME
  • uses: $USER
  • uses: $CFG
void error_exit (string $bare_condition_code, [string $page_title = 'Fatal Error'])
  • string $bare_condition_code: the bare condition code to report
  • string $page_title: the title to show in the generated HTML-page
initialise (line 76)

initialise the program, setup database, read configuration, etc.

void initialise ()
wasentry_script_name (line 391)

determine the name of the executing script (the entry point)

this routine tries to reach consensus about the name of the script that was the entry point. This is not as easy as it sounds.

See install_script_name() for an exhausing discussion of the issues.

  • return: the path of the entry point relative to the document root, e.g. '/was/index.php' or we die() on error
string wasentry_script_name (string $full_wasentry_path)
  • string $full_wasentry_path: is the full path of the entry point, e.g. '/home/httpd/htdocs/was/index.php'
was_version_check (line 255)

check version of PHP-files against version stored in database

this checks the main WAS_VERSION (of files) against $CFG->version (database). if all is well, we return TRUE indicating both version numbers match. If there is a discrepancy it is logged and depending on parameter $exit_on_error we either exit alltogether OR we return FALSE to indicate the version mismatch.

Typical use is to call this routine near the start as follows (e.g. in main_index.php or main_file.php):

    ... initialise(); was_version_check(); // Still here? Then version is OK ...

This forces an exit for the interfaces at the 'visitor' side. For the webmaster it is different: even if the versions do not match, we want to be able to login and do something about it via some sort of upgrade routine, e.g:

    ... initialise(); if (!was_version_check(FALSE)) {   do_upgrade(); } else {   do_regular_admin(); } ...

  • return: TRUE if versions match, FALSE if mismatch and not $exit_on_error, no return at all otherwise
bool|void was_version_check ([bool $exit_on_error = TRUE])
  • bool $exit_on_error: if TRUE, this routine only returns if versions match, if FALSE a mismatch is fatal

Documentation generated on Tue, 28 Jun 2016 19:09:52 +0200 by phpDocumentor 1.4.0