interface QueryInterface (View source)

Methods

string
__toString()

Magic function to convert the query to a string.

QueryElement|mixed
get(string $clause)

Get clause value.

call(mixed $columns)

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

columns(mixed $columns)

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

string
dateFormat()

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

delete(string $table = null)

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

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

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

exec(mixed $columns)

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

from(mixed $tables, string $subQueryAlias = null)

Add a table to the FROM clause of the query.

string
expression(string $name)

expression

group(mixed $columns)

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

having($conditions)

A conditions to the HAVING clause of the query.

orHaving(mixed|callable $conditions)

Add a single condition, or an array of conditions to the HAVING clause and wrap with OR elements.

innerJoin(array|string $table, array|string $condition = array())

Add an INNER JOIN clause to the query.

insert(mixed $table, boolean $incrementField = false)

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

join(string $type, string $table, string|array $conditions = array())

Add a JOIN clause to the query.

leftJoin(array|string $table, array|string $condition = array())

Add a LEFT JOIN clause to the query.

string
nullDate(boolean $quoted = true)

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

order(mixed $columns)

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

limit(integer $limit = null, integer $offset = null)

Sets the offset and limit for the result set, if the database driver supports it.

outerJoin(array|string $table, array|string $condition = array())

Add an OUTER JOIN clause to the query.

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

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

mixed
quoteName(mixed $name)

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

rightJoin(array|string $table, array|string $condition = array())

Add a RIGHT JOIN clause to the query.

select(mixed $columns)

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

set(mixed $conditions, string $glue = ',')

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

setQuery(mixed $sql)

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

update(string $table)

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

values(string $values)

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

where($conditions)

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

orWhere(mixed|callable $conditions)

Add a single condition, or an array of conditions to the WHERE clause and wrap with OR elements.

mixed
union(mixed $query, boolean $distinct = false)

Add a query to UNION with the current query.

mixed
unionDistinct(mixed $query)

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

mixed
unionAll(mixed $query)

Add a query to UNION ALL with the current query.

string
format($format)

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

Details

at line line 21
string __toString()

Magic function to convert the query to a string.

Return Value

string The completed query.

at line line 30
QueryElement|mixed get(string $clause)

Get clause value.

Parameters

string $clause Get query clause.

Return Value

QueryElement|mixed

at line line 48
QueryInterface call(mixed $columns)

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

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'));

Parameters

mixed $columns A string or an array of field names.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 59
QueryInterface columns(mixed $columns)

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

Parameters

mixed $columns A column name, or array of column names.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 72
string dateFormat()

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

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.

Return Value

string The format string.

Exceptions

RuntimeException

at line line 88
QueryInterface delete(string $table = null)

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

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

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

Parameters

string $table The name of the table to delete from.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 106
string escape(string $text, boolean $extra = false)

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

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.

Parameters

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

Return Value

string The escaped string.

Exceptions

RuntimeException if the internal db property is not a valid object.

at line line 124
QueryInterface exec(mixed $columns)

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

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'));

Parameters

mixed $columns A string or an array of field names.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 145
QueryInterface from(mixed $tables, string $subQueryAlias = null)

Add a table to the FROM clause of the query.

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

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

Parameters

mixed $tables A string or array of table names. This can be a JDatabaseQuery object (or a child of it) when used as a subquery in FROM clause along with a value for $subQueryAlias.
string $subQueryAlias Alias used when $tables is a JDatabaseQuery.

Return Value

QueryInterface Returns this object to allow chaining.

Exceptions

InvalidArgumentException
RuntimeException

at line line 154
string expression(string $name)

expression

Parameters

string $name

Return Value

string

at line line 168
QueryInterface group(mixed $columns)

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

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

Parameters

mixed $columns A string or array of ordering columns.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 183
QueryInterface having($conditions)

A conditions to the HAVING clause of the query.

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

Parameters

$conditions

Return Value

QueryInterface Returns this object to allow chaining.

at line line 205
QueryInterface orHaving(mixed|callable $conditions)

Add a single condition, or an array of conditions to the HAVING clause and wrap with OR elements.

Usage: $query->orHaving(array('a < 5', 'b > 6')); $query->orHaving('a < 5', 'b > 6'); $query->orHaving(function ($query) { $query->having('a < 5')->having('b > 6'); });

Result: HAVING ... AND (a < 5 OR b > 6)

Parameters

mixed|callable $conditions A string, array of where conditions or callback to support logic.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 220
QueryInterface innerJoin(array|string $table, array|string $condition = array())

Add an INNER JOIN clause to the query.

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

Parameters

array|string $table The table name with alias.
array|string $condition The join condition.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 239
QueryInterface insert(mixed $table, boolean $incrementField = false)

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

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'));

Parameters

mixed $table The name of the table to insert data into.
boolean $incrementField The name of the field to auto increment.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 255
QueryInterface join(string $type, string $table, string|array $conditions = array())

Add a JOIN clause to the query.

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

Parameters

string $type The type of join. This string is prepended to the JOIN keyword.
string $table The table name with alias.
string|array $conditions A string or array of conditions.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 270
QueryInterface leftJoin(array|string $table, array|string $condition = array())

Add a LEFT JOIN clause to the query.

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

Parameters

array|string $table The table name with alias.
array|string $condition The join condition.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 288
string nullDate(boolean $quoted = true)

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

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

Parameters

boolean $quoted Optionally wraps the null date in database quotes (true by default).

Return Value

string Null or zero representation of a timestamp.

Exceptions

RuntimeException

at line line 303
QueryInterface order(mixed $columns)

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

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

Parameters

mixed $columns A string or array of ordering columns.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 319
QueryInterface limit(integer $limit = null, integer $offset = null)

Sets the offset and limit for the result set, if the database driver supports it.

Usage: $query->setLimit(100, 0); (retrieve 100 rows, starting at first record) $query->setLimit(50, 50); (retrieve 50 rows, starting at 50th record)

Parameters

integer $limit The limit for the result set
integer $offset The offset for the result set

Return Value

QueryInterface Returns this object to allow chaining.

at line line 334
QueryInterface outerJoin(array|string $table, array|string $condition = array())

Add an OUTER JOIN clause to the query.

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

Parameters

array|string $table The table name with alias.
array|string $condition The join condition.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 357
string quote(mixed $text, boolean $escape = true)

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

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'));

Parameters

mixed $text A string or an array of strings to quote.
boolean $escape True to escape the string, false to leave it unchanged.

Return Value

string The quoted input string.

Exceptions

RuntimeException if the internal db property is not a valid object.

at line line 380
mixed quoteName(mixed $name)

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

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');

Parameters

mixed $name The identifier name to wrap in quotes, or an array of identifier names to wrap in quotes. Each type supports dot-notation name.

Return Value

mixed The quote wrapped name, same type of $name.

Exceptions

RuntimeException if the internal db property is not a valid object.

at line line 395
QueryInterface rightJoin(array|string $table, array|string $condition = array())

Add a RIGHT JOIN clause to the query.

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

Parameters

array|string $table The table name with alias.
array|string $condition The join condition.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 413
QueryInterface select(mixed $columns)

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

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'));

Parameters

mixed $columns A string or an array of field names.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 430
QueryInterface set(mixed $conditions, string $glue = ',')

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

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

Parameters

mixed $conditions A string or array of string conditions.
string $glue The glue by which to join the condition strings. Defaults to ,. Note that the glue is set on first use and cannot be changed.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 445
QueryInterface setQuery(mixed $sql)

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

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

Parameters

mixed $sql A SQL query string or DatabaseQuery object

Return Value

QueryInterface Returns this object to allow chaining.

at line line 461
QueryInterface update(string $table)

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

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

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

Parameters

string $table A table to update.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 476
QueryInterface values(string $values)

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

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

Parameters

string $values A single tuple, or array of tuples.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 492
QueryInterface where($conditions)

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

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

Parameters

$conditions

Return Value

QueryInterface Returns this object to allow chaining.

at line line 514
QueryInterface orWhere(mixed|callable $conditions)

Add a single condition, or an array of conditions to the WHERE clause and wrap with OR elements.

Usage: $query->orWhere(array('a < 5', 'b > 6')); $query->orWhere('a < 5', 'b > 6'); $query->orWhere(function ($query) { $query->where('a < 5')->where('b > 6'); });

Result: WHERE ... AND (a < 5 OR b > 6)

Parameters

mixed|callable $conditions A string, array of where conditions or callback to support logic.

Return Value

QueryInterface Returns this object to allow chaining.

at line line 532
mixed union(mixed $query, boolean $distinct = false)

Add a query to UNION with the current query.

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'))

Parameters

mixed $query The Query object or string to union.
boolean $distinct True to only return distinct rows from the union.

Return Value

mixed The Query object on success or boolean false on failure.

at line line 546
mixed unionDistinct(mixed $query)

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

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

Parameters

mixed $query The Query object or string to union.

Return Value

mixed The Query object on success or boolean false on failure.

at line line 564
mixed unionAll(mixed $query)

Add a query to UNION ALL with the current query.

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

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

Parameters

mixed $query The Query object or string to union.

Return Value

mixed The Query object on success or boolean false on failure.

See also

union

at line line 614
string format($format)

Find and replace sprintf-like tokens in a 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.

Parameters

$format

Return Value

string Returns a string produced according to the formatting string.