1<?php 2/** 3 * Copyright 2007 Maintainable Software, LLC 4 * Copyright 2008-2017 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 */ 24interface 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 Horde_Db_Adapter_Base_Result 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 * @deprecated Deprecated for external usage. Use select() instead. 209 * 210 * @param string $sql SQL statement. 211 * @param mixed $arg1 Either an array of bound parameters or a query 212 * name. 213 * @param string $arg2 If $arg1 contains bound parameters, the query 214 * name. 215 * 216 * @return mixed 217 * @throws Horde_Db_Exception 218 */ 219 public function execute($sql, $arg1 = null, $arg2 = null); 220 221 /** 222 * Inserts a row into a table. 223 * 224 * @param string $sql SQL statement. 225 * @param array|string $arg1 Either an array of bound parameters or a 226 * query name. 227 * @param string $arg2 If $arg1 contains bound parameters, the 228 * query name. 229 * @param string $pk The primary key column. 230 * @param integer $idValue The primary key value. This parameter is 231 * required if the primary key is inserted 232 * manually. 233 * @param string $sequenceName The sequence name. 234 * 235 * @return integer Last inserted ID. 236 * @throws Horde_Db_Exception 237 */ 238 public function insert($sql, $arg1 = null, $arg2 = null, $pk = null, 239 $idValue = null, $sequenceName = null); 240 241 /** 242 * Inserts a row including BLOBs into a table. 243 * 244 * @since Horde_Db 2.1.0 245 * 246 * @param string $table The table name. 247 * @param array $fields A hash of column names and values. BLOB columns 248 * must be provided as Horde_Db_Value_Binary 249 * objects. 250 * @param string $pk The primary key column. 251 * @param integer $idValue The primary key value. This parameter is 252 * required if the primary key is inserted 253 * manually. 254 * 255 * @return integer Last inserted ID. 256 * @throws Horde_Db_Exception 257 */ 258 public function insertBlob($table, $fields, $pk = null, $idValue = null); 259 260 /** 261 * Executes the update statement and returns the number of rows affected. 262 * 263 * @param string $sql SQL statement. 264 * @param mixed $arg1 Either an array of bound parameters or a query 265 * name. 266 * @param string $arg2 If $arg1 contains bound parameters, the query 267 * name. 268 * 269 * @return integer Number of rows affected. 270 * @throws Horde_Db_Exception 271 */ 272 public function update($sql, $arg1 = null, $arg2 = null); 273 274 /** 275 * Updates rows including BLOBs into a table. 276 * 277 * @since Horde_Db 2.2.0 278 * 279 * @param string $table The table name. 280 * @param array $fields A hash of column names and values. BLOB columns 281 * must be provided as Horde_Db_Value_Binary objects. 282 * @param string $where A WHERE clause. 283 * 284 * @throws Horde_Db_Exception 285 */ 286 public function updateBlob($table, $fields, $where = ''); 287 288 /** 289 * Executes the delete statement and returns the number of rows affected. 290 * 291 * @param string $sql SQL statement. 292 * @param mixed $arg1 Either an array of bound parameters or a query 293 * name. 294 * @param string $arg2 If $arg1 contains bound parameters, the query 295 * name. 296 * 297 * @return integer Number of rows affected. 298 * @throws Horde_Db_Exception 299 */ 300 public function delete($sql, $arg1 = null, $arg2 = null); 301 302 /** 303 * Check if a transaction has been started. 304 * 305 * @return boolean True if transaction has been started. 306 */ 307 public function transactionStarted(); 308 309 /** 310 * Begins the transaction (and turns off auto-committing). 311 */ 312 public function beginDbTransaction(); 313 314 /** 315 * Commits the transaction (and turns on auto-committing). 316 */ 317 public function commitDbTransaction(); 318 319 /** 320 * Rolls back the transaction (and turns on auto-committing). Must be 321 * done if the transaction block raises an exception or returns false. 322 */ 323 public function rollbackDbTransaction(); 324 325 /** 326 * Appends +LIMIT+ and +OFFSET+ options to a SQL statement. 327 * 328 * @param string $sql SQL statement. 329 * @param array $options TODO 330 * 331 * @return string 332 */ 333 public function addLimitOffset($sql, $options); 334 335 /** 336 * Appends a locking clause to an SQL statement. 337 * This method *modifies* the +sql+ parameter. 338 * 339 * # SELECT * FROM suppliers FOR UPDATE 340 * add_lock! 'SELECT * FROM suppliers', :lock => true 341 * add_lock! 'SELECT * FROM suppliers', :lock => ' FOR UPDATE' 342 * 343 * @param string &$sql SQL statment. 344 * @param array $options TODO. 345 */ 346 public function addLock(&$sql, array $options = array()); 347} 348