1: <?php
2: /**
3: * Copyright 2007 Maintainable Software, LLC
4: * Copyright 2008-2012 Horde LLC (http://www.horde.org/)
5: *
6: * @author Mike Naberezny <mike@maintainable.com>
7: * @author Derek DeVries <derek@maintainable.com>
8: * @author Chuck Hagenbuch <chuck@horde.org>
9: * @license http://www.horde.org/licenses/bsd
10: * @category Horde
11: * @package Db
12: * @subpackage Adapter
13: */
14:
15: /**
16: * @author Mike Naberezny <mike@maintainable.com>
17: * @author Derek DeVries <derek@maintainable.com>
18: * @author Chuck Hagenbuch <chuck@horde.org>
19: * @license http://www.horde.org/licenses/bsd
20: * @category Horde
21: * @package Db
22: * @subpackage Adapter
23: */
24: interface Horde_Db_Adapter
25: {
26: /**
27: * Returns the human-readable name of the adapter. Use mixed case - one
28: * can always use downcase if needed.
29: *
30: * @return string
31: */
32: public function adapterName();
33:
34: /**
35: * Does this adapter support migrations? Backend specific, as the
36: * abstract adapter always returns +false+.
37: *
38: * @return boolean
39: */
40: public function supportsMigrations();
41:
42: /**
43: * Does this adapter support using DISTINCT within COUNT? This is +true+
44: * for all adapters except sqlite.
45: *
46: * @return boolean
47: */
48: public function supportsCountDistinct();
49:
50: /**
51: * Should primary key values be selected from their corresponding
52: * sequence before the insert statement? If true, next_sequence_value
53: * is called before each insert to set the record's primary key.
54: * This is false for all adapters but Firebird.
55: *
56: * @return boolean
57: */
58: public function prefetchPrimaryKey($tableName = null);
59:
60:
61: /*##########################################################################
62: # Connection Management
63: ##########################################################################*/
64:
65: /**
66: * Connect to the db.
67: */
68: public function connect();
69:
70: /**
71: * Is the connection active?
72: *
73: * @return boolean
74: */
75: public function isActive();
76:
77: /**
78: * Reconnect to the db.
79: */
80: public function reconnect();
81:
82: /**
83: * Disconnect from db.
84: */
85: public function disconnect();
86:
87: /**
88: * Provides access to the underlying database connection. Useful for when
89: * you need to call a proprietary method such as postgresql's
90: * lo_* methods.
91: *
92: * @return resource
93: */
94: public function rawConnection();
95:
96:
97: /*##########################################################################
98: # Quoting
99: ##########################################################################*/
100:
101: /**
102: * Quotes a string, escaping any special characters.
103: *
104: * @param string $string
105: * @return string
106: */
107: public function quoteString($string);
108:
109:
110: /*##########################################################################
111: # Database Statements
112: ##########################################################################*/
113:
114: /**
115: * Returns an array of records with the column names as keys, and
116: * column values as values.
117: *
118: * @param string $sql SQL statement.
119: * @param mixed $arg1 Either an array of bound parameters or a query
120: * name.
121: * @param string $arg2 If $arg1 contains bound parameters, the query
122: * name.
123: *
124: * @return Iterator
125: * @throws Horde_Db_Exception
126: */
127: public function select($sql, $arg1 = null, $arg2 = null);
128:
129: /**
130: * Returns an array of record hashes with the column names as keys and
131: * column values as values.
132: *
133: * @param string $sql SQL statement.
134: * @param mixed $arg1 Either an array of bound parameters or a query
135: * name.
136: * @param string $arg2 If $arg1 contains bound parameters, the query
137: * name.
138: *
139: * @return array
140: * @throws Horde_Db_Exception
141: */
142: public function selectAll($sql, $arg1 = null, $arg2 = null);
143:
144: /**
145: * Returns a record hash with the column names as keys and column values
146: * as values.
147: *
148: * @param string $sql SQL statement.
149: * @param mixed $arg1 Either an array of bound parameters or a query
150: * name.
151: * @param string $arg2 If $arg1 contains bound parameters, the query
152: * name.
153: *
154: * @return array
155: * @throws Horde_Db_Exception
156: */
157: public function selectOne($sql, $arg1 = null, $arg2 = null);
158:
159: /**
160: * Returns a single value from a record
161: *
162: * @param string $sql SQL statement.
163: * @param mixed $arg1 Either an array of bound parameters or a query
164: * name.
165: * @param string $arg2 If $arg1 contains bound parameters, the query
166: * name.
167: *
168: * @return string
169: * @throws Horde_Db_Exception
170: */
171: public function selectValue($sql, $arg1 = null, $arg2 = null);
172:
173: /**
174: * Returns an array of the values of the first column in a select:
175: * selectValues("SELECT id FROM companies LIMIT 3") => [1,2,3]
176: *
177: * @param string $sql SQL statement.
178: * @param mixed $arg1 Either an array of bound parameters or a query
179: * name.
180: * @param string $arg2 If $arg1 contains bound parameters, the query
181: * name.
182: *
183: * @return array
184: * @throws Horde_Db_Exception
185: */
186: public function selectValues($sql, $arg1 = null, $arg2 = null);
187:
188: /**
189: * Returns an array where the keys are the first column of a select, and the
190: * values are the second column:
191: *
192: * selectAssoc("SELECT id, name FROM companies LIMIT 3") => [1 => 'Ford', 2 => 'GM', 3 => 'Chrysler']
193: *
194: * @param string $sql SQL statement.
195: * @param mixed $arg1 Either an array of bound parameters or a query
196: * name.
197: * @param string $arg2 If $arg1 contains bound parameters, the query
198: * name.
199: *
200: * @return array
201: * @throws Horde_Db_Exception
202: */
203: public function selectAssoc($sql, $arg1 = null, $arg2 = null);
204:
205: /**
206: * Executes the SQL statement in the context of this connection.
207: *
208: * @param string $sql SQL statement.
209: * @param mixed $arg1 Either an array of bound parameters or a query
210: * name.
211: * @param string $arg2 If $arg1 contains bound parameters, the query
212: * name.
213: *
214: * @return Iterator
215: * @throws Horde_Db_Exception
216: */
217: public function execute($sql, $arg1 = null, $arg2 = null);
218:
219: /**
220: * Returns the last auto-generated ID from the affected table.
221: *
222: * @param string $sql SQL statement.
223: * @param mixed $arg1 Either an array of bound parameters or a
224: * query name.
225: * @param string $arg2 If $arg1 contains bound parameters, the
226: * query name.
227: * @param string $pk TODO
228: * @param integer $idValue TODO
229: * @param string $sequenceName TODO
230: *
231: * @return integer Last inserted ID.
232: * @throws Horde_Db_Exception
233: */
234: public function insert($sql, $arg1 = null, $arg2 = null, $pk = null,
235: $idValue = null, $sequenceName = null);
236:
237: /**
238: * Executes the update statement and returns the number of rows affected.
239: *
240: * @param string $sql SQL statement.
241: * @param mixed $arg1 Either an array of bound parameters or a query
242: * name.
243: * @param string $arg2 If $arg1 contains bound parameters, the query
244: * name.
245: *
246: * @return integer Number of rows affected.
247: * @throws Horde_Db_Exception
248: */
249: public function update($sql, $arg1 = null, $arg2 = null);
250:
251: /**
252: * Executes the delete statement and returns the number of rows affected.
253: *
254: * @param string $sql SQL statement.
255: * @param mixed $arg1 Either an array of bound parameters or a query
256: * name.
257: * @param string $arg2 If $arg1 contains bound parameters, the query
258: * name.
259: *
260: * @return integer Number of rows affected.
261: * @throws Horde_Db_Exception
262: */
263: public function delete($sql, $arg1 = null, $arg2 = null);
264:
265: /**
266: * Check if a transaction has been started.
267: *
268: * @return boolean True if transaction has been started.
269: */
270: public function transactionStarted();
271:
272: /**
273: * Begins the transaction (and turns off auto-committing).
274: */
275: public function beginDbTransaction();
276:
277: /**
278: * Commits the transaction (and turns on auto-committing).
279: */
280: public function commitDbTransaction();
281:
282: /**
283: * Rolls back the transaction (and turns on auto-committing). Must be
284: * done if the transaction block raises an exception or returns false.
285: */
286: public function rollbackDbTransaction();
287:
288: /**
289: * Appends +LIMIT+ and +OFFSET+ options to a SQL statement.
290: *
291: * @param string $sql SQL statement.
292: * @param array $options TODO
293: *
294: * @return string
295: */
296: public function addLimitOffset($sql, $options);
297:
298: /**
299: * Appends a locking clause to an SQL statement.
300: * This method *modifies* the +sql+ parameter.
301: *
302: * # SELECT * FROM suppliers FOR UPDATE
303: * add_lock! 'SELECT * FROM suppliers', :lock => true
304: * add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE'
305: *
306: * @param string &$sql SQL statment.
307: * @param array $options TODO.
308: */
309: public function addLock(&$sql, array $options = array());
310: }
311: