Class: Database
- Package: saf.Database
- Author: John Luxford <lux@simian.ca>
- Copyright: Copyright (C) 2001-2003, Simian Systems Inc.
- License: http://www.sitellite.org/index/license Simian Open Software License
- Version: 3.6, 2004-03-12, $Id: Database.php,v 1.4 2007/09/01 17:02:17 lux Exp $
- Access: public
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.
Usage Example
<?php
$db = new Database ("Driver:Host:Database", "Username", "Password", 1);
// create a database query object
$q = $db->query ("SELECT * FROM table");
if ($q->execute ()) {
while ($row = $q->fetch ()) {
// do something with the $row object
}
$q->free ();
} else {
// query failed
}
if ($row = $db->fetch ('SELECT * FROM table WHERE id = ??', $id)) {
// do something with $row
} else {
// query failed
echo $db->error;
}
?>
Return to Top
Properties
$connection
Contains the database connection resource.
$path
Path to the Berkeley Database.
$mode
Mode to use when opening the database (corresponds to
the modes available to the dba_open () function.
$handler
The database implementation used (db2, db3, gdbm, etc.).
$persistent
Whether or not to use persistence when connecting to the database.
$transactions = 0
Boolean value denoting whether to enable transactions in the
current database.
$driver
Contains the name of the database driver being used.
$host
Contains the name of the database host.
$name
Contains the name of the database being used.
$user
Contains the username used to connect to the current database.
$pass
Contains the password used to connect to the current database.
$dbd
Contains the loaded database driver.
$error
Contains the error message if an error occurs here. For most
uses however, you will want to use the error() method of the Query
object instead.
$sql
If abstract() has been called, this will contain the SQL
abstraction object.
$rows
Contains the number of rows returned by the previous fetch() call.
$lastid
Contains the lastid() of the last insert query sent to the execute()
method.
$tables = false
Contains a list of tables in the database. Set by getTables().
$pearEmu = false
$sequenceFormat = '%s_seq'
$fetchMode = DB_FETCHMODE_OBJECT
Return to Top
Methods
Database ($connstr = '::', $user = '', $pass = '', $persistent = 0)
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).
query ($sql = '', $cache = 0)
- Access: public
- Return: object
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().
table ($table, $pkey = '')
- Access: public
- Return: object
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.
abstractSql ($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.
fetch ()
- Access: public
- Return: mixed
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.
single ()
- Access: public
- Return: mixed
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.
shift ()
- Access: public
- Return: mixed
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.
execute ()
- Access: public
- Return: boolean
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.
connect ()
- Access: public
- Return: boolean
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.
close ()
- Access: public
- Return: boolean
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.
getTables ()
- Access: public
- Return: boolean
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.
tableExists ($tbl)
- Access: public
- Return: boolean
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.
setFetchMode ($mode)
getFetchMode ()
getAll ($sql)
quote ($string)
setOption ($option, $val)
createSequence ($seq_name)
dropSequence ($seq_name)
getSequenceName ($sqn)
nextId ($seq_name)
Return to Top