Joomla! API

package	Joomla.Platform
subpackage	Database
since	11.1

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

__call(string $method, array $args) : string

since	11.1

Arguments

$method: stringThe called method.
$args: arrayThe array of arguments passed to the method.

Response

stringThe aliased method's return value or null.

Constructor.

__construct(array $options)

since	11.1

Arguments

$options: arrayList of options used to configure the connection

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

addQuoted(mixed $quoted) : void

deprecated

deprecated	12.1
since	11.1

Arguments

$quoted: mixedField name or array of names.

Determines if the connection to the server is active.

connected() : boolean

abstract

since	11.1

Response

booleanTrue if connected to the database engine.

Sets the debug level on or off

debug(integer $level) : void

deprecated

deprecated	12.1
since	11.1

Arguments

$level: integer0 to disable debugging and 1 to enable it.

Drops a table from the database.

dropTable(string $table, boolean $ifExists = true) : \JDatabase

abstract

since	11.4
throws	`\JDatabaseException`

Arguments

$table: stringThe name of the database table to drop.
$ifExists: booleanOptionally specify that the table must exist before it is dropped.

Response

\JDatabaseReturns this object to support chaining.

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

escape(string $text, boolean $extra = false) : string

abstract

since	11.1

Arguments

$text: stringThe string to be escaped.
$extra: booleanOptional parameter to provide extra escaping.

Response

stringThe escaped string.

Execute the SQL statement.

execute() : mixed

abstract

since	12.1
throws	`\JDatabaseException`

Response

mixedA database cursor resource on success, boolean false on failure.

Diagnostic method to return explain information for a query.

explain() : string

abstract deprecated

deprecated	12.1
since	11.1

Response

stringThe explain output.

Method to fetch a row from the result set cursor as an array.

fetchArray(mixed $cursor = null) : mixed

abstract

since	11.1

Arguments

$cursor: mixedThe optional result set cursor from which to fetch the row.

Response

mixedEither the next row from the result set or false if there are no more rows.

Method to fetch a row from the result set cursor as an associative array.

fetchAssoc(mixed $cursor = null) : mixed

abstract

since	11.1

Arguments

$cursor: mixedThe optional result set cursor from which to fetch the row.

Response

mixedEither the next row from the result set or false if there are no more rows.

Method to fetch a row from the result set cursor as an object.

fetchObject(mixed $cursor = null, string $class = 'stdClass') : mixed

abstract

since	11.1

Arguments

$cursor: mixedThe optional result set cursor from which to fetch the row.
$class: stringThe class name to use for the returned row object.

Response

mixedEither the next row from the result set or false if there are no more rows.

Method to free up the memory used for the result set.

freeResult(mixed $cursor = null) : void

abstract

since	11.1

Arguments

$cursor: mixedThe optional result set cursor from which to fetch the row.

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

getAffectedRows() : integer

abstract

since	11.1

Response

integerThe number of affected rows.

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

getCollation() : mixed

abstract

since	11.1

Response

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

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.

getConnection() : resource

since	11.1

Response

resourceThe underlying database connection resource.

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.

getConnectors() : array

static

since	11.1

Response

arrayAn array of available database connectors.

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

getCount() : integer

since	11.1

Response

integer

Gets the name of the database used by this conneciton.

getDatabase() : string

since	11.4

Response

string

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

getDateFormat() : string

since	11.1

Response

stringThe format string.

Gets the error message from the database connection.

getErrorMsg(boolean $escaped = false) : string

deprecated

deprecated	12.1
since	11.1

Arguments

$escaped: booleanTrue to escape the message string for use in JavaScript.

Response

stringThe error message for the most recent query.

Gets the error number from the database connection.

getErrorNum() : integer

deprecated

since	11.1
deprecated	12.1

Response

integerThe error number for the most recent query.

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

getEscaped(string $text, boolean $extra = false) : string

deprecated

since	11.1
deprecated	12.1

Arguments

$text: stringThe string to be escaped.
$extra: booleanOptional parameter to provide extra escaping.

Response

stringThe escaped string.

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.

getInstance(array $options = array()) : \JDatabase

static

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.

since	11.1

Arguments

$options: arrayParameters to be passed to the database driver.

Response

\JDatabaseA database object.

Get the row limit for the current SQL statement.

getLimit() : integer

deprecated

since	2.5.17
deprecated	3.0 Required for SQLSRV support for 2.5 only

Response

integerThe affected row limit for the current SQL statement.

Get the database driver SQL statement log.

getLog() : array

since	11.1

Response

arraySQL statements executed by the database driver.

Get the minimum supported database version.

getMinimum() : string

since	12.1

Response

stringThe minimum version number for the database driver.

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

getNullDate() : string

since	11.1

Response

stringNull or zero representation of a timestamp.

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

getNumRows(resource $cursor = null) : integer

abstract

since	11.1

Arguments

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

Response

integerThe number of returned rows.

Get the row offset for the current SQL statement.

getOffset() : integer

deprecated

since	2.5.17
deprecated	3.0 Required for SQLSRV support for 2.5 only

Response

integerThe affected row offset to apply for the current SQL statement.

Get the common table prefix for the database driver.

getPrefix() : string

since	11.1

Response

stringThe common database table prefix.

Get the current query object or a new JDatabaseQuery object.

getQuery(boolean $new = false) : \JDatabaseQuery

abstract

since	11.1
throws	`\JDatabaseException`

Arguments

$new: booleanFalse to return the current query object, True to return a new JDatabaseQuery object.

Response

\JDatabaseQueryThe current query object or a new object extending the JDatabaseQuery class.

Retrieves field information about the given tables.

getTableColumns(string $table, boolean $typeOnly = true) : array

abstract

since	11.1
throws	`\JDatabaseException`

Arguments

$table: stringThe name of the database table.
$typeOnly: booleanTrue (default) to only return field types.

Response

arrayAn array of fields by table.

Shows the table CREATE statement that creates the given tables.

getTableCreate(mixed $tables) : array

abstract

since	11.1
throws	`\JDatabaseException`

Arguments

$tables: mixedA table name or a list of table names.

Response

arrayA list of the create SQL for the tables.

Retrieves field information about the given tables.

getTableFields(mixed $tables, boolean $typeOnly = true) : array

deprecated

since	11.1
throws	`\JDatabaseException`
deprecated	12.1

Arguments

$tables: mixedA table name or a list of table names.
$typeOnly: booleanTrue to only return field types.

Response

arrayAn array of fields by table.

Retrieves field information about the given tables.

getTableKeys(mixed $tables) : array

abstract

since	11.1
throws	`\JDatabaseException`

Arguments

$tables: mixedA table name or a list of table names.

Response

arrayAn array of keys for the table(s).

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

getTableList() : array

abstract

since	11.1
throws	`\JDatabaseException`

Response

arrayAn array of all the tables in the database.

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

getTicker() : integer

deprecated

since	11.1
deprecated	12.1

Response

integer

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

getUTFSupport() : boolean

since	11.1

Response

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

Get the version of the database connector

getVersion() : string

abstract

since	11.1

Response

stringThe database connector version.

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

hasUTF() : boolean

abstract deprecated

since	11.1
deprecated	12.1

Response

booleanTrue if supported.

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

insertid() : integer

abstract

since	11.1

Response

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

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

insertObject(string $table,  &$object, string $key = null) : boolean

since	11.1
throws	`\JDatabaseException`

Arguments

$table: stringThe name of the database table to insert into.
$object
$key: stringThe name of the primary key. If provided the object property is updated.

Response

booleanTrue on success.

Method to check whether the installed database version is supported by the database driver

isMinimumVersion() : boolean

since	12.1

Response

booleanTrue if the database version is supported

Checks if field name needs to be quoted.

isQuoted(string $field) : boolean

deprecated

deprecated	12.1
since	11.1

Arguments

$field: stringThe field name to be checked.

Response

boolean

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

loadAssoc() : mixed

since	11.1
throws	`\JDatabaseException`

Response

mixedThe return value or null if the query failed.

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

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

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

since	11.1
throws	`\JDatabaseException`

Arguments

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

Response

mixedThe return value or null if the query failed.

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

loadColumn(integer $offset) : mixed

since	11.1
throws	`\JDatabaseException`

Arguments

$offset: integerThe row offset to use to build the result array.

Response

mixedThe return value or null if the query failed.

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

loadNextObject(string $class = 'stdClass') : mixed

since	11.1
throws	`\JDatabaseException`

Arguments

$class: stringThe class name to use for the returned row object.

Response

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

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

loadNextRow() : mixed

since	11.1
throws	`\JDatabaseException`

Response

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

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

loadObject(string $class = 'stdClass') : mixed

since	11.1
throws	`\JDatabaseException`

Arguments

$class: stringThe class name to use for the returned row object.

Response

mixedThe return value or null if the query failed.

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.

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

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

since	11.1
throws	`\JDatabaseException`

Arguments

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

Response

mixedThe return value or null if the query failed.

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

loadResult() : mixed

since	11.1
throws	`\JDatabaseException`

Response

mixedThe return value or null if the query failed.

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

loadResultArray(integer $offset) : mixed

deprecated

since	11.1
throws	`\JDatabaseException`
deprecated	12.1

Arguments

$offset: integerThe row offset to use to build the result array.

Response

mixedThe return value or null if the query failed.

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.

loadRow() : mixed

since	11.1
throws	`\JDatabaseException`

Response

mixedThe return value or null if the query failed.

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.

loadRowList(string $key = null) : mixed

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

since	11.1
throws	`\JDatabaseException`

Arguments

$key: stringThe name of a field on which to key the result array.

Response

mixedThe return value or null if the query failed.

Locks a table in the database.

lockTable(string $tableName) : \JDatabase

abstract

since	11.4
throws	`\JDatabaseException`

Arguments

$tableName: stringThe name of the table to unlock.

Response

\JDatabaseReturns this object to support chaining.

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

nameQuote(string $name) : string

deprecated

since	11.1
deprecated	12.1

Arguments

$name: stringThe identifier name to wrap in quotes.

Response

stringThe quote wrapped name.

Execute the SQL statement.

query() : mixed

since	11.1
throws	`\JDatabaseException`

Response

mixedA database cursor resource on success, boolean false on failure.

Execute a query batch.

queryBatch(boolean $abortOnError = true, boolean $transactionSafe = false) : mixed

abstract deprecated

deprecated	12.1
since	11.1

Arguments

$abortOnError: booleanAbort on error.
$transactionSafe: booleanTransaction safe queries.

Response

mixedA database resource if successful, false if not.

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

quote(string $text, boolean $escape = true) : string

since	11.1

Arguments

$text: stringThe string to quote.
$escape: booleanTrue (default) to escape the string, false to leave it unchanged.

Response

stringThe quoted input string.

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

quoteName(mixed $name, mixed $as = null) : mixed

since	11.1

Arguments

$name: mixedThe identifier name to wrap in quotes, or an array of identifier names to wrap in quotes. Each type supports dot-notation name.
$as: mixedThe AS query part associated to $name. It can be string or array, in latter case it has to be same length of $name; if is null there will not be any AS part for string or array element.

Response

mixedThe quote wrapped name, same type of $name.

Quote strings coming from quoteName call.

quoteNameStr(array $strArr) : string

since	11.3

Arguments

$strArr: arrayArray of strings coming from quoteName dot-explosion.

Response

stringDot-imploded string of quoted parts.

Renames a table in the database.

renameTable(string $oldTable, string $newTable, string $backup = null, string $prefix = null) : \JDatabase

abstract

since	11.4
throws	`\JDatabaseException`

Arguments

$oldTable: stringThe name of the table to be renamed
$newTable: stringThe new name for the table.
$backup: stringTable prefix
$prefix: stringFor the table - used to rename constraints in non-mysql databases

Response

\JDatabaseReturns this object to support chaining.

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

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

since	11.1

Arguments

$sql: stringThe SQL statement to prepare.
$prefix: stringThe common table prefix.

Response

stringThe processed SQL statement.

Select a database for use.

select(string $database) : boolean

abstract

since	11.1
throws	`\JDatabaseException`

Arguments

$database: stringThe name of the database to select for use.

Response

booleanTrue if the database was successfully selected.

Sets the database debugging state for the driver.

setDebug(boolean $level) : boolean

since	11.1

Arguments

$level: booleanTrue to enable debugging.

Response

booleanThe old debugging level.

Sets the SQL statement string for later execution.

setQuery(mixed $query, integer $offset, integer $limit) : \JDatabase

since	11.1

Arguments

$query: mixedThe SQL statement to set either as a JDatabaseQuery object or a string.
$offset: integerThe affected row offset to set.
$limit: integerThe maximum affected rows to set.

Response

\JDatabaseThis object to support method chaining.

Set the connection to use UTF-8 character encoding.

setUTF() : boolean

abstract

since	11.1

Response

booleanTrue on success.

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

splitSql(string $sql) : array

static

since	11.1

Arguments

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

Response

arrayThe queries from the input string separated into an array.

Return the most recent error message for the database connector.

stderr(boolean $showSQL = false) : string

deprecated

deprecated	12.1
since	11.1

Arguments

$showSQL: booleanTrue to display the SQL statement sent to the database as well as the error.

Response

stringThe error message for the most recent query.

Method to commit a transaction.

transactionCommit() : void

abstract

since	11.1
throws	`\JDatabaseException`

Method to roll back a transaction.

transactionRollback() : void

abstract

since	11.1
throws	`\JDatabaseException`

Method to initialize a transaction.

transactionStart() : void

abstract

since	11.1
throws	`\JDatabaseException`

Method to truncate a table.

truncateTable(string $table) : void

since	11.3
throws	`\JDatabaseException`

Arguments

$table: stringThe table to truncate

Unlocks tables in the database.

unlockTables() : \JDatabase

abstract

since	11.4
throws	`\JDatabaseException`

Response

\JDatabaseReturns this object to support chaining.

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

updateObject(string $table,  &$object, string $key, boolean $nulls = false) : boolean

since	11.1
throws	`\JDatabaseException`

Arguments

$table: stringThe name of the database table to update.
$object
$key: stringThe name of the primary key.
$nulls: booleanTrue to update null fields or false to ignore them.

Response

booleanTrue on success.

The name of the database.

since	11.4

Type(s)

string

The name of the database driver.

since	11.1

Type(s)

string

The database connection resource.

since	11.1

Type(s)

resource

The number of SQL statements executed by the database driver.

since	11.1

Type(s)

integer

The database connection cursor from the last query.

since	11.1

Type(s)

resource

The database driver debugging state.

since	11.1

Type(s)

boolean

The affected row limit for the current SQL statement.

since	11.1

Type(s)

integer

The log of executed SQL statements by the database driver.

since	11.1

Type(s)

array

The character(s) used to quote SQL statement names such as table names or field names, etc. The child classes should define this as necessary. If a single character string the same character is used for both sides of the quoted name, else the first character will be used for the opening quote and the second for the closing quote.

since	11.1

Type(s)

string

The null or zero representation of a timestamp for the database driver. This should be defined in child classes to hold the appropriate value for the engine.

since	11.1

Type(s)

string

The affected row offset to apply for the current SQL statement.

since	11.1

Type(s)

integer

The current SQL statement to execute.

since	11.1

Type(s)

mixed

The common database table prefix.

since	11.1

Type(s)

string

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

since	11.1

Type(s)

boolean

The database error number

deprecated

since	11.1
deprecated	12.1

Type(s)

integer

The database error message

deprecated

since	11.1
deprecated	12.1

Type(s)

string

If true then there are fields to be quoted for the query.

deprecated

since	11.1
deprecated	12.1

Type(s)

boolean

The fields that are to be quoted.

deprecated

since	11.1
deprecated	12.1

Type(s)

array

JDatabase instances container.

static

since	11.1

Type(s)

array

The minimum supported database version.

since	12.1

Type(s)

string

JDatabase

Methods

__call

Arguments

Response

__construct

Arguments

addQuoted

Arguments

connected

Response

debug

Arguments

dropTable

Arguments

Response

escape

Arguments

Response

execute

Response

explain

Response

fetchArray

Arguments

Response

fetchAssoc

Arguments

Response

fetchObject

Arguments

Response

freeResult

Arguments

getAffectedRows

Response

getCollation

Response

getConnection

Response

getConnectors

Response

getCount

Response

getDatabase

Response

getDateFormat

Response

getErrorMsg

Arguments

Response

getErrorNum

Response

getEscaped

Arguments

Response

getInstance

Arguments

Response

getLimit

Response

getLog

Response

getMinimum

Response

getNullDate

Response

getNumRows

Arguments

Response

getOffset

Response

getPrefix

Response

getQuery

Arguments

Response

getTableColumns

Arguments

Response