Home « Server software «

Documentation: shared/sql.php

Content

Class SQL - Virtualize interactions with the database

This script is a reference file of this system.

Licence: GNU Lesser General Public License

Auteurs:

Bernard Paques bernard.paques@bigfoot.com

check() - Check presence of SQL back-end

function check()

returns TRUE or FALSE

connect() - Connect to the database server

function &connect($host, $user, $password, $database)

$host - string server host name
$user - string account
$password - string password
$database - string database to use
returns a valid resource, or FALSE on failure

count() - Count selected rows

function count(&$result)

&$result - resource
returns TRUE on success, FALSE on failure

count_tables() - Count tables in database

function count_tables($name, $handle)

$name - string database name
$handle - resource handle to server
returns int number of tables, or FALSE on failure

debug() - Debug a SQL query

function &debug($query, $silent=FALSE, $connection=NULL)

$query - string the SQL query
$silent=FALSE - boolean optional TRUE to not report on any error
$connection=NULL - resource connection to be considered, if any
returns the resource returned by the database server, or the number of affected rows, or FALSE on error

This function may be invoked explicitly during query optimization. To do that, SQL::query(...) has to be temporarily turned to SQL::debug(...) and resulting data will be put in agents/debug.txt for analysis.

On SELECT this function queries the database two times: a first time to explain the statement, and second time to actually do the job.

errno() - Retrieve last error code, if any

function errno($connection=NULL)

$connection=NULL - resource connection to the database server, if any
returns int code of last error, or 0

error() - Build standard error message

function error($connection=NULL)

$connection=NULL - resource connection to the database server, if any
returns string

escape() - Escape a string

function &escape($text)

$text - string to be escaped
returns string safe version

fetch() - Fetch next result as an associative array

function &fetch(&$result)

&$result - resource set of rows
returns array related to next row, or FALSE if there is no more row

fetch_row() - Fetch next result as a bare array

function &fetch_row(&$result)

&$result - resource set of rows
returns array related to next row, or FALSE if there is no more row

free() - Release a resource

function free(&$result)

&$result - resource to be released
returns TRUE on success, FALSE on failure

get_last_id() - Get the id of the most recent item

function get_last_id()

returns int or FALSE

has_database() - Ensure a database exists

function has_database($name, $handle)

$name - string database name
$handle - resource handle to server
returns boolean TRUE or FALSE

initialize() - Initialize connections to the database

function initialize()

returns TRUE on success, FALSE on failure

ping() - Ping the database

function ping()

This function has to be activated from time to time to keep a live connection to the SQL server.

query() - Query the database

function &query(&$query, $silent=FALSE, $connection=NULL)

&$query - string the SQL query
$silent=FALSE - boolean optional TRUE to not report on any error
$connection=NULL - resource connection to be considered, if any
returns the resource returned by the database server, or the number of affected rows, or FALSE on error

This function also remembers any error in $context['error'].

query_count() - Query the database and count rows

function query_count(&$query, $silent=FALSE, $connection=NULL)

&$query - string the SQL query
$silent=FALSE - boolean optional TRUE to not report on any error
$connection=NULL - resource connection to be considered, if any
returns int number of rows, or NULL on error

This function also remember any error in $context['error']

query_first() - Query the database and return first item

function &query_first(&$query, $silent=FALSE, $connection=NULL)

&$query - string the SQL query
$silent=FALSE - boolean optional TRUE to not report on any error
$connection=NULL - resource connection to be considered, if any
returns array containing first item, or NULL on error

This function also remember any error in $context['error']

query_scalar() - Query the database and return result as a scalar

function &query_scalar(&$query, $silent=FALSE, $connection=NULL)

&$query - string the SQL query
$silent=FALSE -
$connection=NULL -
returns mixed containing query result, or NULL on error

This function also remember any error in $context['error']

setup_table() - Create or alter the structure of one table

function setup_table($table, $fields, $indexes)

$table - string the name of the table to setup
$fields - array of $field_name => $field_declaration
$indexes - array of $index_name => $index_declaration
returns a text string to print

table_name() - Create a table name

function table_name($name)

$name - string bare table name
returns string an extensive name suitable for MySQL requests

Note: this function handles properly the specific case of the table for user profiles. However, you may also have to use a different database connection for queries to this table.

table_stat() - Count of rows in a table

function table_stat($table)

$table - string name of table to analyze
returns NULL, or an array(count, min_date, max_date)

table_name()

function table_name($name)

$name -