Db_Query_Interface Class
Interface that an adapter must support to implement the Db class.
Constructor
Db_Query_Interface
-
$db -
$type -
$clauses -
$parameters
Parameters:
-
$dbDb_InterfaceThe database connection
-
$typeIntegerThe type of the query. See class constants beginning with TYPE_ .
-
$clausesArrayThe clauses to add to the query right away
-
$parametersArrayThe parameters to add to the query right away (to be bound when executing)
Item Index
Methods
__toString
()
Just builds the query and returns the string that would be sent to $pdo->prepare(). If this results in an exception, the string will contain the exception instead.
andWhere
-
$criteria -
[$or_criteria=null]
Adds to the WHERE clause, like this: "... AND (x OR y OR z)", where x, y and z are the arguments to this function.
Parameters:
-
$criteriaDb_Expression | String -
[$or_criteria=null]Db_Expression | String optional
begin
-
[$lock_type]
Begins a transaction right before executing this query. The reason this method is part of the query class is because you often need the "where" clauses to figure out which database to send it to, if sharding is being used.
Parameters:
-
[$lock_type]String optionalThe type of lock in the transaction
bind
-
[$parameters=array()]
You can bind more parameters to the query manually using this method. These parameters are bound in the order they are passed to the query. Here is an example:
Parameters:
-
[$parameters=array()]Array optionalAn associative array of parameters. The query should contain :name, where :name is a placeholder for the parameter under the key "name". The parameters will be properly escaped. You can also have the query contain question marks (the binding is done using PDO), but then the order of the parameters matters.
Example:
$result = $db->select('*', 'foo')
->where(array('a' => $a))
->andWhere('a = :moo')
->bind(array('moo' => $moo))
->execute();build
()
Builds the query from the clauses
commit
()
chainable
Commits a transaction right after executing this query. The reason this method is part of the query class is because you often need the "where" clauses to figure out which database to send it to, if sharding is being used.
excecute
-
[$prepare_statement=false] -
[$shards]
Executes a query against the database and returns the result set.
Parameters:
-
[$prepare_statement=false]Boolean optionalDefaults to false. If true, a PDO statement will be prepared from the query before it is executed. It is also saved for future invocations to use. Do this only if the statement will be executed many times with different parameters. Basically you would use "->bind(...)" between invocations of "->execute()".
-
[$shards]Array | String optionalYou can pass a shard name here, or an array where the keys are shard names and the values are the query to execute. This will bypass the usual sharding algorithm.
Returns:
The Db_Result object containing the PDO statement that resulted from the query.
fetchAll
-
$fetch_style=PDO::FETCH_BOTH -
$column_index=null -
$ctor_args=null
Fetches an array of database rows matching the query. If this exact query has already been executed and fetchAll() has been called on the Db_Result, and the return value was cached by the Db_Result, then that cached value is returned, unless $this->ignoreCache is true. Otherwise, the query is executed and fetchAll() is called on the result.
Parameters:
-
$fetch_style=PDO::FETCH_BOTHEnum -
$column_index=nullEnum -
$ctor_args=nullArray
Returns:
fetchDbRows
-
[$class_name='Db_Row'] -
[$fields_prefix='']
Fetches an array of Db_Row objects. If this exact query has already been executed and fetchAll() has been called on the Db_Result, and the return value was cached by the Db_Result, then that cached value is returned, unless $this->ignoreCache is true. Otherwise, the query is executed and fetchDbRows() is called on the result.
Parameters:
-
[$class_name='Db_Row']String optionalThe name of the class to instantiate and fill objects from. Must extend Db_Row.
-
[$fields_prefix='']String optionalThis is the prefix, if any, to strip out when fetching the rows.
Returns:
getSQL
-
[$callback=null]
Gets the SQL that would be executed with the execute() method.
Parameters:
-
[$callback=null]Callable optionalIf not set, this function returns the generated SQL string. If it is set, this function calls $callback, passing it the SQL string, and then returns $this, for chainable interface.
Returns:
Depends on whether $callback is set or not.
groupBy
-
$expression
Adds a GROUP BY clause to a query
Parameters:
-
$expressionDb_Expression | String
having
-
$criteria
Adds a HAVING clause to a query
Parameters:
-
$criteriaDb_Expression | ArrayAn associative array of expression => value pairs. The values are automatically escaped using PDO placeholders. Or, this could be a Db_Expression object.
join
-
$table -
$condition -
[$join_type='INNER']
Joins another table to use in the query
Parameters:
-
$tableStringThe name of the table. May also be "name AS alias".
-
$conditionDb_Expression | Array | StringThe condition to join on. Thus, JOIN table ON ($condition)
-
[$join_type='INNER']String optionalThe string to prepend to JOIN, such as 'INNER', 'LEFT OUTER', etc.
limit
-
$limit -
[$offset=null]
Adds optional LIMIT and OFFSET clauses to the query
Parameters:
-
$limitIntegerA non-negative integer showing how many rows to return
-
[$offset=null]Integer optionalOptional. A non-negative integer showing what row to start the result set with.
onDuplicateKeyUpdate
-
$updates
Adds an ON DUPLICATE KEY UPDATE clause to an INSERT statement. Use only with MySQL.
Parameters:
-
$updatesArrayAn associative array of column => value pairs. The values are automatically escaped using PDO placeholders.
options
-
$options
This function provides an easy way to provide additional clauses to the query.
Parameters:
-
$optionsArrayAn associative array of key => value pairs, where the key is the name of the method to call, and the value is the array of arguments. If the value is not an array, it is wrapped in one.
orderBy
-
$expression -
[$ascending=true]
Adds an ORDER BY clause to the query
Parameters:
-
$expressionDb_Expression | StringA string or Db_Expression with the expression to order the results by.
-
[$ascending=true]Boolean optionalIf false, sorts results as ascending, otherwise descending.
orWhere
-
$criteria -
[$and_criteria=null]
Adds to the WHERE clause, like this: "... OR (x AND y AND z)", where x, y and z are the arguments to this function.
Parameters:
-
$criteriaDb_Expression | String -
[$and_criteria=null]Db_Expression | String optional
replace
-
[$replacements=array()]
Merges additional replacements over the default replacement array, which is currently just
Parameters:
-
[$replacements=array()]Array optionalThis must be an array.
Example:
array (
'{$prefix}' => $conn['prefix']
)The replacements array is used to replace strings in the SQL before using it. Watch out, because it may replace more than you want!
rollback
()
chainable
Rolls back a transaction right before executing this query. The reason this method is part of the query class is because you often need the "where" clauses to figure out which database to send it to, if sharding is being used.
select
-
$fields -
[$tables=''] -
[$reuse=true]
Creates a query to select fields from one or more tables.
Parameters:
-
$fieldsString | ArrayThe fields as strings, or array of alias=>field
-
[$tables='']String | Array optionalThe tables as strings, or array of alias=>table
-
[$reuse=true]Boolean optionalIf $tables is an array, and select() has already been called with the exact table name and alias as one of the tables in that array, then this table is not appended to the tables list if $reuse is true. Otherwise it is. $reuse is true by default. This is really just for using in your hooks.
set
-
$updates
Adds a SET clause to an UPDATE statement
Parameters:
-
$updatesArrayAn associative array of column => value pairs. The values are automatically escaped using PDO placeholders.
where
-
$criteria
Adds a WHERE clause to a query
Parameters:
-
$criteriaDb_Expression | ArrayAn associative array of expression => value pairs. The values are automatically escaped using PDO placeholders. Or, this could be a Db_Expression object.