What would be the best way to document this PHP code ?

Question

Hello

Can you tell me what does the function do and how would you document the following function using Comments:

function tosql($value, $value_type, $is_delimiters = true, $use_null = true) 
    {
     if (is_array($value) || strlen($value)) {
      switch ($value_type) {
       case NUMBER:
       case FLOAT:
        return preg_replace(array("/,/", "/[^0-9\.,\-]/"), array(".", ""), $value);
        break;
       case DATETIME:
        if (!is_array($value) && is_int($value)) { $value = va_time($value); }
        if (is_array($value)) { $value = va_date($this->DatetimeMask, $value); } 
        else { return "NULL"; }
        break;
       case INTEGER:
        return intval($value);
        break;
       case DATE:
        if (!is_array($value) && is_int($value)) { $value = va_time($value); }
        if (is_array($value)) { $value = va_date($this->DateMask, $value); }
        else { return "NULL"; }
        break;
       case TIME:
        if (!is_array($value) && is_int($value)) { $value = va_time($value); }
        if (is_array($value)) { $value = va_date($this->TimeMask, $value); }
        else { return "NULL"; }
        break;
       case TIMESTAMP:
        if (!is_array($value) && is_int($value)) { $value = va_time($value); }
        if (is_array($value)) { $value = va_date($this->TimestampMask, $value); }
        else { return "NULL"; }
        break;
       case NUMBERS_LIST:
       case FLOATS_LIST:
        $values = (is_array($value)) ? $value : explode(",", $value);
        for ($v = 0; $v < sizeof($values); $v++) {
         $value = $values[$v];
         $value = preg_replace(array("/,/", "/[^0-9\.,\-]/"), array(".", ""), $value);
         if (!is_numeric($value)) {
          $value = 0;
         }
         $values[$v] = $value;
        }
        return implode(",", $values);
        break;
       case INTEGERS_LIST:
        $values = (is_array($value)) ? $value : explode(",", $value);
        for ($v = 0; $v < sizeof($values); $v++) {
         $values[$v] = intval($values[$v]);
        }
        return implode(",", $values);
        break;
       default:
        $value = addslashes($value);
        break;
      }
      if ($is_delimiters) {
       $value = "'" . $value . "'";
      }
     } elseif ($use_null) {
      $value = "NULL";
     } else {
      if ($value_type == INTEGER || $value_type == FLOAT || $value_type == NUMBER 
       || $value_type == NUMBERS_LIST || $value_type == FLOATS_LIST || $value_type == INTEGERS_LIST) {
       $value = 0;
      } elseif ($is_delimiters) {
       $value = "''";
      }
     } 
     return $value;
    }

Answer 1

Well giving it a quick once over it appears to be a function to safely convert a given value to a string that can be used in an SQL command. If it can't convert it then it give a suitable safe value, 'NULL', so as not to break the code.

usage: tosql( mydate, 'DATE' )

Suggest you cut and paste something like the above above the code in a comment...

Answer 2

It takes a value and a constant denoting the type of value and turns it into something acceptable in a SQL statement. It supports arrays as well for some types (DATETIME, DATE, TIME, TIMESTAMP, and LIST types. When $is_delimiters is true, it surrounds the item with single quotes (for inserted values and comparison tokens that require them). If $use_null is specified, it provides a NULL token.

How to comment code is a matter of opinion, religion, and how much you care about the next yahoo who has to use your code.

Answer 3

USing PHPDocumentor

/** * tosql * Converts a string to a valid sql string * @param string * @param string * @return string */ function tosql($value, $value_type, $is_delimiters = true, $use_null = true) { }