Back to index

awl  0.53
Public Member Functions | Static Public Member Functions | Public Attributes | Protected Attributes
AwlQuery Class Reference

List of all members.

Public Member Functions

 __construct ()
 

@-


 SetConnection ($new_connection, $options=null)
 Use a different database connection for this query.
 GetConnection ()
 Get the current database connection for this query.
 _log_query ($locn, $tag, $string, $line=0, $file="")
 Log query, optionally with file and line location of the caller.
 Bind ()
 Bind some parameters.
 Prepare ()
 Tell the database to prepare the query that we will execute.
 Execute ()
 Tell the database to execute the query.
 QueryString ()
 Return the query string we are planning to execute.
 Parameters ()
 Return the parameters we are planning to substitute into the query string.
 rows ()
 Return the count of rows retrieved/affected.
 rownum ()
 Return the current rownum in the retrieved set.
 TransactionState ()
 Returns the current state of a transaction, indicating if we have begun a transaction, whether the transaction has failed, or if we are not in a transaction.
 Begin ()
 Wrap the parent DB class Begin() so we can $qry->Begin() sometime before we $qry->Exec()
 Commit ()
 Wrap the parent DB class Commit() so we can $qry->Commit() sometime after we $qry->Exec()
 Rollback ()
 Wrap the parent DB class Rollback() so we can $qry->Rollback() sometime after we $qry->Exec()
 SetSql ($sql)
 Simple SetSql() class which will reset the object with the querystring from the first argument.
 QDo ()
 Simple QDo() class which will re-use this query for whatever was passed in, and execute it returning the result of the Exec() call.
 Exec ($location=null, $line=null, $file=null)
 Execute the query, logging any debugging.
 Fetch ($as_array=false)
 Fetch the next row from the query results.

Static Public Member Functions

static quote ($str=null)
 Quote the given string so it can be safely used within string delimiters in a query.

Public Attributes

 $location
 $query_time_warning = 0.3

Protected Attributes

 $connection
 $querystring
 $bound_querystring
 $bound_parameters
 $sth
 $result
 $rownum = null
 $rows
 $error_info
 $execution_time

Detailed Description

Definition at line 117 of file AwlQuery.php.


Constructor & Destructor Documentation

@-

Constructor

Parameters:
stringThe query string in PDO syntax with replacable '?' characters or bindable parameters.
mixedThe values to replace into the SQL string.
Returns:
The AwlQuery object

Definition at line 212 of file AwlQuery.php.

                         {
    global $_awl_dbconn;
    $this->rows = null;
    $this->execution_time = 0;
    $this->error_info = null;
    $this->rownum = -1;
    if ( isset($_awl_dbconn) ) $this->connection = $_awl_dbconn;
    else                       $this->connection = null;

    $argc = func_num_args();
    $args = func_get_args();

    $this->querystring = array_shift($args);
    if ( 1 < $argc ) {
      if ( is_array($args[0]) )
        $this->bound_parameters = $args[0];
      else
        $this->bound_parameters = $args;
//      print_r( $this->bound_parameters );
    }

    return $this;
  }

Here is the call graph for this function:


Member Function Documentation

AwlQuery::_log_query ( locn,
tag,
string,
line = 0,
file = "" 
)

Log query, optionally with file and line location of the caller.

This function should not really be used outside of AwlQuery. For a more useful generic logging interface consider calling dbg_error_log(...);

Parameters:
string$locnA string identifying the calling location.
string$tagA tag string, e.g. identifying the type of event.
string$stringThe information to be logged.
int$lineThe line number where the logged event occurred.
string$fileThe file name where the logged event occurred.

Definition at line 289 of file AwlQuery.php.

                                                                    {
    // replace more than one space with one space
    $string = preg_replace('/\s+/', ' ', $string);

    if ( ($tag == 'QF' || $tag == 'SQ') && ( $line != 0 && $file != "" ) ) {
      dbg_error_log( "LOG-$locn", " Query: %s: %s in '%s' on line %d", ($tag == 'QF' ? 'Error' : 'Possible slow query'), $tag, $file, $line );
    }

    while( strlen( $string ) > 0 )  {
      dbg_error_log( "LOG-$locn", " Query: %s: %s", $tag, substr( $string, 0, 240) );
      $string = substr( "$string", 240 );
    }
  }

Here is the caller graph for this function:

Wrap the parent DB class Begin() so we can $qry->Begin() sometime before we $qry->Exec()

Definition at line 468 of file AwlQuery.php.

                          {
    global $_awl_dbconn;
    if ( !isset($this->connection) ) {
      if ( !isset($_awl_dbconn) ) _awl_connect_configured_database();
      $this->connection = $_awl_dbconn;
    }
    return $this->connection->Begin();
  }

Here is the call graph for this function:

Bind some parameters.

This can be called in three ways: 1) As Bind(':key','value), when using named parameters 2) As Bind('value'), when using ? placeholders 3) As Bind(array()), to overwrite the existing bound parameters. The array may be ':name' => 'value' pairs or ordinal values, depending on whether the SQL is using ':name' or '?' style placeholders.

Parameters:
mixed$argsSee details above.

Definition at line 330 of file AwlQuery.php.

                  {
    $argc = func_num_args();
    $args = func_get_args();

    if ( $argc == 1 ) {
      if ( gettype($args[0]) == 'array' ) {
        $this->bound_parameters = $args[0];
      }
      else {
        $this->bound_parameters[] = $args[0];
      }
    }
    else {
      $this->bound_parameters[$args[0]] = $args[1];
    }
  }

Wrap the parent DB class Commit() so we can $qry->Commit() sometime after we $qry->Exec()

Definition at line 481 of file AwlQuery.php.

                           {
    if ( !isset($this->connection) ) {
      trigger_error("Cannot commit a transaction without an active statement.", E_USER_ERROR);
    }
    return $this->connection->Commit();
  }
AwlQuery::Exec ( location = null,
line = null,
file = null 
)

Execute the query, logging any debugging.

Example So that you can nicely enable/disable the queries for a particular class, you could use some of PHPs magic constants in your call. $qry->Exec(CLASS, LINE, FILE);

Parameters:
string$locationThe name of the location for enabling debugging or just to help our children find the source of a problem.
int$lineThe line number where Exec was called
string$fileThe file where Exec was called
Returns:
boolean Success (true) or Failure (false)

Definition at line 557 of file AwlQuery.php.

                                                                {
    global $c;
    if ( isset($location) ) $this->location = trim($location);
    if ( !isset($this->location) || $this->location == "" ) $this->location = substr($_SERVER['PHP_SELF'],1);

    if ( isset($line) )     $this->location_line = intval($line);
    else if ( isset($this->location_line) ) $line = $this->location_line;

    if ( isset($file) )     $this->location_file = trim($file);
    else if ( isset($this->location_file) ) $file = $this->location_file;

    if ( isset($c->dbg['querystring']) || isset($c->dbg['ALL']) ) {
      $this->_log_query( $this->location, 'DBGQ', $this->querystring, $line, $file );
      if ( isset($this->bound_parameters) && !isset($this->sth) ) {
        foreach( $this->bound_parameters AS $k => $v ) {
          $this->_log_query( $this->location, 'DBGQ', sprintf('    "%s" => "%s"', $k, $v), $line, $file );
        }
      }
    }

    if ( isset($this->bound_parameters) ) {
      $this->Prepare();
    }

    $success = $this->Execute();

    if ( ! $success ) {
      // query failed
      $this->errorstring = sprintf( 'SQL error "%s" - %s"', $this->error_info[0], (isset($this->error_info[2]) ? $this->error_info[2] : ''));
      if ( isset($c->dbg['print_query_errors']) && $c->dbg['print_query_errors'] ) {
        printf( "\n=====================\n" );
        printf( "%s[%d] QF: %s\n", $file, $line, $this->errorstring);
        printf( "%s\n", $this->querystring );
        if ( isset($this->bound_parameters) ) {
          foreach( $this->bound_parameters AS $k => $v ) {
            printf( "    %-18s \t=> '%s'\n", "'$k'", $v );
          }          
        }
        printf( ".....................\n" );
      }
      $this->_log_query( $this->location, 'QF', $this->errorstring, $line, $file );
      $this->_log_query( $this->location, 'QF', $this->querystring, $line, $file );
      if ( isset($this->bound_parameters) && ! ( isset($c->dbg['querystring']) || isset($c->dbg['ALL']) ) ) {
        foreach( $this->bound_parameters AS $k => $v ) {
          dbg_error_log( 'LOG-'.$this->location, ' Query: QF:     "%s" => "%s"', $k, $v);
        }
      }
    }
    elseif ( $this->execution_time > $this->query_time_warning ) {
     // if execution time is too long
      $this->_log_query( $this->location, 'SQ', "Took: $this->execution_time for $this->querystring", $line, $file ); // SQ == Slow Query :-)
    }
    elseif ( isset($c->dbg['querystring']) || isset($c->dbg[strtolower($this->location)]) || isset($c->dbg['ALL']) ) {
     // query successful, but we're debugging and want to know how long it took anyway
      $this->_log_query( $this->location, 'DBGQ', "Took: $this->execution_time to find $this->rows rows.", $line, $file );
    }

    return $success;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Tell the database to execute the query.

Definition at line 374 of file AwlQuery.php.

                     {
    global $c;

    if ( !isset($this->connection) ) {
      _awl_connect_configured_database();
      $this->connection = $GLOBALS['_awl_dbconn'];
    }
    if ( !is_object($this->connection) ) throw new Exception('Database not connected.');
    
    if ( isset($c->expand_pdo_parameters) && $c->expand_pdo_parameters ) {
      $this->bound_querystring = $this->querystring;
      if ( isset($this->bound_parameters) ) {
        $this->bound_querystring = $this->connection->ReplaceParameters($this->querystring,$this->bound_parameters);
//        printf( "\n=============================================================== OQ\n%s\n", $this->querystring);
//        printf( "\n=============================================================== QQ\n%s\n", $this->bound_querystring);
//        print_r( $this->bound_parameters );
      }
      $t1 = microtime(true); // get start time
      $this->sth = $this->connection->query($this->bound_querystring);
    }
    else {
      $t1 = microtime(true); // get start time
      $this->sth = $this->connection->prepare($this->querystring);
      if ( $this->sth ) $this->sth->execute($this->bound_parameters);
//      printf( "\n=============================================================== OQ\n%s\n", $this->querystring);
//      print_r( $this->bound_parameters );
    }
    $this->bound_querystring = null;

    if ( ! $this->sth ) {
      $this->error_info = $this->connection->errorInfo();
      return false;
    }
    $this->rows = $this->sth->rowCount();

    $i_took = microtime(true) - $t1;
    $c->total_query_time += $i_took;
    $this->execution_time = sprintf( "%2.06lf", $i_took);

    $this->error_info = null;
    return true;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

AwlQuery::Fetch ( as_array = false)

Fetch the next row from the query results.

Parameters:
boolean$as_arrayTrue if thing to be returned is array
Returns:
mixed query row

Definition at line 623 of file AwlQuery.php.

                                    {

    if ( ! $this->sth || $this->rows == 0 ) return false; // no results
    if ( $this->rownum == null ) $this->rownum = -1;
    if ( ($this->rownum + 1) >= $this->rows ) return false; // reached the end of results

    $this->rownum++;
    $row = $this->sth->fetch( ($as_array ? PDO::FETCH_NUM : PDO::FETCH_OBJ) );

    return $row;
  }

Here is the call graph for this function:

Get the current database connection for this query.

Definition at line 272 of file AwlQuery.php.

                           {
    return $this->connection;
  }

Return the parameters we are planning to substitute into the query string.

Definition at line 429 of file AwlQuery.php.

Tell the database to prepare the query that we will execute.

Definition at line 351 of file AwlQuery.php.

                     {
    global $c;

    if ( isset($this->sth) ) return; // Already prepared
    if ( isset($c->expand_pdo_parameters) && $c->expand_pdo_parameters ) return; //  No-op if we're expanding internally

    if ( !isset($this->connection) ) {
      _awl_connect_configured_database();
      $this->connection = $GLOBALS['_awl_dbconn'];
    }

    $this->sth = $this->connection->prepare( $this->querystring );

    if ( ! $this->sth ) {
      $this->error_info = $this->connection->errorInfo();
    }
    else $this->error_info = null;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Simple QDo() class which will re-use this query for whatever was passed in, and execute it returning the result of the Exec() call.

We can't call it Do() since that's a reserved word...

Parameters:
stringThe query string in PDO syntax with replacable '?' characters or bindable parameters.
mixedThe values to replace into the SQL string.
Returns:
boolean Success (true) or Failure (false)

Definition at line 524 of file AwlQuery.php.

                        {
    $argc = func_num_args();
    $args = func_get_args();

    $this->SetSql( array_shift($args) );
    if ( 1 < $argc ) {
      if ( is_array($args[0]) )
        $this->bound_parameters = $args[0];
      else
        $this->bound_parameters = $args;
    }

    return $this->Exec();
  }

Here is the call graph for this function:

Return the query string we are planning to execute.

Definition at line 421 of file AwlQuery.php.

                         {
    return $this->querystring;
  }
static AwlQuery::quote ( str = null) [static]

Quote the given string so it can be safely used within string delimiters in a query.

To be avoided, in general.

Parameters:
mixed$strData to be converted to a string suitable for including as a value in SQL.
Returns:
string NULL, TRUE, FALSE, a plain number, or the original string quoted and with ' and \ characters escaped

Definition at line 311 of file AwlQuery.php.

                                            {
    global $_awl_dbconn;
    if ( !isset($_awl_dbconn) ) {
      _awl_connect_configured_database();
    }
    return $_awl_dbconn->Quote($str);
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Wrap the parent DB class Rollback() so we can $qry->Rollback() sometime after we $qry->Exec()

Definition at line 492 of file AwlQuery.php.

                             {
    if ( !isset($this->connection) ) {
      trigger_error("Cannot rollback a transaction without an active statement.", E_USER_ERROR);
    }
    return $this->connection->Rollback();
  }

Return the current rownum in the retrieved set.

Definition at line 445 of file AwlQuery.php.

                    {
    return $this->rownum;
  }

Here is the caller graph for this function:

Return the count of rows retrieved/affected.

Definition at line 437 of file AwlQuery.php.

                  {
    return $this->rows;
  }

Here is the caller graph for this function:

AwlQuery::SetConnection ( new_connection,
options = null 
)

Use a different database connection for this query.

Parameters:
resource$new_connectionThe database connection to use.

Definition at line 241 of file AwlQuery.php.

                                                             {
    if ( is_string($new_connection) || is_array($new_connection) ) {
      $dbuser = null;
      $dbpass = null;
      if ( is_array($new_connection) ) {
        $dsn = $new_connection['dsn'];
        if ( isset($new_connection['dbuser']) ) $dbuser = $new_connection['dbuser'];
        if ( isset($new_connection['dbpass']) ) $dbpass = $new_connection['dbpass'];
      }
      elseif ( preg_match( '/^(\S+:)?(.*)( user=(\S+))?( password=(\S+))?$/', $new_connection, $matches ) ) {
        $dsn = $matches[2];
        if ( isset($matches[1]) && $matches[1] != '' ) {
          $dsn = $matches[1] . $dsn;
        }
        else {
          $dsn = 'pgsql:' . $dsn;
        }
        if ( isset($matches[4]) && $matches[4] != '' ) $dbuser = $matches[4];
        if ( isset($matches[6]) && $matches[6] != '' ) $dbpass = $matches[6];
      }
      if ( $new_connection = new AwlDatabase( $dsn, $dbuser, $dbpass, $options ) ) break;
    }
    $this->connection = $new_connection;
    return $new_connection;
  }
AwlQuery::SetSql ( sql)

Simple SetSql() class which will reset the object with the querystring from the first argument.

Parameters:
stringThe query string in PDO syntax with replacable '?' characters or bindable parameters.

Definition at line 504 of file AwlQuery.php.

                                 {
    $this->rows = null;
    $this->execution_time = 0;
    $this->error_info = null;
    $this->rownum = -1;
    $this->bound_parameters = null;
    $this->bound_querystring = null;
    $this->sth = null;

    $this->querystring = $sql;
  }

Here is the call graph for this function:

Here is the caller graph for this function:

Returns the current state of a transaction, indicating if we have begun a transaction, whether the transaction has failed, or if we are not in a transaction.

Returns:
int 0 = not started, 1 = in progress, -1 = error pending rollback/commit

Definition at line 455 of file AwlQuery.php.

                              {
    global $_awl_dbconn;
    if ( !isset($this->connection) ) {
      if ( !isset($_awl_dbconn) ) _awl_connect_configured_database();
      $this->connection = $_awl_dbconn;
    }
    return $this->connection->TransactionState();
  }

Here is the call graph for this function:


Member Data Documentation

Definition at line 144 of file AwlQuery.php.

Definition at line 138 of file AwlQuery.php.

AwlQuery::$connection [protected]

Definition at line 126 of file AwlQuery.php.

AwlQuery::$error_info [protected]

Definition at line 174 of file AwlQuery.php.

Definition at line 181 of file AwlQuery.php.

Definition at line 193 of file AwlQuery.php.

Definition at line 202 of file AwlQuery.php.

Definition at line 132 of file AwlQuery.php.

AwlQuery::$result [protected]

Definition at line 156 of file AwlQuery.php.

AwlQuery::$rownum = null [protected]

Definition at line 162 of file AwlQuery.php.

AwlQuery::$rows [protected]

Definition at line 168 of file AwlQuery.php.

AwlQuery::$sth [protected]

Definition at line 150 of file AwlQuery.php.


The documentation for this class was generated from the following file: