<?php

/*
   sam_lib.php
   
   (c) 2011-2012, Sam D. Gwilliam
   
   A collection of useful functions:
   
>      generateTableRowFromArray ($array, [$type], [$echo])
      
         - Generates an HTML table row from a 1D array. Returns (and optionally echoes) the HTML.
         - Optional 'type' argument ("h" or "n") for creating heading (<th>) rows or normal (<td>) rows.
         - Optional 'echo' argument: if not NULL, also echoes the HTML (in addition to returning it).
         
>      generateVerticalTableFromArray ($array, [$class], [$echo])
      
         - Generates a vertical, 2-col HTML table from a 1D assoc. array. Returns (and optionally echoes) the HTML.
         - Each row is a name/value pair, rendered as <th> and <td> elements, respectively.
         - Optional 'class' argument (in <table> tag) for CSS styling.
         - Optional 'echo' argument: if not NULL, also echoes the HTML (in addition to returning it).
   
>      generateTableFromResult ($result, [$class], [$echo])
      
         - Generates an HTML table from a MySQL query result. Returns (and optionally echoes) the HTML.
         - Optional 'class' argument (in <table> tag) for CSS styling.
         - Optional 'echo' argument: if not NULL, also echoes the HTML (in addition to returning it).
         
>      countArrayDim ($array)
      
         - Recursively computes the dimensionality of a variable/array.
         - Returns 0 for a normal variable, 1 for a 1D array, 2 for a 2D array, etc...
         - Argument 2, [$count], is omitted here because the user must ignore it (and allow it to default to 0),
            it serves simply as a mechanism to pass the incrementing dimension count along the recursion chain!

   General notes:
   
      - Use of square brackets in this annotation (e.g. [$foo]) indicates an optional/hidden argument.
*/

// --- FUNCTIONS --------------------------------------------------------------------------------------------------------------

/*   
   generateTableRowFromArray ($result, [$type], [$echo])
   
   Takes a 1D array and generates a horizontal HTML table row.
   The row's contents can be headings (<th>), or normal data
   (<td>) - depending on the argument passed through $type.
   A mixture of <td> and <th> tags in a single row is not possible with this function.
   
   Optional 'type' argument:
      "n" = normal data (this is the default if $type is omitted for the call).
      "h" = heading data.
      
   Optional 'echo' argument allows direct echoing of HTML (in addition to it being returned).
   
   NOTE:
      This function only generates a single, complete ROW!
      It is up to you to place the function's output between a <table></table> pair!
*/

// Default "n" & NULL allows args 2 & 3 to be omitted:
function generateTableRowFromArray ($array, $type = "n", $echo = NULL)      
{
   $html = "<tr>";                     // Initialise HTML with table row opening.
   
   // Ensure array has content and is 1D:
   if ((sizeof ($array)) && (countArrayDim ($array) == 1))
   {
      $tag = ($type == "h" ? "th" : "td");   // Generate <th> or <td> tag, according to type.
         
      foreach ($array as $data)
         $html .= "<$tag>$data</$tag>";      // Add each data element, surrounded by the relevant tags.      
   }
      
   // Otherwise generate warning:
   else
      $html .= "<th>Warning: cannot generate table row.<br />Content empty or not a 1D array!</th>";
      
   $html .= "</tr>";                  // End row.
   
   // If desired, directly echo the table (in addition to returning the HTML to caller):
   if ($echo)
      echo ($html);      // Echo table row HTML.
      
   return $html;         // Return it, too, in case caller wishes to further process the HTML.
}

// ----------------------------------------------------------------------------------------------------------------------------

/*
   generateVerticalTableFromArray ($array, [$class], [$labels], [$echo])
   
   Takes a 1D associative array and generates a 2-column vertical HTML table.
   
   In other words, each table row is a name/value pair, as opposed to a horizontal
   table, where the first row contains all the names (as <th> elements) and the
   second row contains the respective values (as <td> elements).
   
   Optional 'class' argument allows for CSS styling.
   Optional 'labels' argument must be a numeric array, providing headings for both columns.
   Optional 'echo' argument allows direct echoing of HTML (in addition to it being returned).
*/
   
// Default NULLs allow args 2 & 3 to be omitted:
function generateVerticalTableFromArray ($array, $class = NULL, $labels = NULL, $echo = NULL)
{   
   $size = sizeof ($array);      // Get array size.
   
   $html = "<table";                           // Initialise HTML with partial <table> tag.
   $html .= ($class ? " class='$class'" : "") . ">";   // Add HTML class name (if present) and close.
   
   // Ensure array has content and is 1D:
   if (($size) && (countArrayDim ($array) == 1))
   {
      $name = array_keys ($array);   // Get names of each entry.

      // If labels not provided:
      if (!$labels)
         $html .= "<tr><th>Col A</th><th>Col B</th></tr>";      // Use default labels.
         
      else
      {
         $colA = $labels [0];      // Retrieve provided labels.
         $colB = $labels [1];

         $html .= "<tr><th>$colA</th><th>$colB</th></tr>";      // Use provided labels.
      }
            
      // Generate table content - each name/value pair row:
      for ($i = 0; $i < $size; $i++)
      {
         $key = $name [$i];                        // Store name of current element (also used to index $array []).
         
         $html .= "<tr><th>" . $key . "</th>";         // Open row and heading.
         $html .= "<td>" . $array [$key] . "</td></tr>";   // Content indexed by name ($key).
      }
   }
   
   // Otherwise generate warning:
   else
      $html .= "<tr><th>Warning: cannot generate vertical table.<br />Content empty or not a 1D array!</th></tr>";
      
   $html .= "</table>";                        // End table.
   
   // If desired, directly echo the table (in addition to returning the HTML to caller):
   if ($echo)
      echo ($html);      // Echo table HTML.
      
   return $html;         // Return it, too, in case caller wishes to further process the HTML.
}

// ----------------------------------------------------------------------------------------------------------------------------

/*   
   generateTableFromResult ($result, [$class], [$echo])
   
   Takes a MySQL 'result' object and generates an HTML table, with column headings
   (as they appear in the MySQL table) and an optional HTML class value (allowing
   for different queries to be formatted independently, according to your CSS).
   
   Optional 'class' argument allows for CSS styling.
   Optional 'echo' argument allows direct echoing of HTML (in addition to it being returned).
*/

// Default NULLs allow args 2 & 3 to be omitted:
function generateTableFromResult ($result, $class = NULL, $echo = NULL)      
{
   $rows = mysql_num_rows ($result);      // Row count of table (number of actual data rows, plus the row of col. names.
   $row = mysql_fetch_assoc ($result);      // Pre-emptively get first row (read-ahead).
   
   $html = "<table";                              // Initialise HTML with partial <table> tag.
   $html .= ($class ? " class='$class'" : "") . ">";      // Add HTML class name (if present) and close.
   
   // Ensure array from mysql_fetch_assoc () has content and is 1D (i.e. actually a row):
   if ((sizeof ($row)) && (countArrayDim ($row) == 1))
   {
      $headings = array_keys ($row);         // Use first row to extract key names for column headings.

      // Display column headings row:
      $html .= generateTableRowFromArray ($headings, "h");   // "h" ensures use of <th> instead of <td>.   

      // Display each results row:
      for ($i = 0; $i < $rows; $i++)
      {
         $html .= generateTableRowFromArray ($row);      // Type omitted, so normal table data (i.e. <td>).
         $row = mysql_fetch_assoc ($result);            // Fetch next row from result for next iteration.
      }
      
      mysql_data_seek ($result, 0);   // Go back to start of query in case of subsequent calls!
   }
   
   // Otherwise generate warning:
   else
      $html .= "<tr><th>Warning: cannot generate query table.<br />Query empty or 'row' not a 1D array!</th></tr>";
      
   $html .= "</table>";         // End table.
   
   // If desired, directly echo the table (in addition to returning the HTML to caller):
   if ($echo)
      echo ($html);      // Echo table HTML.
      
   return $html;         // Return it, too, in case caller wishes to further process the HTML.
}

// ----------------------------------------------------------------------------------------------------------------------------

/*
   countArrayDim ($array, [$count])
   
   Uses a recursive chain of is_array () tests to generate a running total of the
   dimensionality of the object passed in $array. Once an is_array () test fails,
   the dimension total is returned - causing it to be passed back up through the
   recursion chain as it unravels.
   
   Does NOT echo, simply returns total array depth.
   
   Hidden argument 'count' is never included in your initial call. It is used on the
      recursive calls to keep track of the running dimension total (which is eventually
      returned to the caller).
*/
      
// It is ESSENTIAL that $count begins on 0, do not set this variable upon calling:
function countArrayDim ($array, $count = 0)
{
   // Check if it's an array:
   if (is_array ($array))
   {
      $count++;      // If this element is an array, then one more dimension.
      
      // Check to see if this array's elements are sub-arrays (foreach () allows handling of numeric and associative arrays):
      foreach ($array as $a)                  // Gets first element, as loop will only run once due to return statement!
         return countArrayDim ($a, $count);      // Recursively call with this array's first element.
   }
   
   // If this code is reached, then there are no more dimensions to this array.
   // Therefore, the final dimension count is returned and the recursion chain is unravelled:
   
   return $count;      // Send it up the chain!
}

?>