phpDocumentor pond
[ class tree: pond ] [ index: pond ] [ all elements ]

Class: DB

Source Location: /qp_inc/_core/model/db/_db.class.php

Class DB

Property Summary
string   $connection_charset   Current connection charset
mixed   $dbaliases   Aliases that will be replaced in queries:
object   $dbhandle   MySQL Database handle
string   $dbhost   Database hostname
string   $dbname   Database name
string   $dbpassword   Database username's password
mixed   $dbreplaces   Strings that will replace the aliases in queries:
string   $dbuser   Database username
integer   $debug_dump_function_trace_for_queries   Do we want to output a function backtrace for every query? Number of stack entries to show (from last to first) (Default: 0); true means 'all'.
integer   $debug_dump_rows   Number of rows we want to dump in debug output (0 disables it) This requires DB::$log_queries to be true.
boolean   $debug_explain_joins   Do we want to explain joins? This requires DB::$log_queries to be true.
boolean   $error   Has an error occured?
boolean   $halt_on_error   Halt on errors?
integer   $insert_id   Last insert ID
string   $last_error   last DB error string
string   $last_query   last query SQL string
array   $last_result   Last result's rows
boolean   $log_queries   Do we want to log queries? If null, it gets set according to $debug.
integer   $num_queries   Number of done queries.
mixed   $num_rows   Number of rows in result set (after a select)
array   $queries   Log of queries:
float   $query_duration_fast   Time in seconds that is considered a fast query (green).
float   $query_duration_slow   Time in seconds that is considered a slow query (red).
resource   $result   Last query's resource
mixed   $rollback_nested_transaction   Rememeber if we have to rollback at the end of a nested transaction construct
mixed   $rows_affected   Number of rows affected by insert, delete, update or replace
boolean   $show_errors   Show/Print errors?
string   $table_options   CREATE TABLE options.
mixed   $transaction_nesting_level   How many transactions are currently nested?
mixed   $use_transactions   Use transactions in DB?

[ Top ]
Method Summary
static void   format_query()   Format a SQL query
DB   DB()   DB Constructor
void   begin()   BEGIN A TRANSCATION
void   commit()   Commit current transaction
string   debug_get_rows_table()   Get a table (or "<p>No Results.</p>") for the SELECT query results.
void   dump_queries()   Displays all queries that have been executed
void   escape()   Format a string correctly for safe insert under all PHP conditions
void   flush()   Kill cached query results
array   get_assoc()   Function to get the second column from the cached result indexed by the first column
array   get_col()   Function to get 1 column from the cached result set based on X index see docs for usage and info
mixed   get_results()   Return the the query as a result set - see docs for more details
mixed   get_row()   Get one row from the DB - see docs for more detail
mixed   get_var()   Get one variable from the DB - see docs for more detail
void   get_version()   Get MYSQL version
string   null()  
string   php_to_mysql_charmap()   Convert a PHP charset to its MySQL equivalent.
void   print_error()   Print SQL/DB error.
mixed   query()   Basic Query
string   quote()   Quote a value, either in single quotes (and escaped) or if it's NULL as 'NULL'.
void   restore_error_state()   Call this after save_halt_on_error() to restore the previous error state.
void   rollback()   Rollback current transaction
void   save_error_state()   Save the vars responsible for error handling.
void   select()   Select a DB (if another one needs to be selected)
boolean   set_connection_charset()   Set the charset of the connection.
void   week()   Returns the correct WEEK() function to get the week number for the given date.

[ Top ]
Properties
string   $connection_charset [line 216]

Current connection charset

API Tags:
See:  DB::set_connection_charset()


[ Top ]
mixed   $dbaliases = array() [line 144]

Aliases that will be replaced in queries:


[ Top ]
object   $dbhandle [line 184]

MySQL Database handle


[ Top ]
string   $dbhost = 'localhost' [line 209]

Database hostname


[ Top ]
string   $dbname [line 203]

Database name

API Tags:
See:  DB::select()


[ Top ]
string   $dbpassword [line 196]

Database username's password


[ Top ]
mixed   $dbreplaces = array() [line 148]

Strings that will replace the aliases in queries:


[ Top ]
string   $dbuser [line 190]

Database username


[ Top ]
integer   $debug_dump_function_trace_for_queries = 0 [line 253]

Do we want to output a function backtrace for every query? Number of stack entries to show (from last to first) (Default: 0); true means 'all'.

This requires DB::$log_queries to be true.


[ Top ]
integer   $debug_dump_rows = 0 [line 260]

Number of rows we want to dump in debug output (0 disables it) This requires DB::$log_queries to be true.


[ Top ]
boolean   $debug_explain_joins = false [line 243]

Do we want to explain joins? This requires DB::$log_queries to be true.

Information Tags:
Todo:  fp> we'd probably want to group all the advanced debug vars under a single setting now. We might even auto enable it when $debug=2. (And we might actually want to include a $debug="cookie" mode for easy switching with bookmarks or a bookmarklet)

[ Top ]
boolean   $error = false [line 95]

Has an error occured?


[ Top ]
boolean   $halt_on_error = true [line 90]

Halt on errors?


[ Top ]
integer   $insert_id = 0 [line 116]

Last insert ID


[ Top ]
string   $last_error = '' [line 110]

last DB error string


[ Top ]
string   $last_query = '' [line 105]

last query SQL string


[ Top ]
array   $last_result [line 129]

Last result's rows


[ Top ]
boolean   $log_queries [line 227]

Do we want to log queries? If null, it gets set according to $debug.

A subclass may set it by default (e.g. DbUnitTestCase_DB).


[ Top ]
integer   $num_queries = 0 [line 100]

Number of done queries.


[ Top ]
mixed   $num_rows = 0 [line 134]

Number of rows in result set (after a select)


[ Top ]
array   $queries = array() [line 233]

Log of queries:


[ Top ]
float   $query_duration_fast = 0.05 [line 267]

Time in seconds that is considered a fast query (green).

API Tags:
See:  DB::dump_queries()


[ Top ]
float   $query_duration_slow = 0.3 [line 274]

Time in seconds that is considered a slow query (red).

API Tags:
See:  DB::dump_queries()


[ Top ]
resource   $result [line 123]

Last query's resource

API Tags:
Access:  protected


[ Top ]
mixed   $rollback_nested_transaction = false [line 178]

Rememeber if we have to rollback at the end of a nested transaction construct


[ Top ]
mixed   $rows_affected = 0 [line 139]

Number of rows affected by insert, delete, update or replace


[ Top ]
boolean   $show_errors = true [line 85]

Show/Print errors?


[ Top ]
string   $table_options = '' [line 161]

CREATE TABLE options.

This gets appended to every "CREATE TABLE" query.

Edit those if you have control over you MySQL server and want a more professional database than what is commonly offered by popular hosting providers.

Information Tags:
Todo:  dh> If the query itself uses already e.g. "CHARACTER SET latin1" it should not get overridden..

[ Top ]
mixed   $transaction_nesting_level = 0 [line 173]

How many transactions are currently nested?


[ Top ]
mixed   $use_transactions = false [line 168]

Use transactions in DB?

You need to use InnoDB in order to enable this. See the $app_db_config.


[ Top ]
Methods
static method format_query  [line 1145]

  static void format_query( string $sql, [boolean $html = true]  )

Format a SQL query

Parameters:
string   $sql:  SQL
boolean   $html:  Format with/for HTML?

Information Tags:
Todo:  dh> Steal the code from phpMyAdmin :)

[ Top ]
Constructor DB  [line 301]

  DB DB( array $params  )

DB Constructor

Connects to the server and selects a database.

Parameters:
array   $params:  An array of parameters. Manadatory:
  • 'user': username to connect with
  • 'password': password to connect with
OR Optional:
  • 'name': the name of the default database, see DB::select()
  • 'host': host of the database; Default: 'localhost'
  • 'show_errors': Display SQL errors? (true/false); Default: don't change member default ($show_errors)
  • 'halt_on_error': Halt on error? (true/false); Default: don't change member default ($halt_on_error)
  • 'table_options': sets $table_options
  • 'use_transactions': sets $use_transactions
  • 'aliases': Aliases for tables (array( alias => table name )); Default: no aliases.
  • 'new_link': create a new link to the DB, even if there was a mysql_connect() with the same params before. (requires PHP 4.2)
  • 'client_flags': optional settings like compression or SSL encryption. See http://www.php.net/manual/en/ref.mysql.php#mysql.client-flags. (requires PHP 4.3)


[ Top ]
begin  [line 1404]

  void begin( )

BEGIN A TRANSCATION

Note: By default, MySQL runs with autocommit mode enabled. This means that as soon as you execute a statement that updates (modifies) a table, MySQL stores the update on disk. Once you execute a BEGIN, the updates are "pending" until you execute a COMMIT or a DB:rollback()

Note 2: standard syntax would be START TRANSACTION but it's not supported by older MySQL versions whereas BEGIN is...

Note 3: The default isolation level is REPEATABLE READ.



[ Top ]
commit  [line 1418]

  void commit( )

Commit current transaction



[ Top ]
debug_get_rows_table  [line 1054]

  string debug_get_rows_table( $max_lines, [ $break_at_comma = false]  )

Get a table (or "<p>No Results.</p>") for the SELECT query results.

Parameters:
   $max_lines: 
   $break_at_comma: 

API Tags:
Return:  HTML table or "No Results" if the


[ Top ]
dump_queries  [line 1179]

  void dump_queries( [boolean $html = true]  )

Displays all queries that have been executed

Parameters:
boolean   $html:  Use HTML.


[ Top ]
escape  [line 439]

  void escape( $str  )

Format a string correctly for safe insert under all PHP conditions

Parameters:
   $str: 


[ Top ]
flush  [line 603]

  void flush( )

Kill cached query results



[ Top ]
get_assoc  [line 980]

  array get_assoc( [ $query = NULL], [ $title = '']  )

Function to get the second column from the cached result indexed by the first column

Parameters:
   $query: 
   $title: 

API Tags:
Return:  [col_0] => col_1


[ Top ]
get_col  [line 956]

  array get_col( [ $query = NULL], [ $x = 0], [ $title = '']  )

Function to get 1 column from the cached result set based on X index see docs for usage and info

Parameters:
   $query: 
   $x: 
   $title: 


[ Top ]
get_results  [line 1006]

  mixed get_results( [ $query = NULL], [ $output = OBJECT], [ $title = '']  )

Return the the query as a result set - see docs for more details

Parameters:
   $query: 
   $output: 
   $title: 


[ Top ]
get_row  [line 913]

  mixed get_row( [ $query = NULL], [ $output = OBJECT], [ $y = 0], [ $title = '']  )

Get one row from the DB - see docs for more detail

Parameters:
   $query: 
   $output: 
   $y: 
   $title: 


[ Top ]
get_var  [line 885]

  mixed get_var( [ $query = NULL], [ $x = 0], [ $y = 0], [ $title = '']  )

Get one variable from the DB - see docs for more detail

Note: To be sure that you received NULL from the DB and not "no rows" check for $num_rows.

Parameters:
   $query: 
   $x: 
   $y: 
   $title: 

API Tags:
Return:  NULL if not found, the value otherwise (which may also be NULL).


[ Top ]
get_version  [line 614]

  void get_version( [ $query_title = NULL]  )

Get MYSQL version

Parameters:
   $query_title: 


[ Top ]
null  [line 476]

  string null( $val  )

Parameters:
   $val: 

API Tags:
Return:  Return the given value or 'NULL', if it's === NULL.


[ Top ]
php_to_mysql_charmap  [line 1472]

  string php_to_mysql_charmap( string $php_charset  )

Convert a PHP charset to its MySQL equivalent.

Parameters:
string   $php_charset:  PHP charset

API Tags:
Return:  MYSQL charset or unchanged


[ Top ]
print_error  [line 516]

  void print_error( [string $title = ''], [string $html_str = ''], [string|false $query_title = '']  )

Print SQL/DB error.

TODO: fp> bloated: it probably doesn't make sense to display errors if we don't stop. Any use case? dh> Sure. Local testing (and test cases).

Parameters:
string   $title:  Short error (no HTML)
string   $html_str:  Extended description/help for the error (for HTML)
string|false   $query_title:  Query title; false if DB::$last_query should not get displayed


[ Top ]
query  [line 686]

  mixed query( string $query, [string $title = '']  )

Basic Query

Parameters:
string   $query:  SQL query
string   $title:  title for debugging

API Tags:
Return:  # of rows affected or false if error


[ Top ]
quote  [line 451]

  string quote( string|array|null $str  )

Quote a value, either in single quotes (and escaped) or if it's NULL as 'NULL'.

Parameters:
string|array|null   $str: 

API Tags:
Return:  Quoted (and escaped) value or 'NULL'.


[ Top ]
restore_error_state  [line 662]

  void restore_error_state( )

Call this after save_halt_on_error() to restore the previous error state.

This can be chained.


API Tags:
See:  DB::save_error_state()


[ Top ]
rollback  [line 1445]

  void rollback( )

Rollback current transaction



[ Top ]
save_error_state  [line 646]

  void save_error_state( )

Save the vars responsible for error handling.

This can be chained.


API Tags:
See:  DB::restore_error_state()


[ Top ]
select  [line 422]

  void select( $db  )

Select a DB (if another one needs to be selected)

Parameters:
   $db: 


[ Top ]
set_connection_charset  [line 1524]

  boolean set_connection_charset( string $charset, [boolean $use_map = true]  )

Set the charset of the connection.

WARNING: this will fail on MySQL 3.23

Parameters:
string   $charset:  Charset
boolean   $use_map:  Use the "regular charset => mysql charset map"?

API Tags:
Return:  true on success, false on failure
Staticvar:  array $mysql_charset_map: "regular charset => mysql charset map"


[ Top ]
week  [line 494]

  void week( string $date, integer $startofweek  )

Returns the correct WEEK() function to get the week number for the given date.

Parameters:
string   $date:  will be used as is
integer   $startofweek:  0 for sunday, 1 for monday

Information Tags:
Link:  http://dev.mysql.com/doc/mysql/en/date-and-time-functions.html
Todo:  disable when MySQL < 4

[ Top ]