Class: Database

Source Location: Program_Root/Database/Database.php

Class Overview

Database is a database abstraction class; a unified means of accessing different relational database systems. It is accompanied by a second class called Query, and relies on driver classes to provide all the database specific functionality.

Author(s)

John Luxford <mailto:lux@simian.ca>

Version

3.6, 2004-03-12, $Id: Database.php,v 1.3 2005/07/06 15:30:56 lux Exp $

Copyright

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

[line 119]
Database is a database abstraction class; a unified means of accessing different relational database systems. It is accompanied by a second class called Query, and relies on driver classes to provide all the database specific functionality.

Database 2.0 is 100% backwards compatible with code written for 1.0, except that it has been updated to require the new Loader class, and to work with Query 2.0, which adds optional caching support via Berkeley DBs.

New in 2.2:

Added new $error and $row properties, and a new fetch() method, to retrieve quick select queries in a single line of code.

New in 2.4:

Added new table() method, which creates a DatabaseTable object, which you can use to execute high-level functions, such as fetchAll(), on.
Added an $sql property and an abstract() method, for query abstraction using the saf.Database.SQL package.

New in 2.6:

Added an execute() method, which allows you to execute quick insert or update statements in a single line of code.

New in 2.8:

Added connect() and close() methods, so that you can disconnect and reconnect to the same database if necessary.

New in 3.0:

Added getTables() and tableExists() methods.
Added a $tables property.
saf.Database.Table is included automatically now, because it is extended in the drivers.
Turned persistent connections OFF by default.

New in 3.2:

Fixed fetch() and execute() so that the bind values may be passed as a single array which would be the second value, as opposed to needing each value to bind to be declared separately. This is handy if you already have an array of values to bind.

New in 3.4:

Added new methods single() and shift(), which return the first object only of a result set, or the first value from the first object of the result set, respectively.
Added global functions that alias methods of a global $db object. These include db_fetch(), db_query(), db_table(), db_execute(), db_error(), db_single(), and db_shift().

New in 3.6:

Fixed a bug in the handling of hostnames including ports.


1     <?php
2     
3      $db = new Database ("Driver:Host:Database", "Username", "Password", 1);
4     
5      // create a database query object
6      $q = $db->query ("SELECT * FROM table");
7     
8      if ($q->execute ()) {
9          while ($row = $q->fetch ()) {
10             // do something with the $row object
11         }
12         $q->free ();
13     } else {
14         // query failed
15     }
16    
17     if ($row = $db->fetch ('SELECT * FROM table WHERE id = ??', $id)) {
18         // do something with $row
19     } else {
20         // query failed
21         echo $db->error;
22     }
23    
24     ? >

Tags:

access:	public
version:	3.6, 2004-03-12, $Id: Database.php,v 1.3 2005/07/06 15:30:56 lux Exp $
license:	http://www.sitellite.org/index/license
copyright:	Copyright (C) 2001-2003, Simian Systems Inc.
author:	John Luxford <mailto:lux@simian.ca>

[ Top ]

Class Variables

$connection =

[line 126]

Contains the database connection resource.

Tags:

access:

public

Type:

mixed

[ Top ]

Class Methods

constructor Database [line 257]

Database Database(
[mixed
$connstr = '::'], [string
$user = ''], [string
$pass = ''], [boolean
$persistent = 0], string
$constr)

Constructor method. Establishes a connection to the specified database system.

$constr is the connection string that is used to tell Database how to find the database you are looking for. It takes the format: "Driver:Hostname:Database".

$user is the username required to connect to the database.

$pass is the password required to connect to the database.

$persistent is a 1 or 0 (true or false) value denoting whether to establish a persistent connection or not. Default is 1 (true).

Tags:

access:

public

Parameters:

string	$constr
string	$user
string	$pass
boolean	$persistent

[ Top ]

method abstractSql [line 331]

void abstractSql(
[string
$path = 'inc/sql'])

Creates an saf.Database.SQL object, which inherits all of its functionality from saf.I18n, and serves as an abstraction layer for database queries.

method close [line 526]

boolean close(
)

Disconnects from the database. This method is usually unnecessary since connections should be automatically terminated or should persist after the script finishes executing, depending on your settings.

Tags:

access:

public

[ Top ]

method connect [line 507]

boolean connect(
)

Connects to the database. A connection is automatically created when a new Database object is created, so there is no need to use this method unless you need to disconnect and reconnect again.

Tags:

access:

public

[ Top ]

method createSequence [line 606]

void createSequence(
mixed
$seq_name)

[ Top ]

method dropSequence [line 614]

void dropSequence(
mixed
$seq_name)

[ Top ]

method execute [line 471]

boolean execute(
string
$sql, mixed
$bind_values)

Executes a single query against the database and returns true

or false depending on the success of the query. This method is good for shortening code on quick insert or update queries. If an error occurs, you can retrieve the error message from the $error property. The lastid() of an insert query is stored in the $lastid property. Bind values may be passed as additional parameters.

Tags:

access:

public

Parameters:

string	$sql
mixed	$bind_values

[ Top ]

method fetch [line 352]

mixed fetch(
string
$sql, mixed
$bind_values)

Executes a single query against the database and returns either

the single result object if there is only one, an array of result objects all at once if there are more than one, or false upon failure or no results. This method is good for shortening code on quick select queries. If an error occurs, you can retrieve the error message from the $error property. The number of rows returned is stored in the $rows property. Bind values may be passed as additional parameters.

Tags:

access:

public

Parameters:

string	$sql
mixed	$bind_values

[ Top ]

method getAll [line 584]

void getAll(
mixed
$sql)

[ Top ]

method getFetchMode [line 578]

void getFetchMode(
)

[ Top ]

method getSequenceName [line 622]

void getSequenceName(
mixed
$sqn)

[ Top ]

method getTables [line 544]

boolean getTables(
)

Retrieves a list of tables in the database and places them in the $tables property, which is an array. Returns true on success and false on failure.

Tags:

access:

public

[ Top ]

method nextId [line 629]

void nextId(
mixed
$seq_name)

[ Top ]

method query [line 289]

object query(
[string
$sql = ''], [mixed
$cache = 0])

Creates and returns a Query object.

$sql is the SQL query you wish to execute with this object.

Note: If $pearEmu is set to true, this method merely aliases execute().

method quote [line 597]

void quote(
mixed
$string)

[ Top ]

method setFetchMode [line 572]

void setFetchMode(
mixed
$mode)

[ Top ]

method setOption [line 604]

void setOption(
mixed
$option, mixed
$val)

[ Top ]

method shift [line 448]

mixed shift(
string
$sql, mixed
$bind_values)

Executes a single query against the database and returns the

first value from the first result. This method is good for shortening code on quick select queries. If an error occurs, you can retrieve the error message from the $error property. The number of rows returned is stored in the $rows property. Bind values may be passed as additional parameters.

Tags:

access:

public

Parameters:

string	$sql
mixed	$bind_values

[ Top ]

method single [line 403]

mixed single(
string
$sql, mixed
$bind_values)

Executes a single query against the database and returns a

single result object. This method is good for shortening code on quick select queries. If an error occurs, you can retrieve the error message from the $error property. The number of rows returned is stored in the $rows property. Bind values may be passed as additional parameters.

Tags:

access:

public

Parameters:

string	$sql
mixed	$bind_values

[ Top ]

method table [line 316]

object table(
string
$table, [string
$pkey = ''])

Creates and returns a DatabaseTable object. $pkey is the name of the primary key column. Automatically loads the saf.Database.Table package on calling, instead of loading the extra package at the start.

Tags:

access:

public

Parameters:

string	$table
string	$pkey

[ Top ]

method tableExists [line 562]

boolean tableExists(
string
$tbl)

Determines whether the specified table exists or not by comparing it to the $tables list. If $tables is not set, then it will call getTables() automatically as well.

Packages

Classes

Files

Class: Database

Class Overview

Author(s)

Version

Copyright

Variables

Methods

Inherited Variables

Inherited Methods

Class Details

Tags:

Class Variables

$connection =

Tags:

$driver =

Tags:

$error =

Tags:

$fetchMode = DB_FETCHMODE_OBJECT

$host =

Tags:

$lastid =

Tags:

$name =

Tags:

$pass =

Tags:

$pearEmu = false

$rows =

Tags:

$sequenceFormat = '%s_seq'

$tables = false

Tags:

$transactions = 0

Tags:

$user =

Tags:

Class Methods

constructor Database [line 257]

Tags:

Parameters:

method abstractSql [line 331]

Tags:

Parameters:

method close [line 526]

Tags:

method connect [line 507]

Tags:

method createSequence [line 606]

method dropSequence [line 614]

method execute [line 471]

Tags:

Parameters:

method fetch [line 352]

Tags:

Parameters:

method getAll [line 584]

method getFetchMode [line 578]

method getSequenceName [line 622]

method getTables [line 544]

Tags:

method nextId [line 629]

method query [line 289]

Tags:

Parameters:

method quote [line 597]

method setFetchMode [line 572]

method setOption [line 604]

method shift [line 448]

Tags:

Parameters:

method single [line 403]

Tags:

Parameters:

method table [line 316]

Tags:

Parameters: