1: <?php
2: /**
3: * CakePHP(tm) : Rapid Development Framework (https://cakephp.org)
4: * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
5: *
6: * Licensed under The MIT License
7: * For full copyright and license information, please see the LICENSE.txt
8: * Redistributions of files must retain the above copyright notice.
9: *
10: * @copyright Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
11: * @link https://cakephp.org CakePHP(tm) Project
12: * @since 3.0.0
13: * @license https://opensource.org/licenses/mit-license.php MIT License
14: */
15: namespace Cake\Database;
16:
17: /**
18: * Represents a database statement. Concrete implementations
19: * can either use PDOStatement or a native driver
20: *
21: * @property-read string $queryString
22: */
23: interface StatementInterface
24: {
25: /**
26: * Used to designate that numeric indexes be returned in a result when calling fetch methods
27: *
28: * @var string
29: */
30: const FETCH_TYPE_NUM = 'num';
31:
32: /**
33: * Used to designate that an associated array be returned in a result when calling fetch methods
34: *
35: * @var string
36: */
37: const FETCH_TYPE_ASSOC = 'assoc';
38:
39: /**
40: * Used to designate that a stdClass object be returned in a result when calling fetch methods
41: *
42: * @var string
43: */
44: const FETCH_TYPE_OBJ = 'obj';
45:
46: /**
47: * Assign a value to a positional or named variable in prepared query. If using
48: * positional variables you need to start with index one, if using named params then
49: * just use the name in any order.
50: *
51: * It is not allowed to combine positional and named variables in the same statement
52: *
53: * ### Examples:
54: *
55: * ```
56: * $statement->bindValue(1, 'a title');
57: * $statement->bindValue('active', true, 'boolean');
58: * $statement->bindValue(5, new \DateTime(), 'date');
59: * ```
60: *
61: * @param string|int $column name or param position to be bound
62: * @param mixed $value The value to bind to variable in query
63: * @param string $type name of configured Type class
64: * @return void
65: */
66: public function bindValue($column, $value, $type = 'string');
67:
68: /**
69: * Closes a cursor in the database, freeing up any resources and memory
70: * allocated to it. In most cases you don't need to call this method, as it is
71: * automatically called after fetching all results from the result set.
72: *
73: * @return void
74: */
75: public function closeCursor();
76:
77: /**
78: * Returns the number of columns this statement's results will contain
79: *
80: * ### Example:
81: *
82: * ```
83: * $statement = $connection->prepare('SELECT id, title from articles');
84: * $statement->execute();
85: * echo $statement->columnCount(); // outputs 2
86: * ```
87: *
88: * @return int
89: */
90: public function columnCount();
91:
92: /**
93: * Returns the error code for the last error that occurred when executing this statement
94: *
95: * @return int|string
96: */
97: public function errorCode();
98:
99: /**
100: * Returns the error information for the last error that occurred when executing
101: * this statement
102: *
103: * @return array
104: */
105: public function errorInfo();
106:
107: /**
108: * Executes the statement by sending the SQL query to the database. It can optionally
109: * take an array or arguments to be bound to the query variables. Please note
110: * that binding parameters from this method will not perform any custom type conversion
111: * as it would normally happen when calling `bindValue`
112: *
113: * @param array|null $params list of values to be bound to query
114: * @return bool true on success, false otherwise
115: */
116: public function execute($params = null);
117:
118: /**
119: * Returns the next row for the result set after executing this statement.
120: * Rows can be fetched to contain columns as names or positions. If no
121: * rows are left in result set, this method will return false
122: *
123: * ### Example:
124: *
125: * ```
126: * $statement = $connection->prepare('SELECT id, title from articles');
127: * $statement->execute();
128: * print_r($statement->fetch('assoc')); // will show ['id' => 1, 'title' => 'a title']
129: * ```
130: *
131: * @param string $type 'num' for positional columns, assoc for named columns
132: * @return array|false Result array containing columns and values or false if no results
133: * are left
134: */
135: public function fetch($type = 'num');
136:
137: /**
138: * Returns an array with all rows resulting from executing this statement
139: *
140: * ### Example:
141: *
142: * ```
143: * $statement = $connection->prepare('SELECT id, title from articles');
144: * $statement->execute();
145: * print_r($statement->fetchAll('assoc')); // will show [0 => ['id' => 1, 'title' => 'a title']]
146: * ```
147: *
148: * @param string $type num for fetching columns as positional keys or assoc for column names as keys
149: * @return array list of all results from database for this statement
150: */
151: public function fetchAll($type = 'num');
152:
153: /**
154: * Returns the number of rows affected by this SQL statement
155: *
156: * ### Example:
157: *
158: * ```
159: * $statement = $connection->prepare('SELECT id, title from articles');
160: * $statement->execute();
161: * print_r($statement->rowCount()); // will show 1
162: * ```
163: *
164: * @return int
165: */
166: public function rowCount();
167:
168: /**
169: * Statements can be passed as argument for count()
170: * to return the number for affected rows from last execution
171: *
172: * @return int
173: */
174: public function count();
175:
176: /**
177: * Binds a set of values to statement object with corresponding type
178: *
179: * @param array $params list of values to be bound
180: * @param array $types list of types to be used, keys should match those in $params
181: * @return void
182: */
183: public function bind($params, $types);
184:
185: /**
186: * Returns the latest primary inserted using this statement
187: *
188: * @param string|null $table table name or sequence to get last insert value from
189: * @param string|null $column the name of the column representing the primary key
190: * @return string
191: */
192: public function lastInsertId($table = null, $column = null);
193: }
194: