1<?php
2/**
3 *
4 * This file is part of Aura for PHP.
5 *
6 * @license https://opensource.org/licenses/MIT MIT
7 *
8 */
9namespace Aura\Sql;
10
11use Aura\Sql\Parser\ParserInterface;
12use Aura\Sql\Profiler\ProfilerInterface;
13use PDO;
14
15/**
16 *
17 * An interface to the Aura.Sql extended PDO object.
18 *
19 * @package Aura.Sql
20 *
21 */
22interface ExtendedPdoInterface extends PdoInterface
23{
24    /**
25     *
26     * Connects to the database.
27     *
28     */
29    public function connect();
30
31    /**
32     *
33     * Disconnects from the database.
34     *
35     */
36    public function disconnect();
37
38    /**
39     *
40     * Performs a statement and returns the number of affected rows.
41     *
42     * @param string $statement The SQL statement to prepare and execute.
43     *
44     * @param array $values Values to bind to the query.
45     *
46     * @return int
47     *
48     */
49    public function fetchAffected($statement, array $values = []);
50
51    /**
52     *
53     * Fetches a sequential array of rows from the database; the rows
54     * are represented as associative arrays.
55     *
56     * @param string $statement The SQL statement to prepare and execute.
57     *
58     * @param array $values Values to bind to the query.
59     *
60     * @return array
61     *
62     */
63    public function fetchAll($statement, array $values = []);
64
65    /**
66     *
67     * Fetches an associative array of rows from the database; the rows
68     * are represented as associative arrays. The array of rows is keyed
69     * on the first column of each row.
70     *
71     * N.b.: if multiple rows have the same first column value, the last
72     * row with that value will override earlier rows.
73     *
74     * @param string $statement The SQL statement to prepare and execute.
75     *
76     * @param array $values Values to bind to the query.
77     *
78     * @return array
79     *
80     */
81    public function fetchAssoc($statement, array $values = []);
82
83    /**
84     *
85     * Fetches the first column of rows as a sequential array.
86     *
87     * @param string $statement The SQL statement to prepare and execute.
88     *
89     * @param array $values Values to bind to the query.
90     *
91     * @return array
92     *
93     */
94    public function fetchCol($statement, array $values = []);
95
96    /**
97     *
98     * Fetches multiple from the database as an associative array.
99     * The first column will be the index
100     *
101     * @param string $statement The SQL statement to prepare and execute.
102     *
103     * @param array $values Values to bind to the query.
104     *
105     * @param int $style a fetch style defaults to PDO::FETCH_COLUMN for single
106     * values, use PDO::FETCH_NAMED when fetching a multiple columns
107     *
108     * @return array
109     *
110     */
111    public function fetchGroup(
112        $statement,
113        array $values = [],
114        $style = PDO::FETCH_COLUMN
115    );
116
117    /**
118     *
119     * Fetches one row from the database as an object, mapping column values
120     * to object properties.
121     *
122     * Warning: PDO "injects property-values BEFORE invoking the constructor -
123     * in other words, if your class initializes property-values to defaults
124     * in the constructor, you will be overwriting the values injected by
125     * fetchObject() !"
126     * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
127     *
128     * @param string $statement The SQL statement to prepare and execute.
129     *
130     * @param array $values Values to bind to the query.
131     *
132     * @param string $class The name of the class to create.
133     *
134     * @param array $args Arguments to pass to the object constructor.
135     *
136     * @return object
137     *
138     */
139    public function fetchObject(
140        $statement,
141        array $values = [],
142        $class = 'stdClass',
143        array $args = []
144    );
145
146    /**
147     *
148     * Fetches a sequential array of rows from the database; the rows
149     * are represented as objects, where the column values are mapped to
150     * object properties.
151     *
152     * Warning: PDO "injects property-values BEFORE invoking the constructor -
153     * in other words, if your class initializes property-values to defaults
154     * in the constructor, you will be overwriting the values injected by
155     * fetchObject() !"
156     * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
157     *
158     * @param string $statement The SQL statement to prepare and execute.
159     *
160     * @param array $values Values to bind to the query.
161     *
162     * @param string $class The name of the class to create from each
163     * row.
164     *
165     * @param array $args Arguments to pass to each object constructor.
166     *
167     * @return array
168     *
169     */
170    public function fetchObjects(
171        $statement,
172        array $values = [],
173        $class = 'stdClass',
174        array $args = []
175    );
176
177    /**
178     *
179     * Fetches one row from the database as an associative array.
180     *
181     * @param string $statement The SQL statement to prepare and execute.
182     *
183     * @param array $values Values to bind to the query.
184     *
185     * @return array
186     *
187     */
188    public function fetchOne($statement, array $values = []);
189
190    /**
191     *
192     * Fetches an associative array of rows as key-value pairs (first
193     * column is the key, second column is the value).
194     *
195     * @param string $statement The SQL statement to prepare and execute.
196     *
197     * @param array $values Values to bind to the query.
198     *
199     * @return array
200     *
201     */
202    public function fetchPairs($statement, array $values = []);
203
204    /**
205     *
206     * Fetches the very first value (i.e., first column of the first row).
207     *
208     * @param string $statement The SQL statement to prepare and execute.
209     *
210     * @param array $values Values to bind to the query.
211     *
212     * @return mixed
213     *
214     */
215    public function fetchValue($statement, array $values = []);
216
217    /**
218     *
219     * Returns the Parser instance.
220     *
221     * @return ParserInterface
222     *
223     */
224    public function getParser();
225
226    /**
227     *
228     * Return the inner PDO (if any)
229     *
230     * @return \PDO
231     *
232     */
233    public function getPdo();
234
235    /**
236     *
237     * Returns the Profiler instance.
238     *
239     * @return ProfilerInterface
240     *
241     */
242    public function getProfiler();
243
244    /**
245     *
246     * Quotes a multi-part (dotted) identifier name.
247     *
248     * @param string $name The multi-part identifier name.
249     *
250     * @return string The multi-part identifier name, quoted.
251     *
252     */
253    public function quoteName($name);
254
255    /**
256     *
257     * Quotes a single identifier name.
258     *
259     * @param string $name The identifier name.
260     *
261     * @return string The quoted identifier name.
262     *
263     */
264    public function quoteSingleName($name);
265
266    /**
267     *
268     * Is the PDO connection active?
269     *
270     * @return bool
271     *
272     */
273    public function isConnected();
274
275    /**
276     *
277     * Sets the Parser instance.
278     *
279     * @param ParserInterface $parser The Parser instance.
280     *
281     */
282    public function setParser(ParserInterface $parser);
283
284    /**
285     *
286     * Sets the Profiler instance.
287     *
288     * @param ProfilerInterface $profiler The Profiler instance.
289     *
290     */
291    public function setProfiler(ProfilerInterface $profiler);
292
293    /**
294     *
295     * Yields rows from the database
296     *
297     * @param string $statement The SQL statement to prepare and execute.
298     *
299     * @param array $values Values to bind to the query.
300     *
301     * @return \Generator
302     *
303     */
304    public function yieldAll($statement, array $values = []);
305
306    /**
307     *
308     * Yields rows from the database keyed on the first column of each row.
309     *
310     * @param string $statement The SQL statement to prepare and execute.
311     *
312     * @param array $values Values to bind to the query.
313     *
314     * @return \Generator
315     *
316     */
317    public function yieldAssoc($statement, array $values = []);
318
319    /**
320     *
321     * Yields the first column of all rows
322     *
323     * @param string $statement The SQL statement to prepare and execute.
324     *
325     * @param array $values Values to bind to the query.
326     *
327     * @return \Generator
328     *
329     */
330    public function yieldCol($statement, array $values = []);
331
332    /**
333     *
334     * Yields objects where the column values are mapped to object properties.
335     *
336     * Warning: PDO "injects property-values BEFORE invoking the constructor -
337     * in other words, if your class initializes property-values to defaults
338     * in the constructor, you will be overwriting the values injected by
339     * fetchObject() !"
340     * <http://www.php.net/manual/en/pdostatement.fetchobject.php#111744>
341     *
342     * @param string $statement The SQL statement to prepare and execute.
343     *
344     * @param array $values Values to bind to the query.
345     *
346     * @param string $class The name of the class to create from each
347     * row.
348     *
349     * @param array $args Arguments to pass to each object constructor.
350     *
351     * @return \Generator
352     *
353     */
354    public function yieldObjects(
355        $statement,
356        array $values = [],
357        $class = 'stdClass',
358        array $args = []
359    );
360
361    /**
362     *
363     * Yields key-value pairs (first column is the key, second column is the
364     * value).
365     *
366     * @param string $statement The SQL statement to prepare and execute.
367     *
368     * @param array $values Values to bind to the query.
369     *
370     * @return \Generator
371     *
372     */
373    public function yieldPairs($statement, array $values = []);
374
375    /**
376     *
377     * Performs a query after preparing the statement with bound values, then
378     * returns the result as a PDOStatement.
379     *
380     * @param string $statement The SQL statement to prepare and execute.
381     *
382     * @param array $values Values to bind to the query.
383     *
384     * @return \PDOStatement
385     *
386     */
387    public function perform($statement, array $values = []);
388
389    /**
390     *
391     * Prepares an SQL statement with bound values.
392     *
393     * This method only binds values that have placeholders in the
394     * statement, thereby avoiding errors from PDO regarding too many bound
395     * values. It also binds all sequential (question-mark) placeholders.
396     *
397     * If a placeholder value is an array, the array is converted to a string
398     * of comma-separated quoted values; e.g., for an `IN (...)` condition.
399     * The quoted string is replaced directly into the statement instead of
400     * using `PDOStatement::bindValue()` proper.
401     *
402     * @param string $statement The SQL statement to prepare for execution.
403     *
404     * @param array $values The values to bind to the statement, if any.
405     *
406     * @return \PDOStatement
407     *
408     * @see http://php.net/manual/en/pdo.prepare.php
409     *
410     */
411    public function prepareWithValues($statement, array $values = []);
412}
413