Joomla! API

Constructor.

__construct(mixed||string|int options) :

since	1.0

Arguments

options: array<string|int, mixed>List of options used to configure the connection

Response

mixed

Destructor.

__destruct() :

since	2.0.0

Response

mixed

Magic method to access properties of the database driver.

__get( name) :

deprecated

since	1.4.0
deprecated	3.0 This is a B/C proxy since $this->name was previously public

Arguments

name: stringThe name of the property.

Response

mixedA value if the property name is valid, null otherwise.

Alter database's character set.

alterDbCharacterSet( dbName) : bool|resource

since	2.0.0
throws	`RuntimeException`

Arguments

dbName: stringThe database name that will be altered

Response

bool|resource

Create a new database using information from $options object.

createDatabase(\stdClass options,  utf = true) : bool|resource

since	2.0.0
throws	`RuntimeException`

Arguments

options: stdClassObject used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
utf: boolTrue if the database supports the UTF-8 character set.

Response

bool|resource

Create a new DatabaseQuery object.

createQuery() : \Joomla\Database\QueryInterface

since	2.2

Response

QueryInterface

Replace special placeholder representing binary field with the original string.

decodeBinary(string|resource data) :

since	1.7.0

Arguments

data: string|resourceEncoded string or resource.

Response

stringThe original string.

Disconnects the database.

disconnect() :

since	2.0.0

Response

void

Dispatch an event.

dispatchEvent(\Joomla\Event\EventInterface event) :

since	2.0.0

Arguments

event: EventInterfaceThe event to dispatch

Response

void

Drops a table from the database.

dropTable( table,  ifExists = true) :

since	2.0.0
throws	`RuntimeException`

Arguments

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

Response

$this

Execute the SQL statement.

execute() :

since	2.0.0
throws	`RuntimeException`

Response

bool

Extract pure host name (or IP address) and port or socket from host name option.

extractHostPortSocket( host, int|null port, string|null socket,  defaultPort,  ipv6SquareBrackets = true) : mixed||string|int

since	3.3.0

Arguments

host: stringHost given in options used to configure the connection.
port: int|nullPort given in options used to configure the connection, null if none.
socket: string|nullSocket given in options used to configure the connection, null if none.
defaultPort: intThe default port number to be used if no port is given.
ipv6SquareBrackets: boolTrue if database connector uses ipv6 address with square brackets, false if not.

Response

array<string|int, mixed>Array with host, port and socket.

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

fetchArray() :

since	1.0

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() :

since	1.0

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() :

Note, the fetch mode should be configured before calling this method using StatementInterface::setFetchMode().

since	1.0

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() :

since	1.0

Response

void

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

getAffectedRows() :

since	2.0.0

Response

intThe number of affected rows in the previous operation

Return the query string to alter the database character set.

getAlterDbCharacterSet( dbName) :

since	1.6.0

Arguments

dbName: stringThe database name

Response

stringThe query that alter the database query string

Method that provides access to the underlying database connection.

getConnection() :

since	1.0

Response

resourceThe underlying database connection resource.

Get a list of available database connectors.

getConnectors() : mixed||string|int

static

The list will only be populated with connectors that the class exists for and the environment supports its use. 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.

since	1.0

Response

array<string|int, mixed>An array of available database connectors.

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

getCount() :

since	1.0

Response

int

Return the query string to create new Database.

getCreateDatabaseQuery(\stdClass options,  utf) :

since	2.0.0

Arguments

options: stdClassObject used to pass user and database name to database driver. This object must have "db_name" and "db_user" set.
utf: boolTrue if the database supports the UTF-8 character set.

Response

stringThe query that creates database

Gets the name of the database used by this connection.

getDatabase() :

since	1.0

Response

string

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

getDateFormat() :

since	1.0

Response

string

Get the event dispatcher.

getDispatcher() : \Joomla\Event\DispatcherInterface

inherited

since	1.2.0
throws	`UnexpectedValueException`May be thrown if the dispatcher has not been set.

Response

DispatcherInterface

Gets an exporter class object.

getExporter() : \Joomla\Database\DatabaseExporter

since	1.0
throws	`RuntimeException`

Response

DatabaseExporterAn exporter object.

Gets an importer class object.

getImporter() : \Joomla\Database\DatabaseImporter

since	1.0

Response

DatabaseImporter

Method to return a DatabaseDriver instance based on the given options.

getInstance(mixed||string|int options = []) : \Joomla\Database\DatabaseDriver

static deprecated

There are three global options and then the rest are specific to the database driver.

The 'driver' option defines which DatabaseDriver class is used for the connection -- the default is 'mysqli'.
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.

since	1.0
throws	`RuntimeException`
deprecated	3.0 Use DatabaseFactory::getDriver() instead

Arguments

options: array<string|int, mixed>Parameters to be passed to the database driver.

Response

DatabaseDriver

Get a new iterator on the current query.

getIterator( column = null,  class = stdClass::class) : \Joomla\Database\DatabaseIterator

since	1.0

Arguments

column: stringAn option column to use as the iterator key.
class: stringThe class of object that is returned.

Response

DatabaseIterator

Get the minimum supported database version.

getMinimum() :

since	1.0

Response

string

Get the query monitor.

getMonitor() : \Joomla\Database\QueryMonitorInterface|null

since	2.0.0

Response

QueryMonitorInterface|nullThe query monitor or null if not set.

Get the name of the database driver.

getName() :

If $this->name is not set it will try guessing the driver name from the class name.

since	1.4.0

Response

string

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

getNullDate() :

since	1.0

Response

string

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

getNumRows() :

since	2.0.0

Response

intThe number of returned rows.

Get the common table prefix for the database driver.

getPrefix() :

since	1.0

Response

stringThe common database table prefix.

Get the current query object or a new DatabaseQuery object.

getQuery( new = false) : \Joomla\Database\DatabaseQuery

since	1.0

Arguments

new: boolFalse to return the current query object, True to return a new DatabaseQuery object. The $new parameter is deprecated in 2.2 and will be removed in 4.0, use createQuery() instead.

Response

DatabaseQuery

Get the server family type.

getServerType() :

If $this->serverType is not set it will attempt guessing the server family type from the driver name. If this is not possible the driver name will be returned instead.

since	1.4.0

Response

string

Shows the table CREATE statement that creates the given tables.

getTableCreate( tables) : mixed||string|int

abstract

since	1.0
throws	`RuntimeException`

Arguments

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

Response

array<string|int, mixed>A list of the create SQL for the tables.

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

hasUtfSupport() :

since	1.0

Response

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

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

insertObject( table,  &object,  key = null) :

since	1.0
throws	`RuntimeException`

Arguments

table: stringThe name of the database table to insert into.
object: objectA reference to an object whose public properties match the table fields.
key: stringThe name of the primary key. If provided the object property is updated.

Response

bool

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

isMinimumVersion() :

since	1.0

Response

boolTrue if the database version is supported

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

loadAssoc() :

since	1.0
throws	`RuntimeException`

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( key = null,  column = null) :

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

since	1.0
throws	`RuntimeException`

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( offset) :

since	1.0
throws	`RuntimeException`

Arguments

offset: intThe 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 object.

loadObject( class = stdClass::class) :

since	1.0
throws	`RuntimeException`

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( key = '',  class = stdClass::class) :

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

since	1.0
throws	`RuntimeException`

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() :

since	1.0
throws	`RuntimeException`

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.

loadRow() :

Columns are indexed numerically so the first column in the result set would be accessible via $row[0], etc.

since	1.0
throws	`RuntimeException`

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( key = null) : mixed||string|int

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

since	1.0
throws	`RuntimeException`

Arguments

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

Response

array<string|int, mixed>An array of results.

Prepares a SQL statement for execution

prepareStatement( query) : \Joomla\Database\StatementInterface

abstract

since	2.0.0
throws	`PrepareStatementFailureException`

Arguments

query: stringThe SQL query to be prepared.

Response

StatementInterface

Alias for quote method

q(array|string text,  escape = true) :

since	1.0

Arguments

text: array<string|int, mixed>|stringA string or an array of strings to quote.
escape: boolTrue (default) to escape the string, false to leave it unchanged.

Response

stringThe quoted input string.

Alias for quoteName method

qn(array|string name, array|string as = null) : array|string

since	1.0

Arguments

name: array<string|int, mixed>|stringThe identifier name to wrap in quotes, or an array of identifier names to wrap in quotes. Each type supports dot-notation name.
as: array<string|int, mixed>|stringThe 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

array<string|int, mixed>|stringThe quote wrapped name, same type of $name.

Quotes and optionally escapes a string to database requirements for use in database queries.

quote(array|string text,  escape = true) : array|string

since	1.0

Arguments

text: array<string|int, mixed>|stringA string or an array of strings to quote.
escape: boolTrue (default) to escape the string, false to leave it unchanged.

Response

array<string|int, mixed>|stringThe quoted input string.

Quotes a binary string to database requirements for use in database queries.

quoteBinary( data) :

since	1.7.0

Arguments

data: stringA binary string to quote.

Response

stringThe binary 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(array|string name, array|string as = null) : array|string

since	1.0

Arguments

name: array<string|int, mixed>|stringThe identifier name to wrap in quotes, or an array of identifier names to wrap in quotes. Each type supports dot-notation name.
as: array<string|int, mixed>|stringThe 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

array<string|int, mixed>|stringThe quote wrapped name, same type of $name.

Quote strings coming from quoteName call.

quoteNameStr(mixed||string|int strArr) :

deprecated

since	1.0
deprecated	2.0 Use quoteNameString instead

Arguments

strArr: array<string|int, mixed>Array of strings coming from quoteName dot-explosion.

Response

stringDot-imploded string of quoted parts.

Quote string coming from quoteName call.

quoteNameString( name,  asSinglePart = false) :

since	1.7.0

Arguments

name: stringIdentifier name to be quoted.
asSinglePart: boolTreat the name as a single part of the identifier.

Response

stringQuoted identifier string.

This function replaces a string identifier with the configured table prefix.

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

since	1.0

Arguments

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

Response

stringThe processed SQL statement.

Set the dispatcher to use.

setDispatcher(\Joomla\Event\DispatcherInterface dispatcher) :

inherited

since	1.2.0

Arguments

dispatcher: DispatcherInterfaceThe dispatcher to use.

Response

$this

Set a query monitor.

setMonitor(\Joomla\Database\QueryMonitorInterface|null monitor = null) :

since	2.0.0

Arguments

monitor: QueryMonitorInterface|nullThe query monitor.

Response

$this

Sets the SQL statement string for later execution.

setQuery(string|\Joomla\Database\QueryInterface query,  offset,  limit) :

since	1.0
throws	`InvalidArgumentException`

Arguments

query: string|QueryInterfaceThe SQL statement to set either as a Query object or a string.
offset: intThe affected row offset to set. {@deprecated Use LimitableInterface::setLimit() instead}
limit: intThe maximum affected rows to set. {@deprecated Use LimitableInterface::setLimit() instead}

Response

$this

Set the connection to use UTF-8 character encoding.

setUtf() :

abstract

since	1.0

Response

boolTrue on success.

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

splitSql( sql) : mixed||string|int

static

since	1.0

Arguments

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

Response

array<string|int, mixed>

Method to truncate a table.

truncateTable( table) :

since	1.0
throws	`RuntimeException`

Arguments

table: stringThe table to truncate

Response

void

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

updateObject( table,  &object, array|string key,  nulls = false) :

since	1.0
throws	`RuntimeException`

Arguments

table: stringThe name of the database table to update.
object: objectA reference to an object whose public properties match the table fields.
key: array<string|int, mixed>|stringThe name of the primary key.
nulls: boolTrue to update null fields or false to ignore them.

Response

boolTrue on success.

Event Dispatcher

inherited

since	1.2.0

Type(s)

DispatcherInterface|null

The name of the database.

since	1.0

Type(s)

string

The name of the database driver.

since	1.0

Type(s)

string

The type of the database server family supported by this driver.

since	1.4.0

Type(s)

string

The database connection resource.

since	1.0

Type(s)

resource

Holds the list of available db connectors.

static

since	1.0

Type(s)

array<string|int, mixed>

The number of SQL statements executed by the database driver.

since	1.0

Type(s)

int

The database connection cursor from the last query.

since	1.0

Type(s)

resource

Contains the current query execution status

since	2.0.0

Type(s)

bool

The affected row limit for the current SQL statement.

since	1.0

Type(s)

int

The character(s) used to quote SQL statement names such as table names or field names, etc.

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	1.0

Type(s)

string

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

since	1.0

Type(s)

string

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

since	1.0

Type(s)

int

Passed in upon instantiation and saved.

since	1.0

Type(s)

array<string|int, mixed>

The current SQL statement to execute.

since	1.0

Type(s)

mixed

The prepared statement.

since	2.0.0

Type(s)

StatementInterface

The common database table prefix.

since	1.0

Type(s)

string

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

since	1.0

Type(s)

bool

The database error number.

since	1.0

Type(s)

int

The database error message.

since	1.0

Type(s)

string

DatabaseDriver instances container.

static deprecated

since	1.0
deprecated	3.0 Singleton storage will no longer be supported.

Type(s)

array<string|int, DatabaseDriver>

The minimum supported database version.

static

since	1.0

Type(s)

string

The depth of the current transaction.

since	1.0

Type(s)

int

DatabaseFactory object

since	2.0.0

Type(s)

DatabaseFactory

Query monitor object

since	2.0.0

Type(s)

QueryMonitorInterface

since	1.0
package	Joomla Framework

DatabaseDriver

Methods

__construct

Arguments

Response

__destruct

Response

__get

Arguments

Response

alterDbCharacterSet

Arguments

Response

createDatabase

Arguments

Response

createQuery

Response

decodeBinary

Arguments

Response

disconnect

Response

dispatchEvent

Arguments

Response

dropTable

Arguments

Response

execute

Response

extractHostPortSocket

Arguments

Response

fetchArray

Response

fetchAssoc

Response

fetchObject

Response

freeResult

Response

getAffectedRows

Response

getAlterDbCharacterSet

Arguments

Response

getConnection

Response

getConnectors

Response

getCount

Response

getCreateDatabaseQuery

Arguments

Response

getDatabase

Response

getDateFormat

Response

getDispatcher

Response

getExporter

Response

getImporter

Response

getInstance

Arguments

Response

getIterator

Arguments

Response

getMinimum

Response

getMonitor

Response

getName

Response

getNullDate

Response