539 lines
13 KiB
PHP
539 lines
13 KiB
PHP
<?php
|
|
/**
|
|
* Query
|
|
*
|
|
* Free Query Builder / Database Abstraction Layer
|
|
*
|
|
* @package Query
|
|
* @author Timothy J. Warren
|
|
* @copyright Copyright (c) 2012 - 2015
|
|
* @link https://github.com/aviat4ion/Query
|
|
* @license http://philsturgeon.co.uk/code/dbad-license
|
|
*/
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
namespace Query;
|
|
|
|
/**
|
|
* Interface defining the Query Builder class
|
|
*
|
|
* @package Query
|
|
* @subpackage QueryBuilder
|
|
*/
|
|
interface QueryBuilderInterface {
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Select Queries
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Specifies rows to select in a query
|
|
*
|
|
* @param string $fields
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function select($fields);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Selects the maximum value of a field from a query
|
|
*
|
|
* @param string $field
|
|
* @param string|bool $as
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function select_max($field, $as=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Selects the minimum value of a field from a query
|
|
*
|
|
* @param string $field
|
|
* @param string|bool $as
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function select_min($field, $as=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Selects the average value of a field from a query
|
|
*
|
|
* @param string $field
|
|
* @param string|bool $as
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function select_avg($field, $as=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Selects the sum of a field from a query
|
|
*
|
|
* @param string $field
|
|
* @param string|bool $as
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function select_sum($field, $as=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Adds the 'distinct' keyword to a query
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function distinct();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Shows the query plan for the query
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function explain();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Specify the database table to select from
|
|
*
|
|
* @param string $tblname
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function from($tblname);
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! 'Like' methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates a Like clause in the sql statement
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @param string $pos
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function like($field, $val, $pos='both');
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Generates an OR Like clause
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @param string $pos
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_like($field, $val, $pos='both');
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Generates a NOT LIKE clause
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @param string $pos
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function not_like($field, $val, $pos='both');
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Generates a OR NOT LIKE clause
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @param string $pos
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_not_like($field, $val, $pos='both');
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Having methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Generates a 'Having' clause
|
|
*
|
|
* @param mixed $key
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function having($key, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Generates a 'Having' clause prefixed with 'OR'
|
|
*
|
|
* @param mixed $key
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_having($key, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! 'Where' methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Specify condition(s) in the where clause of a query
|
|
* Note: this function works with key / value, or a
|
|
* passed array with key / value pairs
|
|
*
|
|
* @param mixed $key
|
|
* @param mixed $val
|
|
* @param bool $escape
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function where($key, $val=[], $escape = NULL);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Where clause prefixed with "OR"
|
|
*
|
|
* @param string $key
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_where($key, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Where clause with 'IN' statement
|
|
*
|
|
* @param mixed $field
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function where_in($field, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Where in statement prefixed with "or"
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_where_in($field, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* WHERE NOT IN (FOO) clause
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function where_not_in($field, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* OR WHERE NOT IN (FOO) clause
|
|
*
|
|
* @param string $field
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_where_not_in($field, $val=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Other Query Modifier methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Sets values for inserts / updates / deletes
|
|
*
|
|
* @param mixed $key
|
|
* @param mixed $val
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function set($key, $val = NULL);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates a join phrase in a compiled query
|
|
*
|
|
* @param string $table
|
|
* @param string $condition
|
|
* @param string $type
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function join($table, $condition, $type='');
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Group the results by the selected field(s)
|
|
*
|
|
* @param mixed $field
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function group_by($field);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Order the results by the selected field(s)
|
|
*
|
|
* @param string $field
|
|
* @param string $type
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function order_by($field, $type="");
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Set a limit on the current sql statement
|
|
*
|
|
* @param int $limit
|
|
* @param int|bool $offset
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function limit($limit, $offset=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Query Grouping Methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Adds a paren to the current query for query grouping
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function group_start();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Adds a paren to the current query for query grouping,
|
|
* prefixed with 'NOT'
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function not_group_start();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Adds a paren to the current query for query grouping,
|
|
* prefixed with 'OR'
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_group_start();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Adds a paren to the current query for query grouping,
|
|
* prefixed with 'OR NOT'
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function or_not_group_start();
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Ends a query group
|
|
*
|
|
* @return QueryBuilderInterface
|
|
*/
|
|
public function group_end();
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Query execution methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Select and retrieve all records from the current table, and/or
|
|
* execute current compiled query
|
|
*
|
|
* @param $table
|
|
* @param int|bool $limit
|
|
* @param int|bool $offset
|
|
* @return \PDOStatement
|
|
*/
|
|
public function get($table='', $limit=FALSE, $offset=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Convience method for get() with a where clause
|
|
*
|
|
* @param string $table
|
|
* @param array $where
|
|
* @param int|bool $limit
|
|
* @param int|bool $offset
|
|
* @return \PDOStatement
|
|
*/
|
|
public function get_where($table, $where=[], $limit=FALSE, $offset=FALSE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Retrieve the number of rows in the selected table
|
|
*
|
|
* @param string $table
|
|
* @return int
|
|
*/
|
|
public function count_all($table);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Retrieve the number of results for the generated query - used
|
|
* in place of the get() method
|
|
*
|
|
* @param string $table
|
|
* @param bool $reset - Whether to keep the query after counting the results
|
|
* @return int
|
|
*/
|
|
public function count_all_results($table='', $reset=TRUE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates an insert clause, and executes it
|
|
*
|
|
* @param string $table
|
|
* @param mixed $data
|
|
* @return \PDOStatement
|
|
*/
|
|
public function insert($table, $data=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates and executes a batch insertion query
|
|
*
|
|
* @param string $table
|
|
* @param array $data
|
|
* @return \PDOStatement|null
|
|
*/
|
|
public function insert_batch($table, $data=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Insertion with automatic overwrite, rather than attempted duplication
|
|
*
|
|
* @param string $table
|
|
* @param array $data
|
|
* @return \PDOStatement|null
|
|
*/
|
|
public function replace($table, $data=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates an update clause, and executes it
|
|
*
|
|
* @param string $table
|
|
* @param mixed $data
|
|
* @return \PDOStatement
|
|
*/
|
|
public function update($table, $data=[]);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Creates a batch update, and executes it.
|
|
* Returns the number of affected rows
|
|
*
|
|
* @param string $table
|
|
* @param array|object $data
|
|
* @param string $where
|
|
* @return int
|
|
*/
|
|
public function update_batch($table, $data, $where);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Deletes data from a table
|
|
*
|
|
* @param string $table
|
|
* @param mixed $where
|
|
* @return \PDOStatement
|
|
*/
|
|
public function delete($table, $where='');
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! SQL Returning Methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Returns the generated 'select' sql query
|
|
*
|
|
* @param string $table
|
|
* @param bool $reset
|
|
* @return string
|
|
*/
|
|
public function get_compiled_select($table='', $reset=TRUE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Returns the generated 'insert' sql query
|
|
*
|
|
* @param string $table
|
|
* @param bool $reset
|
|
* @return string
|
|
*/
|
|
public function get_compiled_insert($table, $reset=TRUE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Returns the generated 'update' sql query
|
|
*
|
|
* @param string $table
|
|
* @param bool $reset
|
|
* @return string
|
|
*/
|
|
public function get_compiled_update($table='', $reset=TRUE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Returns the generated 'delete' sql query
|
|
*
|
|
* @param string $table
|
|
* @param bool $reset
|
|
* @return string
|
|
*/
|
|
public function get_compiled_delete($table="", $reset=TRUE);
|
|
|
|
// --------------------------------------------------------------------------
|
|
// ! Miscellaneous Methods
|
|
// --------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Clear out the class variables, so the next query can be run
|
|
*
|
|
* @return void
|
|
*/
|
|
public function reset_query();
|
|
}
|
|
|
|
// End of QueryBuilderInterface.php
|