File/program/lib/toolslib.php

Description

/program/lib/toolslib.php - tools

Constants
CHORE_SESSION_DELETE = delete (line 34)
CHORE_SESSION_VIEW = view (line 33)
TASK_BACKUPTOOL = backuptool (line 31)
TASK_LOGVIEW = logview (line 35)
TASK_SESSIONTOOL = sessiontool (line 32)
TASK_TOOLS_INTRO = intro (line 29)
TASK_TRANSLATETOOL = translatetool (line 30)
Functions
job_tools (line 47)

main entry point for tools (called from /program/main_admin.php)

this routine dispatches the tasks, If the specified task is not recognised, the default task TASK_TOOLS_INTRO is executed.

  • return: results are returned as output in $output
  • todo: fix permissions for backup tool! perhaps another bit?
void job_tools (object &$output)
  • object &$output: collects the html output
logview_download (line 808)

download records from the log table in CSV format

this sends the contents of the logtable upto (but excluding) the record with pkey = $pivot to the user in CSV format

the suggested filename contains the name of the host and the first and the last pkey of the records exported. This allows for downloading logs from different hosts and multiple times from the same host without name clashes.

If there are errors or no records nothing is sent to the user (but we do try to log the event).

Note The number Nr displayed in the overview (see logview_show()) is just a number starting at 1 every time. The download file works with the real record pkey.

  • return: CSV output directly, $output suppressed
void logview_download (object &$output, int $pivot)
  • object &$output: collects output to show to user
  • int $pivot: download limit: pkey must be < $pivot
logview_priority (line 982)

helper routine to translate a numeric priority to human readable text

look up the symbolic name of priority $p

[Rant]
I used to use the built-in constants like LOG_INFO and LOG_DEBUG to allow for different levels of logging (see logger()). To my complete surprise logging didn't work at all on Windows (it did on Linux). The reason was that LOG_DEBUG and LOG_INFO and LOG_NOTICE are all defined to be the same value. WTF? Any test based on LOG_DEBUG and LOG_INFO being different would fail, hence no logging at all. The mind boggles! So, instead of using built-in constants I had to define my own and do a global search&replace. Aaarghhhhhh!!!!
[/Rant]

  • return: readable priority
string logview_priority (int $p)
  • int $p: numeric value priority
logview_prune (line 866)

ask for confirmation and/or maybe execute pruning of log messages table

shows confirmation screen including download link and also actually process the deletions if the user confirmed. We give the user another opportunity to download the selected records before pruning.

  • return: output written to $output
void logview_prune (object &$output, int $pivot)
  • object &$output: collects output to show to user
  • int $pivot: download limit: pkey must be < $pivot
logview_show (line 671)

show entries from log table in a neat HTML-table (possibly paginated)

this constructs a table of the HTML-variety with the contents of the logtable. fields displayed are: datim, IP-address, username, logpriority and message we use a LEFT JOIN in order to get to a meaningful username rather than a numeric user_id an attempt is made to start with the last page of the logs because that would probably be the most interesting part. We paginate the log in order to keep it manageable.

  • return: output displayed via $output
void logview_show (object &$output, [null|int $offset = NULL])
  • object &$output: collects output to show to user
  • null|int $offset: indicates where to start the listing, NULL=consult GET parameters
sessions_delete (line 531)

handle confirmation and actual delete of a session

this single routine handles

  • the display of a confirmation message,
  • handling of the actual delete, and
  • handling of the bail out/cancelbutton

  • return: output written via $output
void sessions_delete (object &$output, int $session_id)
  • object &$output: collects the html output
  • int $session_id
sessions_show (line 343)

show a table with sessions

display a table with sessions and locked nodes per session

If $id is NULL, all current sessions+locks are displayed, if $id is a specific session_id only that session is displayed. (used in the session delete chore, see sessions_delete()).

If $show_delete is TRUE a link is displayed that allows the user to delete a session, if FALSE no link is displayed.

  • return: FALSE on error, number of selected sessions otherwise
mixed sessions_show (object &$output, [mixed $id = NULL], [bool $show_delete = TRUE])
  • object &$output: collects the html output
  • mixed $id: select which session(s) to display (Null means all)
  • bool $show_delete: if TRUE show clickable links to delete option
sessions_show_footer (line 514)

close the HTML-table

  • return: html written to $output
void sessions_show_footer (object &$output)
  • object &$output: collects the html output
sessions_show_header (line 397)

show the header of the HTML-table

| D | sss | ctime | atime | username (full_name) | ip_addr |
|     nnn | ltime | link_text (title)                      |

the HTML-table has 5 or 6 columns, depending on $show_delete. the header takes two rows: one for the session information, and another for the node lock information.

Parameter $class is used for styling of the table header.

  • return: html written to $output
void sessions_show_header (object &$output, string &$class, [bool $show_delete = TRUE])
  • object &$output: collects the html output
  • string &$class: attribute of table rows and cells
  • bool $show_delete: if TRUE show clickable links to delete option
sessions_show_node_locked (line 489)

show locked node information from a single (combined) record

the HTML-table has 5 or 6 columns, depending on $show_delete. Parameter $class is used for styling of the table row. The value is toggled between 'odd' and 'even'.

  • return: html written to $output
void sessions_show_node_locked (object &$output, array &$record, string &$class, [bool $show_delete = TRUE])
  • object &$output: collects the html output
  • array &$record: contains session and lock information
  • string &$class: attribute of table rows and cells
  • bool $show_delete: if TRUE show clickable links to delete option
sessions_show_overview (line 320)

show an overview of currently existing sessions

  • return: results are returned as output in $output
void sessions_show_overview (object &$output)
  • object &$output: collects the html output
sessions_show_session (line 436)

show session information from a single (combined) record

the HTML-table has 5 or 6 columns, depending on $show_delete. Parameter $class is used for styling of the table row. The value is toggled between 'odd' and 'even'.

  • return: html written to $output
void sessions_show_session (object &$output, array &$record, string &$class, [bool $show_delete = TRUE])
  • object &$output: collects the html output
  • array &$record: contains session and lock information
  • string &$class: attribute of table rows and cells
  • bool $show_delete: if TRUE show clickable links to delete option
show_tools_intro (line 123)

display an introductory text for tools + menu

  • return: results are returned as output in $output
void show_tools_intro (object &$output)
  • object &$output: collects the html output
show_tools_menu (line 135)

display the tools menu

  • return: results are returned as output in $output
void show_tools_menu (object &$output, [string $current_task = NULL])
  • object &$output: collects the html output
  • string $current_task: indicate the current menu selection (if any)
task_backuptool (line 218)

show an introductory text for backup tool OR stream a ZIP-file to the browser

If we arrive here via the tools menu, the parameter download is not set. In that case we show an introductory text with a link that yields a ZIP-file with the backup.

If the user follows the download link, we arrive here too but with the download parameter set. We then dump the database in a variable and subsequently compress it in a ZIP-file which we stream to the browser. We do code some things in the basename of the backup:

  • the hostname
  • the database name
  • the database prefix
  • the date and the time
which should be enough to distinguish nearly all backups if you happen to have a lot of different ones. Note that the URL is also encoded as a comment in the .ZIP.

The parameter download is currently set to 'zip'. However, we do attempt to send the plain uncompressed data if that parameter is set to 'sql' (quick and dirty). Oh well. hopefully there is enough memory to accomodate backups of moderate sized sites.

Note that we need space to compress the data; a informal test yielded that we need about 160% of the uncompressed size of the backup (tested with a small testset). Rule of the thumb for memory: the more the merrier but at least twice the size of the uncompressed backup.

  • return: displayed via $output OR ZIP-file streamed to the browser
output task_backuptool (object &$output)
  • object &$output: collects output to show to user
task_logview (line 646)

quick and dirty logfile view / download / prune tool

this is the dispatcher that decides whether to show entries, download entries or prune the logs

  • return: output displayed via $output
  • todo: should we allow for fancy selection mechanisms on the logfile or is that over the top?
void task_logview (object &$output)
  • object &$output: collects output to show to user
task_sessiontool (line 290)

main entry point for session management

  • return: results are returned as output in $output
void task_sessiontool (object &$output)
  • object &$output: collects the html output
tools_get_hostname (line 949)

helper routine to construct something that looks like this hosts name

string tools_get_hostname ()

Documentation generated on Tue, 28 Jun 2016 19:12:18 +0200 by phpDocumentor 1.4.0