Query/src/QueryBuilderInterface.php

534 lines
14 KiB
PHP
Raw Normal View History

2016-10-12 22:12:25 -04:00
<?php declare(strict_types=1);
2012-12-18 16:19:52 -05:00
/**
* Query
*
2016-09-07 13:17:17 -04:00
* SQL Query Builder / Database Abstraction Layer
2012-12-18 16:19:52 -05:00
*
2018-01-19 13:43:19 -05:00
* PHP version 7.1
2016-09-07 13:17:17 -04:00
*
* @package Query
* @author Timothy J. Warren <tim@timshomepage.net>
2018-01-19 13:43:19 -05:00
* @copyright 2012 - 2018 Timothy J. Warren
2016-09-07 13:17:17 -04:00
* @license http://www.opensource.org/licenses/mit-license.html MIT License
* @link https://git.timshomepage.net/aviat4ion/Query
2012-12-18 16:19:52 -05:00
*/
2014-04-02 17:08:50 -04:00
namespace Query;
2016-10-12 22:12:25 -04:00
use PDOStatement;
2012-12-18 16:19:52 -05:00
/**
* Interface defining the Query Builder class
*
* @package Query
2015-11-10 20:58:32 -05:00
* @subpackage QueryBuilder
2012-12-18 16:19:52 -05:00
*/
2015-11-10 10:12:23 -05:00
interface QueryBuilderInterface {
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Select Queries
// --------------------------------------------------------------------------
/**
* Specifies rows to select in a query
*
* @param string $fields
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function select(string $fields): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Selects the maximum value of a field from a query
*
* @param string $field
2014-04-23 16:27:43 -04:00
* @param string|bool $as
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function selectMax(string $field, $as=FALSE): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Selects the minimum value of a field from a query
*
* @param string $field
2014-04-23 16:27:43 -04:00
* @param string|bool $as
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function selectMin(string $field, $as=FALSE): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Selects the average value of a field from a query
*
* @param string $field
2014-04-23 16:27:43 -04:00
* @param string|bool $as
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function selectAvg(string $field, $as=FALSE): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Selects the sum of a field from a query
*
* @param string $field
2014-04-23 16:27:43 -04:00
* @param string|bool $as
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function selectSum(string $field, $as=FALSE): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
2016-10-13 21:55:23 -04:00
// --------------------------------------------------------------------------q
2012-12-18 16:19:52 -05:00
/**
* Adds the 'distinct' keyword to a query
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function distinct(): QueryBuilderInterface;
2014-02-04 20:59:30 -05:00
// --------------------------------------------------------------------------
2014-02-04 20:59:30 -05:00
/**
* Shows the query plan for the query
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2014-02-04 20:59:30 -05:00
*/
2016-10-12 22:12:25 -04:00
public function explain(): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Specify the database table to select from
*
* @param string $tblname
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function from($tblname): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! 'Like' methods
// --------------------------------------------------------------------------
/**
* Creates a Like clause in the sql statement
*
* @param string $field
* @param mixed $val
* @param string $pos
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function like($field, $val, $pos='both'): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Generates an OR Like clause
*
* @param string $field
* @param mixed $val
* @param string $pos
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orLike($field, $val, $pos='both'): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Generates a NOT LIKE clause
*
* @param string $field
* @param mixed $val
* @param string $pos
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function notLike($field, $val, $pos='both'): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Generates a OR NOT LIKE clause
*
* @param string $field
* @param mixed $val
* @param string $pos
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orNotLike($field, $val, $pos='both'): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Having methods
// --------------------------------------------------------------------------
/**
* Generates a 'Having' clause
*
* @param mixed $key
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function having($key, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Generates a 'Having' clause prefixed with 'OR'
*
* @param mixed $key
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orHaving($key, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! '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
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function where($key, $val=[], $escape = NULL): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Where clause prefixed with "OR"
*
* @param string $key
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orWhere($key, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Where clause with 'IN' statement
*
* @param mixed $field
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function whereIn($field, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Where in statement prefixed with "or"
*
* @param string $field
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orWhereIn($field, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* WHERE NOT IN (FOO) clause
*
* @param string $field
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function whereNotIn($field, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* OR WHERE NOT IN (FOO) clause
*
* @param string $field
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orWhereNotIn($field, $val=[]): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Other Query Modifier methods
// --------------------------------------------------------------------------
/**
* Sets values for inserts / updates / deletes
*
* @param mixed $key
* @param mixed $val
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function set($key, $val = NULL): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Creates a join phrase in a compiled query
*
* @param string $table
* @param string $condition
* @param string $type
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function join($table, $condition, $type=''): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Group the results by the selected field(s)
*
* @param mixed $field
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function groupBy($field): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Order the results by the selected field(s)
*
* @param string $field
* @param string $type
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orderBy($field, $type=""): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Set a limit on the current sql statement
*
* @param int $limit
2014-04-23 16:27:43 -04:00
* @param int|bool $offset
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function limit($limit, $offset=FALSE): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Query Grouping Methods
// --------------------------------------------------------------------------
/**
* Adds a paren to the current query for query grouping
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function groupStart(): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
2016-09-07 13:10:03 -04:00
/**
* Adds a paren to the current query for query grouping,
* prefixed with 'NOT'
2016-10-12 22:12:25 -04:00
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
*/
2016-10-13 21:55:23 -04:00
public function notGroupStart(): QueryBuilderInterface;
2016-09-07 13:10:03 -04:00
// --------------------------------------------------------------------------
2012-12-18 16:19:52 -05:00
/**
* Adds a paren to the current query for query grouping,
* prefixed with 'OR'
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orGroupStart(): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Adds a paren to the current query for query grouping,
* prefixed with 'OR NOT'
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function orNotGroupStart(): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Ends a query group
*
2016-09-07 13:10:03 -04:00
* @return QueryBuilderInterface
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function groupEnd(): QueryBuilderInterface;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Query execution methods
// --------------------------------------------------------------------------
/**
* Select and retrieve all records from the current table, and/or
* execute current compiled query
*
2016-09-07 14:22:52 -04:00
* @param string $table
2014-04-23 16:27:43 -04:00
* @param int|bool $limit
* @param int|bool $offset
2016-10-12 22:12:25 -04:00
* @return PDOStatement
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function get($table='', $limit=FALSE, $offset=FALSE): PDOStatement;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
2016-10-12 22:12:25 -04:00
* Convenience method for get() with a where clause
2012-12-18 16:19:52 -05:00
*
* @param string $table
* @param array $where
2014-04-23 16:27:43 -04:00
* @param int|bool $limit
* @param int|bool $offset
2016-10-12 22:12:25 -04:00
* @return PDOStatement
2012-12-18 16:19:52 -05:00
*/
2016-10-13 21:55:23 -04:00
public function getWhere($table, $where=[], $limit=FALSE, $offset=FALSE): PDOStatement;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
2014-04-23 16:27:43 -04:00
* Retrieve the number of rows in the selected table
2012-12-18 16:19:52 -05:00
*
* @param string $table
* @return int
*/
2016-10-13 21:55:23 -04:00
public function countAll($table): int;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Retrieve the number of results for the generated query - used
* in place of the get() method
*
* @param string $table
2016-09-07 13:10:03 -04:00
* @param bool $reset - Whether to keep the query after counting the results
2012-12-18 16:19:52 -05:00
* @return int
*/
2016-10-13 21:55:23 -04:00
public function countAllResults(string $table='', bool $reset=TRUE): int;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Creates an insert clause, and executes it
*
* @param string $table
* @param mixed $data
2016-10-12 22:12:25 -04:00
* @return PDOStatement
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function insert($table, $data=[]): PDOStatement;
2014-03-28 15:16:39 -04:00
// --------------------------------------------------------------------------
/**
* Creates and executes a batch insertion query
*
* @param string $table
* @param array $data
2014-04-03 15:05:18 -04:00
* @return \PDOStatement|null
2014-03-28 15:16:39 -04:00
*/
2016-10-13 21:55:23 -04:00
public function insertBatch($table, $data=[]);
2016-09-07 13:10:03 -04:00
// --------------------------------------------------------------------------
/**
* Insertion with automatic overwrite, rather than attempted duplication
*
* @param string $table
* @param array $data
* @return \PDOStatement|null
*/
public function replace($table, $data=[]);
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Creates an update clause, and executes it
*
* @param string $table
* @param mixed $data
2016-10-12 22:12:25 -04:00
* @return PDOStatement
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function update($table, $data=[]): PDOStatement;
2016-09-07 13:10:03 -04:00
// --------------------------------------------------------------------------
/**
* Creates a batch update, and executes it.
* Returns the number of affected rows
*
* @param string $table
* @param array|object $data
* @param string $where
2016-09-07 17:39:19 -04:00
* @return int|null
2016-09-07 13:10:03 -04:00
*/
2016-10-13 21:55:23 -04:00
public function updateBatch($table, $data, $where);
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
/**
* Deletes data from a table
*
* @param string $table
* @param mixed $where
2016-10-12 22:12:25 -04:00
* @return PDOStatement
2012-12-18 16:19:52 -05:00
*/
2016-10-12 22:12:25 -04:00
public function delete($table, $where=''): PDOStatement;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! SQL Returning Methods
// --------------------------------------------------------------------------
/**
* Returns the generated 'select' sql query
*
* @param string $table
* @param bool $reset
* @return string
*/
2016-10-13 21:55:23 -04:00
public function getCompiledSelect(string $table='', bool $reset=TRUE): string;
2012-12-18 16:19:52 -05:00
/**
* Returns the generated 'insert' sql query
*
* @param string $table
* @param bool $reset
* @return string
*/
2016-10-13 21:55:23 -04:00
public function getCompiledInsert(string $table, bool $reset=TRUE): string;
2012-12-18 16:19:52 -05:00
/**
* Returns the generated 'update' sql query
*
* @param string $table
* @param bool $reset
* @return string
*/
2016-10-13 21:55:23 -04:00
public function getCompiledUpdate(string $table='', bool $reset=TRUE): string;
2012-12-18 16:19:52 -05:00
/**
* Returns the generated 'delete' sql query
*
* @param string $table
* @param bool $reset
* @return string
*/
2016-10-13 21:55:23 -04:00
public function getCompiledDelete(string $table='', bool $reset=TRUE): string;
2012-12-18 16:19:52 -05:00
// --------------------------------------------------------------------------
// ! Miscellaneous Methods
// --------------------------------------------------------------------------
/**
* Clear out the class variables, so the next query can be run
*
* @return void
*/
2016-10-13 21:55:23 -04:00
public function resetQuery();
2012-12-18 16:19:52 -05:00
}
2016-09-07 13:10:03 -04:00
// End of QueryBuilderInterface.php