TW Blog :: Archives for January 2004

Result Sets From Different Sources

Relates to PHP

Continuing the discussion of cleaner programming layers, one problem I find with similar sets of results from different tables, is that the API layer becomes cluttered with functions formatting similar result sets, with negligible differences. For example links to different sections of this weblog (the categories and archives). A quick solution to this is to set generic field names for the result set in the SQL query, and then using the same function to format the data in an array_walk call.

function ss_fns_build_list(&$str_item)
{
  extract($str_item);
  $str_item = sprintf("<li><a href=\"%s\"%s>%s</a></li>\n",
                      $t_url, $t_title, $t_text);
}

function ss_fns_get_data($str_query)
{  
  $var_results = ss_db_sel($str_query);
  if (PEAR::isError($var_results)) { // error trap }
  else
  {
    array_walk($var_results, 'ss_fns_build_list');
    return implode("\n", $var_results);
  }
}

The data is initially formatted in the SQL query (not shown) and assigned to generic field names (t_url, t_title, t_text). Then each item of the result set array is passed by reference to the function ss_fns_build_list where it is reformatted as a string. Then the entire array can be returned as a single string by first calling implode(). The PHP Manual states that modifying the array from inside the function may cause unpredictable behaviour, however I have not witnessed any testing the above code. A safety measure would be to pass a third parameter to the function by reference and fill that with the newly formatted data.

This solution is satisfying since it is visibly extensible. As an example, suppose the result set has groups of data (eg links to websites, categorised by region). Suppose, for this example, the grouping category has been given the generic field name t_list in the SQL query. Now an additional function can be defined at the API layer to do the additional formatting.

function ss_fns_build_list_multiple(&$arr_item, $key, &$arr_sets)
{
  $str_key = $arr_item["t_list"];
  ss_fns_build_list(&$arr_item);
  $arr_sets[$str_key][] = $arr_item;  
}

function ss_fns_get_grouped_data($str_query)
{
  $var_results = ss_db_sel($str_query);
  if (PEAR::isError($var_results)) { // error trap }
  else
  {
    array_walk($var_results,
               'ss_fns_build_list_multiple',
               &$arr_sets);
    foreach($arr_sets as $str_group_header => $arr_list_items)
    {
      $str_output .= "$str_group_header\n" 
                   . implode("\n", $arr_list_items) 
                   . "\n";
    }
    return $str_output;
  }
}

Each item of the result set is passed by reference to the function ss_fns_build_list_multiple. The category is looked up in the field t_list and then the item is formatted using the original ss_fns_build_list function. Finally it is assigned to the correct category in the third parameter, $arr_sets, which is also passed by reference. All that is left to do is to loop through the key, value pairs to produce the return data.

I have found these generic functions can be effectively applied to a number of scenarios, thus reducing the volume of code in the API. One further development would be to pass the location of a template as the third parameter in array_walk and hence remove the HTML from the layer completely, allowing more flexibility.

UPDATE - 2004-02-25 I have recently switched off the allow_call_time_pass_reference configuration. The function calls in ss_fns_build_multiple_list and ss_fns_get_grouped_data should not declare the variables $arr_item and $arr_sets, respectively, be passed by reference (this is left to the function being called). Under the new configuration, these call-time pass-by-references produce warnings. Thanks to the PHP Anthology for pointing this out to me.

Posted on Friday, Jan 30, 2004 at 00:46:40.