DatabaseQuery

Joomla Framework Query Building Class.

abstract
since

1.0

package

Joomla Framework

Methods

__call

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

__call(string method, array args) : mixed
since

1.0

Arguments

method

stringThe called method.

args

arrayThe array of arguments passed to the method.

Response

mixedThe aliased method's return value or null.

__clone

Method to provide deep copy support to nested objects and arrays when cloning.

__clone() : void
since

1.0

__construct

Class constructor.

__construct(\Joomla\Database\DatabaseDriver db = null) : mixed
since

1.0

Arguments

db

\Joomla\Database\DatabaseDriverThe database driver.

Response

mixed

__get

Magic function to get protected variable value

__get(string name) : mixed
since

1.0

Arguments

name

stringThe name of the variable.

Response

mixed

__toString

Magic function to convert the query to a string.

__toString() : string
since

1.0

Response

stringThe completed query.

andWhere

Extend the WHERE clause with an AND and a single condition or an array of conditions.

andWhere(mixed conditions, string glue = 'OR') : \Joomla\Database\DatabaseQuery

Usage: $query->where(array('a = 1', 'b = 2'))->andWhere(array('c = 3', 'd = 4')); will produce: WHERE ((a = 1 AND b = 2) AND (c = 3 OR d = 4)

since

1.3.0

Arguments

conditions

mixedA string or array of WHERE conditions.

glue

stringThe glue by which to join the conditions. Defaults to OR.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

call

Add a single column, or array of columns to the CALL clause of the query.

call(mixed columns) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query. The call method can, however, be called multiple times in the same query.

Usage: $query->call('a.')->call('b.id'); $query->call(array('a.', 'b.id'));

since

1.0

Arguments

columns

mixedA string or an array of field names.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

castAsChar

Casts a value to a char.

castAsChar(string value) : string

Ensure that the value is properly quoted before passing to the method.

Usage: $query->select($query->castAsChar('a'));

since

1.0

Arguments

value

stringThe value to cast as a char.

Response

stringReturns the cast value.

charLength

Gets the number of characters in a string.

charLength(string field, string operator = null, string condition = null) : string

Note, use 'length' to find the number of bytes in a string.

Usage: $query->select($query->charLength('a'));

since

1.0

Arguments

field

stringA value.

operator

stringComparison operator between charLength integer value and $condition

condition

stringInteger value to compare charLength with.

Response

stringThe required char length call.

clear

Clear data from the query or a specific clause of the query.

clear(string clause = null) : \Joomla\Database\DatabaseQuery
since

1.0

Arguments

clause

stringOptionally, the name of the clause to clear, or nothing to clear the whole query.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

columns

Adds a column, or array of column names that would be used for an INSERT INTO statement.

columns(array|string columns) : \Joomla\Database\DatabaseQuery
since

1.0

Arguments

columns

array|stringA column name, or array of column names.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

concatenate

Concatenates an array of column names or values.

concatenate(array values, string separator = null) : string

Usage: $query->select($query->concatenate(array('a', 'b')));

since

1.0

Arguments

values

arrayAn array of values to concatenate.

separator

stringAs separator to place between each value.

Response

stringThe concatenated values.

currentTimestamp

Gets the current date and time.

currentTimestamp() : string

Usage: $query->where('published_up < '.$query->currentTimestamp());

since

1.0

Response

string

dateAdd

Add to the current date and time.

dateAdd(string date, string interval, string datePart) : string

Usage: $query->select($query->dateAdd());

Prefixing the interval with a - (negative sign) will cause subtraction to be used. Note: Not all drivers support all units.

link
since

1.5.0

Arguments

date

stringThe db quoted string representation of the date to add to. May be date or datetime

interval

stringThe string representation of the appropriate number of units

datePart

stringThe part of the date to perform the addition on

Response

stringThe string with the appropriate sql for addition of dates

dateFormat

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

dateFormat() : string

This method is provided for use where the query object is passed to a function for modification. If you have direct access to the database object, it is recommended you use the getDateFormat method directly.

since

1.0

throws

\RuntimeException

Response

stringThe format string.

day

Used to get a string to extract day from date column.

day(string date) : string

Usage: $query->select($query->day($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing day to be extracted.

Response

stringReturns string to extract day from a date.

delete

Add a table name to the DELETE clause of the query.

delete(string table = null) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query.

Usage: $query->delete('#__a')->where('id = 1');

since

1.0

Arguments

table

stringThe name of the table to delete from.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

dump

Creates a formatted dump of the query for debugging purposes.

dump() : string

Usage: echo $query->dump();

since

1.0

Response

string

e

e(mixed text, mixed extra) : string

Alias for escape method

Arguments

text

mixed

extra

mixed

Response

string

escape

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

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

This method is provided for use where the query object is passed to a function for modification. If you have direct access to the database object, it is recommended you use the escape method directly.

Note that 'e' is an alias for this method as it is in JDatabaseDatabaseDriver.

since

1.0

throws

\RuntimeExceptionif the internal db property is not a valid object.

Arguments

text

stringThe string to be escaped.

extra

boolOptional parameter to provide extra escaping.

Response

stringThe escaped string.

exec

Add a single column, or array of columns to the EXEC clause of the query.

exec(array|string columns) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query. The exec method can, however, be called multiple times in the same query.

Usage: $query->exec('a.')->exec('b.id'); $query->exec(array('a.', 'b.id'));

since

1.0

Arguments

columns

array|stringA string or an array of field names.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

extendWhere

Extend the WHERE clause with a single condition or an array of conditions, with a potentially different logical operator from the one in the current WHERE clause.

extendWhere(string outerGlue, mixed conditions, string innerGlue = 'AND') : \Joomla\Database\DatabaseQuery

Usage: $query->where(array('a = 1', 'b = 2'))->extendWhere('XOR', array('c = 3', 'd = 4')); will produce: WHERE ((a = 1 AND b = 2) XOR (c = 3 AND d = 4)

since

1.3.0

Arguments

outerGlue

stringThe glue by which to join the conditions to the current WHERE conditions.

conditions

mixedA string or array of WHERE conditions.

innerGlue

stringThe glue by which to join the conditions. Defaults to AND.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

findInSet

Find a value in a varchar used like a set.

findInSet(string value, string set) : string

Ensure that the value is an integer before passing to the method.

Usage: $query->findInSet((int) $parent->id, 'a.assigned_cat_ids')

since

1.5.0

Arguments

value

stringThe value to search for.

set

stringThe set of values.

Response

stringA representation of the MySQL find_in_set() function for the driver.

format

Find and replace sprintf-like tokens in a format string.

format(string format) : string

Each token takes one of the following forms: %% - A literal percent character. %[t] - Where [t] is a type specifier. %[n]$[x] - Where [n] is an argument specifier and [t] is a type specifier.

Types: a - Numeric: Replacement text is coerced to a numeric type but not quoted or escaped. e - Escape: Replacement text is passed to $this->escape(). E - Escape (extra): Replacement text is passed to $this->escape() with true as the second argument. n - Name Quote: Replacement text is passed to $this->quoteName(). q - Quote: Replacement text is passed to $this->quote(). Q - Quote (no escape): Replacement text is passed to $this->quote() with false as the second argument. r - Raw: Replacement text is used as-is. (Be careful)

Date Types:

  • Replacement text automatically quoted (use uppercase for Name Quote).
  • Replacement text should be a string in date format or name of a date column. y/Y - Year m/M - Month d/D - Day h/H - Hour i/I - Minute s/S - Second

Invariable Types:

  • Takes no argument.
  • Argument index not incremented. t - Replacement text is the result of $this->currentTimestamp(). z - Replacement text is the result of $this->nullDate(false). Z - Replacement text is the result of $this->nullDate(true).

Usage: $query->format('SELECT %1$n FROM %2$n WHERE %3$n = %4$a', 'foo', '#__foo', 'bar', 1); Returns: SELECT foo FROM #__foo WHERE bar = 1

Notes: The argument specifier is optional but recommended for clarity. The argument index used for unspecified tokens is incremented only when used.

since

1.0

Arguments

format

stringThe formatting string.

Response

stringReturns a string produced according to the formatting string.

from

Add a table to the FROM clause of the query.

from(array|string tables, string subQueryAlias = null) : \Joomla\Database\DatabaseQuery

Note that while an array of tables can be provided, it is recommended you use explicit joins.

Usage: $query->select('*')->from('#__a');

since

1.0

throws

\RuntimeException

Arguments

tables

array|stringA string or array of table names. This can be a DatabaseQuery object (or a child of it) when used as a subquery in FROM clause along with a value for $subQueryAlias.

subQueryAlias

stringAlias used when $tables is a DatabaseQuery.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

group

Add a grouping column to the GROUP clause of the query.

group(array|string columns) : \Joomla\Database\DatabaseQuery

Usage: $query->group('id');

since

1.0

Arguments

columns

array|stringA string or array of ordering columns.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

having

A conditions to the HAVING clause of the query.

having(array|string conditions, string glue = 'AND') : \Joomla\Database\DatabaseQuery

Usage: $query->group('id')->having('COUNT(id) > 5');

since

1.0

Arguments

conditions

array|stringA string or array of columns.

glue

stringThe glue by which to join the conditions. Defaults to AND.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

hour

Used to get a string to extract hour from date column.

hour(string date) : string

Usage: $query->select($query->hour($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing hour to be extracted.

Response

stringReturns string to extract hour from a date.

innerJoin

Add an INNER JOIN clause to the query.

innerJoin(string condition) : \Joomla\Database\DatabaseQuery

Usage: $query->innerJoin('b ON b.id = a.id')->innerJoin('c ON c.id = b.id');

since

1.0

Arguments

condition

stringThe join condition.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

insert

Add a table name to the INSERT clause of the query.

insert(string table, bool incrementField = false) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query.

Usage: $query->insert('#__a')->set('id = 1'); $query->insert('#__a')->columns('id, title')->values('1,2')->values('3,4'); $query->insert('#__a')->columns('id, title')->values(array('1,2', '3,4'));

since

1.0

Arguments

table

stringThe name of the table to insert data into.

incrementField

boolThe name of the field to auto increment.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

join

Add a JOIN clause to the query.

join(string type, array|string conditions) : \Joomla\Database\DatabaseQuery

Usage: $query->join('INNER', 'b ON b.id = a.id);

since

1.0

Arguments

type

stringThe type of join. This string is prepended to the JOIN keyword.

conditions

array|stringA string or array of conditions.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

leftJoin

Add a LEFT JOIN clause to the query.

leftJoin(string condition) : \Joomla\Database\DatabaseQuery

Usage: $query->leftJoin('b ON b.id = a.id')->leftJoin('c ON c.id = b.id');

since

1.0

Arguments

condition

stringThe join condition.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

length

Get the length of a string in bytes.

length(string value) : int

Note, use 'charLength' to find the number of characters in a string.

Usage: query->where($query->length('a').' > 3');

since

1.0

Arguments

value

stringThe string to measure.

Response

int

minute

Used to get a string to extract minute from date column.

minute(string date) : string

Usage: $query->select($query->minute($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing minute to be extracted.

Response

stringReturns string to extract minute from a date.

month

Used to get a string to extract month from date column.

month(string date) : string

Usage: $query->select($query->month($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing month to be extracted.

Response

stringReturns string to extract month from a date.

nullDate

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

nullDate(bool quoted = true) : string

This method is provided for use where the query object is passed to a function for modification. If you have direct access to the database object, it is recommended you use the nullDate method directly.

Usage: $query->where('modified_date <> '.$query->nullDate());

since

1.0

throws

\RuntimeException

Arguments

quoted

boolOptionally wraps the null date in database quotes (true by default).

Response

stringNull or zero representation of a timestamp.

order

Add a ordering column to the ORDER clause of the query.

order(array|string columns) : \Joomla\Database\DatabaseQuery

Usage: $query->order('foo')->order('bar'); $query->order(array('foo','bar'));

since

1.0

Arguments

columns

array|stringA string or array of ordering columns.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

orWhere

Extend the WHERE clause with an OR and a single condition or an array of conditions.

orWhere(mixed conditions, string glue = 'AND') : \Joomla\Database\DatabaseQuery

Usage: $query->where(array('a = 1', 'b = 2'))->orWhere(array('c = 3', 'd = 4')); will produce: WHERE ((a = 1 AND b = 2) OR (c = 3 AND d = 4)

since

1.3.0

Arguments

conditions

mixedA string or array of WHERE conditions.

glue

stringThe glue by which to join the conditions. Defaults to AND.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

outerJoin

Add an OUTER JOIN clause to the query.

outerJoin(string condition) : \Joomla\Database\DatabaseQuery

Usage: $query->outerJoin('b ON b.id = a.id')->outerJoin('c ON c.id = b.id');

since

1.0

Arguments

condition

stringThe join condition.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

q

q(mixed text, mixed escape) : string

Alias for quote method

Arguments

text

mixed

escape

mixed

Response

string

qn

qn(mixed name, mixed as) : string

Alias for quoteName method

Arguments

name

mixed

as

mixed

Response

string

quote

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

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

This method is provided for use where the query object is passed to a function for modification. If you have direct access to the database object, it is recommended you use the quote method directly.

Note that 'q' is an alias for this method as it is in DatabaseDriver.

Usage: $query->quote('fulltext'); $query->q('fulltext'); $query->q(array('option', 'fulltext'));

since

1.0

throws

\RuntimeExceptionif the internal db property is not a valid object.

Arguments

text

array|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.

quoteName

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

This method is provided for use where the query object is passed to a function for modification. If you have direct access to the database object, it is recommended you use the quoteName method directly.

Note that 'qn' is an alias for this method as it is in DatabaseDriver.

Usage: $query->quoteName('#__a'); $query->qn('#__a');

since

1.0

throws

\RuntimeExceptionif the internal db property is not a valid object.

Arguments

name

array|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|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|stringThe quote wrapped name, same type of $name.

rand

Get the function to return a random floating-point value

rand() : string

Usage: $query->rand();

since

1.5.0

Response

string

regexp

Get the regular expression operator

regexp(string value) : string

Usage: $query->where('field ' . $query->regexp($search));

since

1.5.0

Arguments

value

stringThe regex pattern.

Response

string

rightJoin

Add a RIGHT JOIN clause to the query.

rightJoin(string condition) : \Joomla\Database\DatabaseQuery

Usage: $query->rightJoin('b ON b.id = a.id')->rightJoin('c ON c.id = b.id');

since

1.0

Arguments

condition

stringThe join condition.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

second

Used to get a string to extract seconds from date column.

second(string date) : string

Usage: $query->select($query->second($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing second to be extracted.

Response

stringReturns string to extract second from a date.

select

Add a single column, or array of columns to the SELECT clause of the query.

select(array|string columns) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query. The select method can, however, be called multiple times in the same query.

Usage: $query->select('a.')->select('b.id'); $query->select(array('a.', 'b.id'));

since

1.0

Arguments

columns

array|stringA string or an array of field names.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

set

Add a single condition string, or an array of strings to the SET clause of the query.

set(array|string conditions, string glue = ',') : \Joomla\Database\DatabaseQuery

Usage: $query->set('a = 1')->set('b = 2'); $query->set(array('a = 1', 'b = 2');

since

1.0

Arguments

conditions

array|stringA string or array of string conditions.

glue

stringThe glue by which to join the condition strings. Defaults to ,. Note that the glue is set on first use and cannot be changed.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

setQuery

Allows a direct query to be provided to the database driver's setQuery() method, but still allow queries to have bounded variables.

setQuery(\Joomla\Database\DatabaseQuery|string sql) : \Joomla\Database\DatabaseQuery

Usage: $query->setQuery('select * from #__users');

since

1.0

Arguments

sql

\Joomla\Database\DatabaseQuery|stringA SQL query string or DatabaseQuery object

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

union

Add a query to UNION with the current query.

union(\Joomla\Database\DatabaseQuery|string query, bool distinct = false, string glue = '') : \Joomla\Database\DatabaseQuery

Multiple unions each require separate statements and create an array of unions.

Usage: $query->union('SELECT name FROM #__foo') $query->union('SELECT name FROM #__foo','distinct') $query->union(array('SELECT name FROM #__foo', 'SELECT name FROM #__bar'))

since

1.0

Arguments

query

\Joomla\Database\DatabaseQuery|stringThe DatabaseQuery object or string to union.

distinct

boolTrue to only return distinct rows from the union.

glue

stringThe glue by which to join the conditions.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

unionAll

Add a query to UNION ALL with the current query.

unionAll(\Joomla\Database\DatabaseQuery|string query, bool distinct = false, string glue = '') : \Joomla\Database\DatabaseQuery

Multiple unions each require separate statements and create an array of unions.

Usage: $query->union('SELECT name FROM #__foo') $query->union(array('SELECT name FROM #__foo','SELECT name FROM #__bar'))

see union
since

1.5.0

Arguments

query

\Joomla\Database\DatabaseQuery|stringThe DatabaseQuery object or string to union.

distinct

boolNot used - ignored.

glue

stringThe glue by which to join the conditions.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

unionDistinct

Add a query to UNION DISTINCT with the current query. Simply a proxy to Union with the Distinct clause.

unionDistinct(\Joomla\Database\DatabaseQuery|string query, string glue = '') : \Joomla\Database\DatabaseQuery

Usage: $query->unionDistinct('SELECT name FROM #__foo')

since

1.0

Arguments

query

\Joomla\Database\DatabaseQuery|stringThe DatabaseQuery object or string to union.

glue

stringThe glue by which to join the conditions.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

update

Add a table name to the UPDATE clause of the query.

update(string table) : \Joomla\Database\DatabaseQuery

Note that you must not mix insert, update, delete and select method calls when building a query.

Usage: $query->update('#__foo')->set(...);

since

1.0

Arguments

table

stringA table to update.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

values

Adds a tuple, or array of tuples that would be used as values for an INSERT INTO statement.

values(array|string values) : \Joomla\Database\DatabaseQuery

Usage: $query->values('1,2,3')->values('4,5,6'); $query->values(array('1,2,3', '4,5,6'));

since

1.0

Arguments

values

array|stringA single tuple, or array of tuples.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

where

Add a single condition, or an array of conditions to the WHERE clause of the query.

where(array|string conditions, string glue = 'AND') : \Joomla\Database\DatabaseQuery

Usage: $query->where('a = 1')->where('b = 2'); $query->where(array('a = 1', 'b = 2'));

since

1.0

Arguments

conditions

array|stringA string or array of where conditions.

glue

stringThe glue by which to join the conditions. Defaults to AND. Note that the glue is set on first use and cannot be changed.

Response

\Joomla\Database\DatabaseQueryReturns this object to allow chaining.

year

Used to get a string to extract year from date column.

year(string date) : string

Usage: $query->select($query->year($query->quoteName('dateColumn')));

since

1.0

Arguments

date

stringDate column containing year to be extracted.

Response

stringReturns string to extract year from a date.

Properties

db

The database driver.

since

1.0

Type(s)

\Joomla\Database\DatabaseDriver

sql

The SQL query (if a direct query string was provided).

since

1.0

Type(s)

string

type

The query type.

since

1.0

Type(s)

string

element

The query element for a generic query (type = null).

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

select

The select element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

delete

The delete element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

update

The update element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

insert

The insert element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

from

The from element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

join

The join element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

set

The set element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

where

The where element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

group

The group by element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

having

The having element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

columns

The column list for an INSERT statement.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

values

The values list for an INSERT statement.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

order

The order element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

autoIncrementField

The auto increment insert field element.

since

1.0

Type(s)

object

call

The call element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

exec

The exec element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

union

The union element.

since

1.0

Type(s)

\Joomla\Database\Query\QueryElement

unionAll

The unionAll element.

since

1.5.0

Type(s)

\Joomla\Database\Query\QueryElement