class JDatabase implements JDatabaseInterface


Located at : UKNOWVA_ROOT/libraries/joomla/database/database.php

Database connector class.

Properties

string $name

Methods

static array
getConnectors()

Get a list of available database connectors. The list will only be populated with connectors that both the class exists and the static test method returns true. This gives us the ability to have a multitude of connector classes that are self-aware as to whether or not they are able to be used on a given system.

static JDatabase
getInstance(array $options = array())

Method to return a JDatabase instance based on the given options. There are three global options and then the rest are specific to the database driver. The 'driver' option defines which JDatabaseDriver class is used for the connection -- the default is 'mysql'. The 'database' option determines which database is to be used for the connection. The 'select' option determines whether the connector should automatically select the chosen database.

static array
splitSql(string $sql)

Splits a string of multiple queries into an array of individual queries.

string
__call(string $method, array $args)

Magic method to provide method alias support for quote() and quoteName().

void
addQuoted(mixed $quoted) deprecated

Adds a field or array of field names to the list that are to be quoted.

bool
connected()

Determines if the connection to the server is active.

string
escape(string $text, bool $extra = false)

Method to escape a string for usage in an SQL statement.

integer
getAffectedRows()

Get the number of affected rows for the previous executed SQL statement.

mixed
getCollation()

Method to get the database collation in use by sampling a text field of a table in the database.

resource
getConnection()

Method that provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.

integer
getCount()

Get the total number of SQL statements executed by the database driver.

string
getDateFormat()

Returns a PHP date() function compliant date format for the database driver.

array
getLog()

Get the database driver SQL statement log.

string
getNullDate()

Get the null or zero representation of a timestamp for the database driver.

integer
getNumRows(resource $cursor = null)

Get the number of returned rows for the previous executed SQL statement.

string
getPrefix()

Get the common table prefix for the database driver.

mixed
getQuery(bool $new = false)

Get the current or query, or new JDatabaseQuery object.

array
getTableColumns(mixed $tables, bool $typeOnly = true)

Retrieves field information about the given tables.

array
getTableCreate(mixed $tables)

Shows the table CREATE statement that creates the given tables.

array
getTableKeys(mixed $tables)

Retrieves field information about the given tables.

array
getTableList()

Method to get an array of all tables in the database.

bool
getUTFSupport()

Determine whether or not the database engine supports UTF-8 character encoding.

string
getVersion()

Get the version of the database connector

boolean
hasUTF()

Determines if the database engine supports UTF-8 character encoding.

integer
insertid()

Method to get the auto-incremented value from the last INSERT statement.

bool
insertObject(string $table, object $object, string $key = null)

Inserts a row into a table based on an object's properties.

mixed
loadAssoc()

Method to get the first row of the result set from the database query as an associative array of ['fieldname' => 'rowvalue'].

mixed
loadAssocList(string $key = null, string $column = null)

Method to get an array of the result set rows from the database query where each row is an associative array of ['fieldname' => 'rowvalue']. The array of rows can optionally be keyed by a field name, but defaults to a sequential numeric array.

mixed
loadColumn(integer $offset)

Method to get an array of values from the $offset field in each row of the result set from the database query.

mixed
loadNextObject(string $class = 'stdClass')

Method to get the next row in the result set from the database query as an object.

mixed
loadNextRow()

Method to get the next row in the result set from the database query as an array.

mixed
loadObject(string $class = 'stdClass')

Method to get the first row of the result set from the database query as an object.

mixed
loadObjectList(string $key = '', string $class = 'stdClass')

Method to get an array of the result set rows from the database query where each row is an object. The array of objects can optionally be keyed by a field name, but defaults to a sequential numeric array.

mixed
loadResult()

Method to get the first field of the first row of the result set from the database query.

mixed
loadRow()

Method to get the first row of the result set from the database query as an array. Columns are indexed numerically so the first column in the result set would be accessible via $row[0], etc.

mixed
loadRowList(string $key = null)

Method to get an array of the result set rows from the database query where each row is an array. The array of objects can optionally be keyed by a field offset, but defaults to a sequential numeric array.

mixed
query()

Execute the SQL statement.

string
quote(string $text, bool $escape = true)

Method to quote and optionally escape a string to database requirements for insertion into the database.

string
quoteName(string $name)

Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection risks and reserved word conflicts.

string
replacePrefix(string $sql, string $prefix = '#__')

This function replaces a string identifier $prefix with the string held is the tablePrefix class variable.

bool
select(string $database)

Select a database for use.

bool
setDebug(bool $level)

Sets the database debugging state for the driver.

setQuery(mixed $query, integer $offset, integer $limit)

Sets the SQL statement string for later execution.

bool
setUTF()

Set the connection to use UTF-8 character encoding.

void
transactionCommit()

Method to commit a transaction.

void
transactionRollback()

Method to roll back a transaction.

void
transactionStart()

Method to initialize a transaction.

bool
updateObject(string $table, object $object, string $key, bool $nulls = false)

Updates a row in a table based on an object's properties.

void
debug(integer $level) deprecated

Sets the debug level on or off

string
explain() deprecated

Diagnostic method to return explain information for a query.

string
getErrorMsg(bool $escaped = false) deprecated

Gets the error message from the database connection.

integer
getErrorNum() deprecated

Gets the error number from the database connection.

string
getEscaped(string $text, bool $extra = false) deprecated

Method to escape a string for usage in an SQL statement.

array
getTableFields(mixed $tables, bool $typeOnly = true) deprecated

Retrieves field information about the given tables.

integer
getTicker() deprecated

Get the total number of SQL statements executed by the database driver.

bool
isQuoted(string $field) deprecated

Checks if field name needs to be quoted.

mixed
loadResultArray(integer $offset) deprecated

Method to get an array of values from the $offset field in each row of the result set from the database query.

string
nameQuote(string $name) deprecated

Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection risks and reserved word conflicts.

mixed
queryBatch($abortOnError = true, $transactionSafe = false) deprecated

Execute a query batch.

string
stderr(bool $showSQL = false) deprecated

Return the most recent error message for the database connector.

Details

at line 160
static array getConnectors()

Get a list of available database connectors. The list will only be populated with connectors that both the class exists and the static test method returns true. This gives us the ability to have a multitude of connector classes that are self-aware as to whether or not they are able to be used on a given system.

Return Value

array An array of available database connectors.

at line 225
static JDatabase getInstance(array $options = array())

Method to return a JDatabase instance based on the given options. There are three global options and then the rest are specific to the database driver. The 'driver' option defines which JDatabaseDriver class is used for the connection -- the default is 'mysql'. The 'database' option determines which database is to be used for the connection. The 'select' option determines whether the connector should automatically select the chosen database.

Instances are unique to the given options and new objects are only created when a unique options array is passed into the method. This ensures that we don't end up with unnecessary database connection resources.

Parameters

array $options Parameters to be passed to the database driver.

Return Value

JDatabase A database object.

at line 313
static array splitSql(string $sql)

Splits a string of multiple queries into an array of individual queries.

Parameters

string $sql Input SQL string with which to split into individual queries.

Return Value

array The queries from the input string separated into an array.

at line 364
string __call(string $method, array $args)

Magic method to provide method alias support for quote() and quoteName().

Parameters

string $method The called method.
array $args The array of arguments passed to the method.

Return Value

string The aliased method's return value or null.

at line 420
void addQuoted(mixed $quoted) deprecated

deprecated 12.1

Adds a field or array of field names to the list that are to be quoted.

Parameters

mixed $quoted Field name or array of names.

Return Value

void

at line 442
abstract bool connected()

Determines if the connection to the server is active.

Return Value

bool True if connected to the database engine.

at line 454
abstract string escape(string $text, bool $extra = false)

Method to escape a string for usage in an SQL statement.

Parameters

string $text The string to be escaped.
bool $extra Optional parameter to provide extra escaping.

Return Value

string The escaped string.

at line 508
abstract integer getAffectedRows()

Get the number of affected rows for the previous executed SQL statement.

Return Value

integer The number of affected rows.

at line 517
abstract mixed getCollation()

Method to get the database collation in use by sampling a text field of a table in the database.

Return Value

mixed The collation in use by the database or boolean false if not supported.

at line 527
resource getConnection()

Method that provides access to the underlying database connection. Useful for when you need to call a proprietary method such as postgresql's lo_* methods.

Return Value

resource The underlying database connection resource.

at line 539
integer getCount()

Get the total number of SQL statements executed by the database driver.

Return Value

integer

at line 551
string getDateFormat()

Returns a PHP date() function compliant date format for the database driver.

Return Value

string The format string.

at line 563
array getLog()

Get the database driver SQL statement log.

Return Value

array SQL statements executed by the database driver.

at line 575
string getNullDate()

Get the null or zero representation of a timestamp for the database driver.

Return Value

string Null or zero representation of a timestamp.

at line 589
abstract integer getNumRows(resource $cursor = null)

Get the number of returned rows for the previous executed SQL statement.

Parameters

resource $cursor An optional database cursor resource to extract the row count from.

Return Value

integer The number of returned rows.

at line 598
string getPrefix()

Get the common table prefix for the database driver.

Return Value

string The common database table prefix.

at line 613
abstract mixed getQuery(bool $new = false)

Get the current or query, or new JDatabaseQuery object.

Parameters

bool $new False to return the last query set, True to return a new JDatabaseQuery object.

Return Value

mixed The current value of the internal SQL variable or a new JDatabaseQuery object.

Exceptions

DatabaseException

at line 626
abstract array getTableColumns(mixed $tables, bool $typeOnly = true)

Retrieves field information about the given tables.

Parameters

mixed $tables A table name or a list of table names.
bool $typeOnly True to only return field types.

Return Value

array An array of fields by table.

Exceptions

DatabaseException

at line 638
abstract array getTableCreate(mixed $tables)

Shows the table CREATE statement that creates the given tables.

Parameters

mixed $tables A table name or a list of table names.

Return Value

array A list of the create SQL for the tables.

Exceptions

DatabaseException

at line 650
abstract array getTableKeys(mixed $tables)

Retrieves field information about the given tables.

Parameters

mixed $tables A table name or a list of table names.

Return Value

array An array of keys for the table(s).

Exceptions

DatabaseException

at line 660
abstract array getTableList()

Method to get an array of all tables in the database.

Return Value

array An array of all the tables in the database.

Exceptions

DatabaseException

at line 669
bool getUTFSupport()

Determine whether or not the database engine supports UTF-8 character encoding.

Return Value

bool True if the database engine supports UTF-8 character encoding.

at line 681
abstract string getVersion()

Get the version of the database connector

Return Value

string The database connector version.

at line 690
abstract boolean hasUTF()

Determines if the database engine supports UTF-8 character encoding.

Return Value

boolean True if supported.

at line 699
abstract integer insertid()

Method to get the auto-incremented value from the last INSERT statement.

Return Value

integer The value of the auto-increment field from the last inserted row.

at line 713
bool insertObject(string $table, object $object, string $key = null)

Inserts a row into a table based on an object's properties.

Parameters

string $table The name of the database table to insert into.
object $object A reference to an object whose public properties match the table fields.
string $key The name of the primary key. If provided the object property is updated.

Return Value

bool True on success.

Exceptions

DatabaseException

at line 764
mixed loadAssoc()

Method to get the first row of the result set from the database query as an associative array of ['fieldname' => 'rowvalue'].

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 802
mixed loadAssocList(string $key = null, string $column = null)

Method to get an array of the result set rows from the database query where each row is an associative array of ['fieldname' => 'rowvalue']. The array of rows can optionally be keyed by a field name, but defaults to a sequential numeric array.

NOTE: Chosing to key the result array by a non-unique field name can result in unwanted behavior and should be avoided.

Parameters

string $key The name of a field on which to key the result array.
string $column An optional column name. Instead of the whole row, only this column value will be in the result array.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 841
mixed loadColumn(integer $offset)

Method to get an array of values from the $offset field in each row of the result set from the database query.

Parameters

integer $offset The row offset to use to build the result array.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 873
mixed loadNextObject(string $class = 'stdClass')

Method to get the next row in the result set from the database query as an object.

Parameters

string $class The class name to use for the returned row object.

Return Value

mixed The result of the query as an array, false if there are no more rows.

Exceptions

DatabaseException

at line 902
mixed loadNextRow()

Method to get the next row in the result set from the database query as an array.

Return Value

mixed The result of the query as an array, false if there are no more rows.

Exceptions

DatabaseException

at line 933
mixed loadObject(string $class = 'stdClass')

Method to get the first row of the result set from the database query as an object.

Parameters

string $class The class name to use for the returned row object.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 969
mixed loadObjectList(string $key = '', string $class = 'stdClass')

Method to get an array of the result set rows from the database query where each row is an object. The array of objects can optionally be keyed by a field name, but defaults to a sequential numeric array.

NOTE: Chosing to key the result array by a non-unique field name can result in unwanted behavior and should be avoided.

Parameters

string $key The name of a field on which to key the result array.
string $class The class name to use for the returned row objects.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 1004
mixed loadResult()

Method to get the first field of the first row of the result set from the database query.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 1034
mixed loadRow()

Method to get the first row of the result set from the database query as an array. Columns are indexed numerically so the first column in the result set would be accessible via $row[0], etc.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 1069
mixed loadRowList(string $key = null)

Method to get an array of the result set rows from the database query where each row is an array. The array of objects can optionally be keyed by a field offset, but defaults to a sequential numeric array.

NOTE: Chosing to key the result array by a non-unique field can result in unwanted behavior and should be avoided.

Parameters

string $key The name of a field on which to key the result array.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 1104
abstract mixed query()

Execute the SQL statement.

Return Value

mixed A database cursor resource on success, boolean false on failure.

Exceptions

DatabaseException

at line 1116
string quote(string $text, bool $escape = true)

Method to quote and optionally escape a string to database requirements for insertion into the database.

Parameters

string $text The string to quote.
bool $escape True to escape the string, false to leave it unchanged.

Return Value

string The quoted input string.

at line 1131
string quoteName(string $name)

Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection risks and reserved word conflicts.

Parameters

string $name The identifier name to wrap in quotes.

Return Value

string The quote wrapped name.

at line 1160
string replacePrefix(string $sql, string $prefix = '#__')

This function replaces a string identifier $prefix with the string held is the tablePrefix class variable.

Parameters

string $sql The SQL statement to prepare.
string $prefix The common table prefix.

Return Value

string The processed SQL statement.

at line 1244
abstract bool select(string $database)

Select a database for use.

Parameters

string $database The name of the database to select for use.

Return Value

bool True if the database was successfully selected.

Exceptions

DatabaseException

at line 1255
bool setDebug(bool $level)

Sets the database debugging state for the driver.

Parameters

bool $level True to enable debugging.

Return Value

bool The old debugging level.

at line 1274
JDatabase setQuery(mixed $query, integer $offset, integer $limit)

Sets the SQL statement string for later execution.

Parameters

mixed $query The SQL statement to set either as a JDatabaseQuery object or a string.
integer $offset The affected row offset to set.
integer $limit The maximum affected rows to set.

Return Value

JDatabase This object to support method chaining.

at line 1290
abstract bool setUTF()

Set the connection to use UTF-8 character encoding.

Return Value

bool True on success.

at line 1300
abstract void transactionCommit()

Method to commit a transaction.

Return Value

void

Exceptions

DatabaseException

at line 1310
abstract void transactionRollback()

Method to roll back a transaction.

Return Value

void

Exceptions

DatabaseException

at line 1320
abstract void transactionStart()

Method to initialize a transaction.

Return Value

void

Exceptions

DatabaseException

at line 1335
bool updateObject(string $table, object $object, string $key, bool $nulls = false)

Updates a row in a table based on an object's properties.

Parameters

string $table The name of the database table to update.
object $object A reference to an object whose public properties match the table fields.
string $key The name of the primary key.
bool $nulls True to update null fields or false to ignore them.

Return Value

bool True on success.

Exceptions

DatabaseException

at line 1402
void debug(integer $level) deprecated

deprecated 12.1

Sets the debug level on or off

Parameters

integer $level 0 to disable debugging and 1 to enable it.

Return Value

void

at line 1418
abstract string explain() deprecated

deprecated 12.1

Diagnostic method to return explain information for a query.

Return Value

string The explain output.

at line 1430
string getErrorMsg(bool $escaped = false) deprecated

deprecated 12.1

Gets the error message from the database connection.

Parameters

bool $escaped True to escape the message string for use in JavaScript.

Return Value

string The error message for the most recent query.

at line 1450
integer getErrorNum() deprecated

deprecated 12.1

Gets the error number from the database connection.

Return Value

integer The error number for the most recent query.

at line 1469
string getEscaped(string $text, bool $extra = false) deprecated

deprecated 11.1

Method to escape a string for usage in an SQL statement.

Parameters

string $text The string to be escaped.
bool $extra Optional parameter to provide extra escaping.

Return Value

string The escaped string.

at line 1489
array getTableFields(mixed $tables, bool $typeOnly = true) deprecated

deprecated 11.1

Retrieves field information about the given tables.

Parameters

mixed $tables A table name or a list of table names.
bool $typeOnly True to only return field types.

Return Value

array An array of fields by table.

Exceptions

DatabaseException

at line 1514
integer getTicker() deprecated

deprecated 12.1

Get the total number of SQL statements executed by the database driver.

Return Value

integer

at line 1532
bool isQuoted(string $field) deprecated

deprecated 12.1

Checks if field name needs to be quoted.

Parameters

string $field The field name to be checked.

Return Value

bool

at line 1557
mixed loadResultArray(integer $offset) deprecated

deprecated 11.1

Method to get an array of values from the $offset field in each row of the result set from the database query.

Parameters

integer $offset The row offset to use to build the result array.

Return Value

mixed The return value or null if the query failed.

Exceptions

DatabaseException

at line 1576
string nameQuote(string $name) deprecated

deprecated 11.1

Wrap an SQL statement identifier name such as column, table or database names in quotes to prevent injection risks and reserved word conflicts.

Parameters

string $name The identifier name to wrap in quotes.

Return Value

string The quote wrapped name.

at line 1592
abstract mixed queryBatch($abortOnError = true, $transactionSafe = false) deprecated

deprecated 12.1

Execute a query batch.

Parameters

$abortOnError
$transactionSafe

Return Value

mixed A database resource if successful, false if not.

at line 1604
string stderr(bool $showSQL = false) deprecated

deprecated 12.1

Return the most recent error message for the database connector.

Parameters

bool $showSQL True to display the SQL statement sent to the database as well as the error.

Return Value

string The error message for the most recent query.