Docs for page dbi4php.php

/includes/dbi4php.php

Description

dbi4php - Generic database access for PHP

The functions defined in this file are meant to provide a single API to the different PHP database APIs. Unfortunately, this is necessary since PHP does not yet have a common db API. The value of $GLOBALS['db_type'] should be defined somewhere to one of the following:

mysql
mysqli
mssql
oracle (This uses the Oracle8 OCI API, so Oracle 8 libs are required)
postgresql
odbc
ibase (Interbase)
sqlite
ibm_db2

Limitations:

This assumes a single connection to a single database for the sake of simplicity. Do not make a new connection until you are completely finished with the previous one. However, you can execute more than query at the same time.
Rather than use the associative arrays returned with xxx_fetch_array (), normal arrays are used with xxx_fetch_row (). (Some db APIs don't support xxx_fetch_array ().)

author: Craig Knudsen <cknudsen@cknudsen.com>
version:
$Id$
$Log$ Revision 1.2 2010/03/24 22:31:26 dick Apply patch from fxmauricard Better error reporting for Oracle support in dbi4php.php - ID: 2840937 https://sourceforge.net/tracker/?func=detail&aid=2840937&group_id=3870&atid=303870
History: See ChangeLog
License: Copyright (C) 2006 Craig Knudsen This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to: Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor Boston, MA 02110-1301, USA
copyright: Craig Knudsen, <cknudsen@cknudsen.com>, http://www.k5n.us/cknudsen
license: GNU LGPL

Functions

dbi_affected_rows (line 442)

Returns the number of rows affected by the last INSERT, UPDATE or DELETE.

Note: Use the () function to get error information if the connection fails.

return: The number or database rows affected.

int dbi_affected_rows (resource $conn, resource $res)

resource $conn: The database connection
resource $res: The database query resource returned from the () function.

dbi_clear_cache (line 820)

Clear out the db cache.

Return the number of files deleted.

void dbi_clear_cache ()

dbi_close (line 233)

Closes a database connection.

This is not necessary for any database that uses pooled connections, such as MySQL, but a good programming practice.

return: True on success, false on error.

bool dbi_close (resource $conn)

resource $conn: The database connection.

dbi_connect (line 83)

Opens up a database connection.

Use a pooled connection if the db supports it and the db_persistent setting is enabled.

Notes:

The database type is determined by the global variable db_type
For ODBC, $host is ignored, $database = DSN
For Oracle, $database = tnsnames name
Use the () function to get error information if the connection fails.

return: The connection

resource dbi_connect (string $host, string $login, string $password, string $database, [string $lazy = true])

string $host: Hostname of database server
string $login: Database login
string $password: Database login password
string $database: Name of database
string $lazy: Wait until a query to connect?

dbi_error (line 593)

Gets the latest database error message.

return: The text of the last database error. (The type of information varies depending on which type of database is being used.)

string dbi_error ()

dbi_escape_string (line 657)

Escapes a string accordingly to the DB type.

return: The escaped string

string dbi_escape_string (string $string)

string $string: SQL of query to execute

dbi_execute (line 712)

Executes a SQL query, supporting parameter binding in the ?-style

Note: Use the () function to get error information if the connection fails.

return: The query result resource on queries (which can then be passed to the () function to obtain the results), or true/false on insert or delete queries.

mixed dbi_execute (string $sql, [array $params = array ()], [bool $fatalOnError = true], [bool $showError = true])

string $sql: SQL of query to execute. May contain ?-placeholders
array $params: An array containing the values to put in placeolders. These values will be escaped with dbi_escape_string () and will be put in single quotes. A NULL param will be replaced with NULL without quotes around it.
bool $fatalOnError: Abort execution if there is a database error?
bool $showError: Display error to user (including possibly the SQL) if there is a database error?

dbi_fatal_error (line 639)

Displays a fatal database error and aborts execution.

void dbi_fatal_error (string $msg, [bool $doExit = true], [bool $showError = true])

string $msg: The database error message.
bool $doExit: Abort execution?
bool $showError: Show the details of the error (possibly including the SQL that caused the error)?

dbi_fetch_row (line 404)

Retrieves a single row from the database and returns it as an array.

Note: We don't use the more useful xxx_fetch_array because not all databases support this function.

Note: Use the () function to get error information if the connection fails.

return: An array of database columns representing a single row in the query result or false on an error.

mixed dbi_fetch_row (resource $res)

resource $res: The database query resource returned from the () function.

dbi_free_result (line 558)

Frees a result set.

return: True on success

bool dbi_free_result (resource $res)

resource $res: The database query resource returned from the () function.

dbi_get_blob (line 519)

Get a BLOB (binary large object) from the database.

return: True on success

bool dbi_get_blob (resource $table, resource $column, resource $key)

resource $table: the table name that contains the blob
resource $column: the table column name for the blob
resource $key: the key for updating the table row

dbi_get_cached_rows (line 736)

Execute a SQL query. First, look to see if the results of this query are in a cache. If they are, then return them. If not, then run the query and store them in the cache. Of course, caching is only performed for SELECT queries.

Anything other than that will clear out the entire cache (until we add more intelligent caching logic).

void dbi_get_cached_rows ( $sql, [ $params = array ()], [ $fatalOnError = true], [ $showError = true])

$sql
$params
$fatalOnError
$showError

dbi_get_debug (line 811)

Get the SQL debug status.

void dbi_get_debug ()

dbi_init_cache (line 790)

Specify the location of the cache directory.

This directory will need to world-writable if this is a web-based application.

void dbi_init_cache ( $dir)

$dir

dbi_num_cached_queries (line 289)

Return the number of queries that were cached.

void dbi_num_cached_queries ()

dbi_num_queries (line 281)

Return the number of database queries that were executed.

(This does not included cached queries.)

void dbi_num_queries ()

dbi_query (line 309)

Executes an SQL query.

Note: Use the () function to get error information if the connection fails.

return: The query result resource on queries (which can then be passed to the () function to obtain the results), or true/false on insert or delete queries.

mixed dbi_query (string $sql, [bool $fatalOnError = true], [bool $showError = true])

string $sql: SQL of query to execute.
bool $fatalOnError: Abort execution if there is a database error?
bool $showError: Display error to user (including possibly the SQL) if there is a database error?

dbi_set_debug (line 801)

Enable SQL debugging.

This will keep an array of all SQL queries in the global variable $SQLLOG.

void dbi_set_debug ([ $status = false])

$status

dbi_update_blob (line 479)

Update a BLOB (binary large object) in the database with the contents of the specified file.

A BLOB field should be created in a separete INSERT statement using NULL as the initial value prior to this call.

return: True on success

bool dbi_update_blob (resource $table, resource $column, resource $key, resource $data)

resource $table: the table name that contains the blob
resource $column: the table column name for the blob
resource $key: the key for updating the table row
resource $data: the data to insert

Documentation generated on Thu, 10 Jun 2010 17:08:21 -0400 by phpDocumentor 1.4.3