document all functions

ChangeLog

@@ -10,7 +10,7 @@ $Source$
 
 2005-11-28 Michal Čihař  <michal@cihar.com>
     * scripts/setup.php: Don't allow loading of configuration if there is no
-      write permission on config.
+      write permission on config, document all functions.
     * libraries/auth/cookie.auth.lib.php: Display PMA_errors on login form.
     * Documentation.html: Add anchors to configuration directives.
     * scripts/setup.php: Add links to documentation.

scripts/setup.php

@@ -4,10 +4,6 @@
 
 // phpMyAdmin setup script by Michal Čihař <michal@cihar.com>
 
-// TODO: 
-// - links to documentation
-// - document functions
-
 // Grab phpMyAdmin version and PMA_dl function
 $cfg['GD2Available'] = 'auto';
 require('../libraries/defines.lib.php');
@@ -22,6 +18,13 @@ require('../config.default.php');
 $default_cfg = $cfg;
 unset($cfg);
 
+/**
+ * Removes slashes from string if needed (eg. magic quotes are enabled)
+ *
+ * @param   string  prossibly escaped string
+ *
+ * @return  string  unsescaped string
+ */
 function remove_slashes($val) {
     if (get_magic_quotes_gpc()) {
         return stripslashes($val);
@@ -30,7 +33,7 @@ function remove_slashes($val) {
 }
 
 
-// Grab some variables
+// Grab action
 if (isset($_POST['action'])) {
     $action = $_POST['action'];
 } else {
@@ -38,23 +41,30 @@ if (isset($_POST['action'])) {
 }
 
 if (isset($_POST['cfg']) && $action != 'clear' ) {
+    // Grab previous configuration, if it should not be cleared
     $cfg = unserialize(remove_slashes($_POST['cfg']));
 } else {
+    // Start with empty configuration
     $cfg = array();
 }
+
+// We rely on Servers array to exist, so create it here
 if (!isset($cfg['Servers']) || !is_array($cfg['Servers'])) {
     $cfg['Servers'] = array();
 }
 
+// Used later
 $now = gmdate('D, d M Y H:i:s') . ' GMT';
 
-// whether to show html header?
+// General header for no caching
-if ($action != 'download') {
-
 header('Expires: ' . $now); // rfc2616 - Section 14.21
 header('Last-Modified: ' . $now);
 header('Cache-Control: no-store, no-cache, must-revalidate, pre-check=0, post-check=0, max-age=0'); // HTTP/1.1
 header('Pragma: no-cache'); // HTTP/1.0
+
+// whether to show html header?
+if ($action != 'download') {
+
 // Define the charset to be used
 header('Content-Type: text/html; charset=utf-8');
 
@@ -225,10 +235,26 @@ echo '<?xml version="1.0" encoding="utf-8"?>' . "\n";
 <?php
 } // end show html header
 
+/**
+ * Returns link to documentation of some configuration directive
+ *
+ * @param   string  confguration directive name
+ *
+ * @return  string  HTML link to documentation
+ */
 function get_cfg_doc($anchor) {
     return '<a href="../Documentation.html#cfg_' . $anchor . '" target="pma_doc" class="doc"><img class="icon" src="../themes/original/img/b_help.png" width="11" height="11" alt="Documentation" title="Documentation" /></a>';
 }
 
+/**
+ * Displays message
+ *
+ * @param   string  type of message (notice/warning/error)
+ * @param   string  text of message
+ * @param   title   optional title of message
+ *
+ * @return  nothing
+ */
 function message($type, $text, $title = '') {
     echo '<div class="' . $type . '">' . "\n";
     if (!empty($title)) {
@@ -240,16 +266,26 @@ function message($type, $text, $title = '') {
     echo '</div>' . "\n";
 }
 
+/**
+ * Creates hidden input required for keeping current configuraion
+ *
+ * @return string   HTML with hidden inputs
+ */
 function get_hidden_cfg() {
     global $cfg;
     
     return '<input type="hidden" name="cfg" value="' . htmlspecialchars(serialize($cfg)) . '" />' . "\n";
 }
 
-function show_hidden_cfg() {
+/**
-    echo get_hidden_cfg();
+ * Creates form for some action
-}
+ *
-
+ * @param   string  action name
+ * @param   string  form title
+ * @param   string  optional additional inputs
+ *
+ * @return  string  HTML with form
+ */
 function get_action($name, $title, $added = '') {
     $ret = '';
     $ret .= '<form class="action" method="POST">';
@@ -262,15 +298,23 @@ function get_action($name, $title, $added = '') {
     return $ret;
 }
 
-function show_action($name, $title, $added = '') {
+/**
-    echo get_action($name, $title, $added);
+ * Terminates script and ends HTML
-}
+ *
-
+ * @return nothing
+ */
 function footer() {
     echo '</body>';
     exit;
 }
 
+/**
+ * Creates string describing server authentication method
+ *
+ * @param   array   server configuration
+ *
+ * @return  string  authentication method description
+ */
 function get_server_auth($val) {
     global $default_cfg;
     
@@ -290,6 +334,14 @@ function get_server_auth($val) {
     return $ret;
 }
 
+/**
+ * Creates nice string with server name
+ *
+ * @param   array   server configuration
+ * @param   int     optional server id
+ *
+ * @return  string  fancy server name
+ */
 function get_server_name($val, $id = FALSE) {
     if (!empty($val['verbose'])) {
         $ret = htmlspecialchars($val['verbose']);
@@ -303,8 +355,15 @@ function get_server_name($val, $id = FALSE) {
     return $ret;
 }
 
-function get_cfg_string() {
+/**
-    global $cfg, $script_info, $script_version, $now;
+ * Creates configuration PHP code 
+ *
+ * @param   array   configuration
+ *
+ * @return  string  PHP code containing configuration
+ */
+function get_cfg_string($cfg) {
+    global $script_info, $script_version, $now;
 
     $c = $cfg;
     $ret = "<?php\n/*\n * Generated configuration file\n * Generated by: $script_info\n * Version: $script_version\n * Date: " . $now . "\n */\n\n";
@@ -357,9 +416,14 @@ function get_cfg_string() {
     return $ret;
 }
 
-function compress_servers() {
+/**
-    global $cfg;
+ * Comresses server configuration to be indexed from 0 and contain no gaps
-
+ *
+ * @param   array   configuration
+ *
+ * @return  nothing
+ */
+function compress_servers(&$cfg) {
     $ns = array();
     foreach ($cfg['Servers'] as $val) {
         if (!empty($val['host'])) {
@@ -369,6 +433,18 @@ function compress_servers() {
     $cfg['Servers'] = $ns;
 }
 
+/**
+ * Grabs values from POST
+ *
+ * @param   string   list of values to grab, values are separated by ";", 
+ *                   each can have defined type separated by ":", if no type
+ *                   is defined, string is assumed. Possible types: bool -
+ *                   boolean value, serialized - serialized value, int -
+ *                   integer, tristate - "TRUE"/"FALSE" converted to bool,
+ *                   other strings are kept.
+ *
+ * @return  array   array with grabbed values
+ */
 function grab_values($list) {
     $a = split(';', $list);
     $res = array();
@@ -401,6 +477,7 @@ function grab_values($list) {
                     }
                 }
                 break;
+            case 'string':
             default:
                 if (isset($_POST[$v[0]]) && strlen($_POST[$v[0]]) > 0) {
                     $res[$v[0]] = remove_slashes($_POST[$v[0]]);
@@ -411,9 +488,19 @@ function grab_values($list) {
     return $res;
 }
 
-function show_overview($legend, $list, $buttons = '') {
+/**
+ * Displays overview
+ *
+ * @param   string  title of oveview
+ * @param   array   list of values to display (each element is array of two
+ *                  values - name and value)
+ * @param   string  optional buttons to be displayed
+ *
+ * @return  nothing
+ */
+function show_overview($title, $list, $buttons = '') {
     echo '<fieldset class="overview">' . "\n";
-    echo '<legend>' . $legend . '</legend>' . "\n";
+    echo '<legend>' . $title . '</legend>' . "\n";
     foreach($list as $val) {
         echo '<div class="row">';
         echo '<div class="desc">';
@@ -434,6 +521,22 @@ function show_overview($legend, $list, $buttons = '') {
     echo "\n";
 }
 
+/**
+ * Displays configration, fallback defaults are taken from global $default_cfg
+ *
+ * @param   array   list of values to display (each element is array of two or
+ *                  three values - desription, name and optional type
+ *                  indicator). Type is determined by type of this parameter,
+ *                  array means select and array elements are items,
+ *                  'password' means password input.
+ * @param   string  title of configuration
+ * @param   string  help string for this configuration
+ * @param   array   optional first level defaults
+ * @param   string  optional title for save button
+ * @param   string  optional prefix for documentation links
+ *
+ * @return  nothing
+ */
 function show_config_form($list, $legend, $help, $defaults = array(), $save = '', $prefix = '') {
     global $default_cfg;
     
@@ -518,12 +621,19 @@ function show_config_form($list, $legend, $help, $defaults = array(), $save = ''
     echo "\n";
 }
 
+/**
+ * Shows security options configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_security_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_security_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Blowfish secret', 'blowfish_secret', 'Secret passhrase used for encrypting cookies'),
             array('Force SSL connection', 'ForceSSL', 'Whether to force using secured connetion while using phpMyAdmin', FALSE),
@@ -541,12 +651,19 @@ function show_security_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows MySQL manual configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_manual_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_manual_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Type of MySQL documentation', 'MySQLManualType', 'These types are same as listed on MySQL download page', array('viewable', 'chapters', 'big', 'none')),
             array('Base URL of MySQL documentation', 'MySQLManualBase', 'Where is MySQL documentation placed, this is usually top level directory.'),
@@ -559,13 +676,20 @@ function show_manual_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows charset options configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_charset_form($defaults = array()) {
     global $default_cfg;
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_charset_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Allow charset conversion', 'AllowAnywhereRecoding', 'If you want to use such functions.', FALSE),
             array('Default charset', 'DefaultCharset', 'Default charset for conversion.', $default_cfg['AvailableCharsets']),
@@ -580,13 +704,20 @@ function show_charset_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows PHP extensions configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_extensions_form($defaults = array()) {
     global $default_cfg;
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_extensions_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('GD 2 is available', 'GD2Available', 'Whether you have GD 2 or newer installed', array('auto', 'yes', 'no')),
             ), 
@@ -598,13 +729,20 @@ function show_extensions_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows MIME/relation/history configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_relation_form($defaults = array()) {
     global $default_cfg;
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_relation_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Parmanent query history', 'QueryHistoryDB', 'Store history into database.', FALSE),
             array('Maximal history size', 'QueryHistoryMax', 'How many queries are kept in history.'),
@@ -619,12 +757,19 @@ function show_relation_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows upload/save configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_upload_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="feat_upload_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Upload directory', 'UploadDir', 'Directory on server where you can upload files for import'),
             array('Save directory', 'SaveDir', 'Directory where exports can be saved on server'),
@@ -638,12 +783,19 @@ function show_upload_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows server configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_server_form($defaults = array(), $number = FALSE) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="addserver_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         if (!($number === FALSE)) {
             echo '<input type="hidden" name="server" value="' . $number . '" />';
         }
@@ -677,12 +829,19 @@ function show_server_form($defaults = array(), $number = FALSE) {
     <?php
 }
 
+/**
+ * Shows left frame configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_left_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_left_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Use light version', 'LeftFrameLight', 'Disable this if you want to see all databases at one time.', TRUE),
             array('Display databases in tree', 'LeftFrameDBTree', 'Whether to display databases in tree (determined by separator defined lower)', TRUE),
@@ -701,12 +860,19 @@ function show_left_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows tabs configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_tabs_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_tabs_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Default tab for server', 'DefaultTabServer', 'Tab that is displayed when entering server', array('main.php', 'server_databases.php', 'server_status.php', 'server_variables.php', 'server_privileges.php', 'server_processlist.php')),
             array('Default tab for database', 'DefaultTabDatabase', 'Tab that is displayed when entering database', array('db_details_structure.php', 'db_details.php', 'db_search.php', 'db_operations.php')),
@@ -721,12 +887,19 @@ function show_tabs_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows icons configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_icons_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_icons_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Icons on errors', 'ErrorIconic', 'Whether to use icons in error messages.', TRUE),
             array('Icons on main page', 'MainPageIconic', 'Whether to use icons on main page.', TRUE),
@@ -742,12 +915,19 @@ function show_icons_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows browsing  configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_browse_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_browse_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Display of values', 'DefaultDisplay', 'How to list values while browsing', array('horizontal', 'vertical', 'horizontalflipped')),
             array('Hightlight pointer', 'BrowsePointerEnable', 'Whether to highlight row under mouse.', TRUE),
@@ -764,12 +944,19 @@ function show_browse_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows editing options configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_edit_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_edit_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Display of properties editation', 'DefaultPropDisplay', 'How to list properties (table structure or values) while editing', array('horizontal', 'vertical')),
             array('Number of inserted rows', 'InsertRows', 'How many rows can be inserted at once'),
@@ -790,12 +977,19 @@ function show_edit_form($defaults = array()) {
     <?php
 }
 
+/**
+ * Shows query window configuration form
+ *
+ * @param   array   optional defaults
+ *
+ * @return  nothing
+ */
 function show_window_form($defaults = array()) {
     ?>
 <form method="post">
     <input type="hidden" name="action" value="lay_window_real" />
     <?php 
-        show_hidden_cfg(); 
+        echo get_hidden_cfg(); 
         show_config_form(array(
             array('Edit SQL in window', 'EditInWindow', 'Whether edit links will edit in query window.', TRUE),
             array('Query window height', 'QueryWindowHeight', 'Height of query window'),
@@ -810,8 +1004,14 @@ function show_window_form($defaults = array()) {
     <?php
 }
 
-function get_server_selection() {
+/**
-    global $cfg;
+ * Creates selection with servers
+ *
+ * @param   array   configuraion
+ *
+ * @return  string  HTML for server selection
+ */
+function get_server_selection($cfg) {
     if (count($cfg['Servers']) == 0) return ''; 
     $ret = '<select name="server">';
     foreach ($cfg['Servers'] as $key => $val) {
@@ -835,21 +1035,23 @@ if ($action != 'download') {
     }
 }
 
+/**
+ * @var boolean whether to show configuration overview
+ */
 $show_info = FALSE;
 
+// Do the main work depending on selected action
 switch ($action) {
     case 'download':
         header('Content-Type: text/plain');
-        header('Expires: ' . $now);
         header('Content-Disposition: attachment; filename="config.inc.php"');
-        header('Pragma: no-cache');
 
-        echo get_cfg_string();
+        echo get_cfg_string($cfg);
         exit;
         break;
     case 'display':
         echo '<form method="none"><textarea name="config" cols="50" rows="20" id="textconfig" wrap="off">' . "\n";
-        echo htmlspecialchars(get_cfg_string());
+        echo htmlspecialchars(get_cfg_string($cfg));
         echo '</textarea></form>' . "\n";
         ?>
 <script language="javascript" type="text/javascript">
@@ -880,7 +1082,7 @@ switch ($action) {
             message('error', 'Could not open config file for writing! Bad permissions?');
             break;
         }
-        $s = get_cfg_string();
+        $s = get_cfg_string($cfg);
         $r = fwrite($config, $s);
         if (!$r || $r != strlen($s)) {
             message('error', 'Could not write to config file! Not enough space?');
@@ -918,7 +1120,7 @@ switch ($action) {
                 $cfg = $bck_cfg;
             } else {
                 message('notice', 'Configuration loaded');
-                compress_servers();
+                compress_servers($cfg);
             }
         } else {
             message('error', 'Configuration file not found!');
@@ -1032,7 +1234,7 @@ switch ($action) {
         if (!isset($_POST['server'])) footer();
         message('notice', 'Deleted server ' . get_server_name($cfg['Servers'][$_POST['server']], $_POST['server']));
         unset($cfg['Servers'][$_POST['server']]);
-        compress_servers();
+        compress_servers($cfg);
         $show_info = TRUE;
         break;
     case 'servers':
@@ -1390,6 +1592,31 @@ switch ($action) {
         show_window_form($cfg);
         break;
 
+/* Template for new actions: 
+    case 'blah_real':
+        if (isset($_POST['submit_save'])) {
+            $vals = grab_values('value1:bool;value2');
+            $err = FALSE;
+            if (somechekcfails) {
+                message('error', 'Invalid value for blah!');
+                $err = TRUE;
+            }
+            if ($err) {
+                show_blah_form($vals);
+            } else {
+                $cfg = array_merge($cfg, $vals);
+                message('notice', 'Configuration changed');
+                $show_info = TRUE;
+            }
+        } else {
+            $show_info = TRUE;
+        }
+        break;
+    case 'blah':
+        show_blah_form($cfg);
+        break;
+*/
+
     case 'clear': // Actual clearing is done on beginning of this script
     case 'main':
         $show_info = TRUE;
@@ -1409,6 +1636,7 @@ switch ($action) {
         break;
 }
 
+// Should we show information?
 if ($show_info) {
     $servers = 'none';
     $servers_text = 'Servers';
@@ -1436,45 +1664,46 @@ if ($show_info) {
     unset($servers_text, $servers);
 }
 
+// And finally display all actions:
 echo '<p>Available global actions (please note that these will delete any changes you could have done above):</p>';
 
 echo '<fieldset class="toolbar"><legend>Servers</legend>' . "\n";
-show_action('addserver', 'Add');
+echo get_action('addserver', 'Add');
-$servers = get_server_selection();
+$servers = get_server_selection($cfg);
 if (!empty($servers)) {
-    show_action('servers', 'List');
+    echo get_action('servers', 'List');
-    show_action('deleteserver', 'Delete', $servers);
+    echo get_action('deleteserver', 'Delete', $servers);
-    show_action('editserver', 'Edit', $servers);
+    echo get_action('editserver', 'Edit', $servers);
 }
 echo '</fieldset>' . "\n\n";
 
 echo '<fieldset class="toolbar"><legend>Layout</legend>' . "\n";
-show_action('lay_left', 'Left frame');
+echo get_action('lay_left', 'Left frame');
-show_action('lay_tabs', 'Tabs');
+echo get_action('lay_tabs', 'Tabs');
-show_action('lay_icons', 'Icons');
+echo get_action('lay_icons', 'Icons');
-show_action('lay_browse', 'Browsing');
+echo get_action('lay_browse', 'Browsing');
-show_action('lay_edit', 'Editing');
+echo get_action('lay_edit', 'Editing');
-show_action('lay_window', 'Query window');
+echo get_action('lay_window', 'Query window');
 echo '</fieldset>' . "\n\n";
 
 echo '<fieldset class="toolbar"><legend>Features</legend>' . "\n";
-show_action('feat_upload', 'Upload/Download');
+echo get_action('feat_upload', 'Upload/Download');
-show_action('feat_security', 'Security');
+echo get_action('feat_security', 'Security');
-show_action('feat_manual', 'MySQL manual');
+echo get_action('feat_manual', 'MySQL manual');
-show_action('feat_charset', 'Charsets');
+echo get_action('feat_charset', 'Charsets');
-show_action('feat_extensions', 'Extensions');
+echo get_action('feat_extensions', 'Extensions');
-show_action('feat_relation', 'MIME/Relation/History');
+echo get_action('feat_relation', 'MIME/Relation/History');
 echo '</fieldset>' . "\n\n";
 
 echo '<fieldset class="toolbar"><legend>Configuration</legend>' . "\n";
-show_action('main', 'Overview');
+echo get_action('main', 'Overview');
-show_action('display', 'Display');
+echo get_action('display', 'Display');
-show_action('download', 'Download');
+echo get_action('download', 'Download');
 if (!$fail_dir) {
-    show_action('save', 'Save');
+    echo get_action('save', 'Save');
-    show_action('load', 'Load');
+    echo get_action('load', 'Load');
 }
-show_action('clear', 'Clear');
+echo get_action('clear', 'Clear');
 echo '</fieldset>' . "\n\n";
 
 footer();