Source for file abstractdb.class.php

Documentation is available at abstractdb.class.php

  1. <?php
  2. /**
  3. * @package AbstractDB
  4. * @author Pacific-Cybersoft
  5. * @copyright (C) 2005 Pacific-Cybersoft. All Rights Reserved.
  6. * @version v 1.0.2
  7. * @license http://www.gnu.org/copyleft/lesser.txt GNU Lesser General Public License
  8. */
  9.  
  10. /**
  11. * AbstractDB Main Class
  12. *
  13. * The main AbstractDB class used to interact with various DBMS packages via the
  14. * use of driver classes.
  15. * @package AbstractDB
  16. * @access public
  17. */
  18. class AbstractDB
  19. {
  20. /* PRIVATE FIELDS */
  21. /**
  22. * List of connection arguments.
  23. * @access private
  24. * @var array
  25. */
  26. var $_arguments;
  27. /**
  28. * Reference to the AbstractDB driver.
  29. * @access private
  30. * @var object
  31. */
  32. var $_driver;
  33. /**
  34. * The last error message.
  35. * @access private
  36. * @var string
  37. */
  38. var $_error;
  39. /**
  40. * Name of an error handling function passed in via {@link SetErrorHandler}.
  41. * @access private
  42. * @var string
  43. */
  44. var $_error_handler;
  45. /* PUBLIC PROPERTIES */
  46. /**
  47. * List of supported features of the currently loaded driver.
  48. * @access public
  49. * @var array
  50. */
  51. var $Support;
  52. /**
  53. * AbstractDB Constructor
  54. *
  55. * Initilises an instance of the AbstractDB class.
  56. * @access public
  57. * @internal Parses connection arguments and loads the driver class.
  58. * @param array $arguments Database connection and driver specific arguments.
  59. *
  60. * Arguments must be supplied as an associative array containing one of the following:
  61. *
  62. * ConnectionString:
  63. *
  64. * A string composed of the connection arguments and optional or driver specific options in the form
  65. * of <b>Type</b>://<b>Username</b>:<b>Password</b>@<b>Hostname</b>:<b>Port</b>/<b>Database</b>?<b>Options</b>/option1=value1&<b>Options</b>/option2=value2
  66. *
  67. * e.g. $args = array("ConnectionString" => "mysql://root:pass@localhost/MyDatabase?Options/Persistent=1");
  68. *
  69. * or
  70. *
  71. * Type: The type of database to connect to. AbstractDB is currently only distributed with a MySQL driver.
  72. *
  73. * Username: The database username.
  74. *
  75. * Password: The database password.
  76. *
  77. * Hostname: The database hostname or IP Address.
  78. *
  79. * Database: The name of the database.
  80. *
  81. * Options: An associative array of optional or driver specific options. See individual driver
  82. * documentation for a potential list of driver specific options. The value for Port should be
  83. * specified in this list, otherwise the default port for the database type will be used.
  84. *
  85. * e.g. $args = array("Type" => "mysql", "Username" => "root", "Password" => "pass", "Hostname" => "localhost", "Database" => "MyDatabase", "Options" => array("Persistent" => 1));
  86. *
  87. * Type and Database are required parameters and must be specified.
  88. * @example instantiate_connectionstring.php Instantiation example using a ConnectionString argument.
  89. * @example instantiate_associative.php Instantiation example using an associative array of arguments.
  90. */
  91. function AbstractDB($arguments)
  92. {
  93. $this->ClearError();
  94. if($this->ParseArguments($arguments))
  95. $this->LoadDriver();
  96. }
  97. /* PUBLIC FUNCTIONS */
  98. /**
  99. * Closes the Database Connection
  100. * @access public
  101. * @return bool Returns true if the database connection was successfully closed, otherwise false.
  102. */
  103. function Close()
  104. {
  105. $result = $this->_driver->Close();
  106. $this->GetDriverError();
  107. return $result;
  108. }
  109. /**
  110. * Fetches the Next Row as an Associative Array
  111. * @access public
  112. * @param resource $rs A reference to a resource handle returned by executing a query.
  113. * @param array $assoc A reference to an array that will contain the result row.
  114. * @return bool Returns true if the operation was successful, otherwise false.
  115. * @example fetch_next_result.php FetchNextResult example.
  116. */
  117. function FetchNextResultAssoc(&$rs, &$assoc)
  118. {
  119. $this->ClearError();
  120. if($result = $this->IsResource($rs, "FetchNextResultAssoc"))
  121. {
  122. if(isset($this->Support["FetchAssoc"]) && $this->Support["FetchAssoc"])
  123. $result = (($assoc = $this->_driver->FetchAssoc($rs)) != false);
  124. else
  125. $reuslt = false;
  126. $this->GetDriverError();
  127. }
  128. return $result;
  129. }
  130. /**
  131. * Fetches the Next Row as an Object
  132. * @access public
  133. * @param resource $rs A reference to a resource handle returned by executing a query.
  134. * @param object $object A reference to an object that will contain the result row.
  135. * @return bool Returns true if the operation was successful, otherwise false.
  136. * @example fetch_next_result.php FetchNextResult example.
  137. */
  138. function FetchNextResultObject(&$rs, &$object)
  139. {
  140. $this->ClearError();
  141. if($result = $this->IsResource($rs, "FetchNextResultObject"))
  142. {
  143. if(isset($this->Support["FetchObject"]) && $this->Support["FetchObject"])
  144. $result = (($object = $this->_driver->FetchObject($rs)) != false);
  145. else
  146. $reuslt = false;
  147. $this->GetDriverError();
  148. }
  149. return $result;
  150. }
  151. /**
  152. * Fetches the Next Row
  153. * @access public
  154. * @param resource $rs A reference to a resource handle returned by executing a query.
  155. * @param array $row A reference to an array that will contain the result row.
  156. * @return bool Returns true if the operation was successful, otherwise false.
  157. * @example fetch_next_result.php FetchNextResult example.
  158. */
  159. function FetchNextResultRow(&$rs, &$row)
  160. {
  161. $this->ClearError();
  162. if($result = $this->IsResource($rs, "FetchNextResultRow"))
  163. {
  164. $result = (($row = $this->_driver->FetchRow($rs)) != false);
  165. $this->GetDriverError();
  166. }
  167. return $result;
  168. }
  169. /**
  170. * Fetches a Row as an Associative Array
  171. *
  172. * Fetches the first row as an associative array and then frees the result set.
  173. * @access public
  174. * @param resource $rs A reference to a resource handle returned by executing a query.
  175. * @param array $assoc A reference to an array that will contain the result row.
  176. * @return bool Returns true if the operation was successful, otherwise false.
  177. * @example fetch_result.php FetchResult example.
  178. */
  179. function FetchResultAssoc(&$rs, &$assoc)
  180. {
  181. $this->ClearError();
  182. if($result = $this->IsResource($rs, "FetchResultAssoc"))
  183. {
  184. $result = $this->FetchNextResultAssoc($rs, $assoc);
  185. $this->GetDriverError();
  186. $this->_driver->FreeResult($rs);
  187. $this->GetDriverError();
  188. }
  189. return $result;
  190. }
  191. /**
  192. * Fetches All Rows as Associative Arrays
  193. *
  194. * Fetches all rows as associative arrays and then frees the result set.
  195. * @access public
  196. * @param resource $rs A reference to a resource handle returned by executing a query.
  197. * @param array $all A reference to an array that will contain the result rows.
  198. * @return bool Returns true if the operation was successful, otherwise false.
  199. * @example fetch_result_all.php FetchResultAll example.
  200. */
  201. function FetchResultAssocAll(&$rs, &$all)
  202. {
  203. $this->ClearError();
  204. if($result = $this->IsResource($rs, "FetchResultAssocAll"))
  205. {
  206. while($result = $this->FetchNextResultAssoc($rs, $all[])){}
  207. array_pop($all);
  208. $this->GetDriverError();
  209. $result = (strlen($this->_error) == 0);
  210. $this->_driver->FreeResult($rs);
  211. $this->GetDriverError();
  212. }
  213. return $result;
  214. }
  215. /**
  216. * Fetches a Result Column
  217. *
  218. * Fetches all rows of the first column and then frees the result set.
  219. * @access public
  220. * @param resource $rs A reference to a resource handle returned by executing a query.
  221. * @param array $column A reference to an array that will contain the result column rows.
  222. * @return bool Returns true if the operation was successful, otherwise false.
  223. * @example fetch_result_column.php FetchResultColumn example.
  224. */
  225. function FetchResultColumn(&$rs, &$column)
  226. {
  227. $this->ClearError();
  228. if($result = $this->IsResource($rs, "FetchResultColumn"))
  229. {
  230. while($column[] = $this->_driver->FetchField($rs)){}
  231. array_pop($column);
  232. $this->GetDriverError();
  233. $result = (strlen($this->_error) == 0);
  234. $this->_driver->FreeResult($rs);
  235. $this->GetDriverError();
  236. }
  237. return $result;
  238. }
  239. /**
  240. * Fetches a Result Field
  241. *
  242. * Fetches the value in the first column of the first row and then frees the result set.
  243. * @access public
  244. * @param resource $rs A reference to a resource handle returned by executing a query.
  245. * @param mixed $field A reference to a variable that will contain the field value.
  246. * @return bool Returns true if the operation was successful, otherwise false.
  247. * @example fetch_result_field.php FetchResultField example.
  248. */
  249. function FetchResultField(&$rs, &$field)
  250. {
  251. $this->ClearError();
  252. if($result = $this->IsResource($rs, "FetchResultField"))
  253. {
  254. $result = (($field = $this->_driver->FetchField($rs)) != false);
  255. $this->GetDriverError();
  256. $this->_driver->FreeResult($rs);
  257. $this->GetDriverError();
  258. }
  259. return $result;
  260. }
  261. /**
  262. * Fetches a Row as an Object
  263. *
  264. * Fetches the first row as an object and then frees the result set.
  265. * @access public
  266. * @param resource $rs A reference to a resource handle returned by executing a query.
  267. * @param object $object A reference to an object that will contain the result row.
  268. * @return bool Returns true if the operation was successful, otherwise false.
  269. * @example fetch_result.php FetchResult example.
  270. */
  271. function FetchResultObject(&$rs, &$object)
  272. {
  273. $this->ClearError();
  274. if($result = $this->IsResource($rs, "FetchResultObject"))
  275. {
  276. $result = $this->FetchNextResultObject($rs, $object);
  277. $this->GetDriverError();
  278. $this->_driver->FreeResult($rs);
  279. $this->GetDriverError();
  280. }
  281. return $result;
  282. }
  283. /**
  284. * Fetches All Rows as Objects
  285. *
  286. * Fetches all rows as objects and then frees the result set.
  287. * @access public
  288. * @param resource $rs A reference to a resource handle returned by executing a query.
  289. * @param array $all A reference to an array that will contain the result rows.
  290. * @return bool Returns true if the operation was successful, otherwise false.
  291. * @example fetch_result_all.php FetchResultAll example.
  292. */
  293. function FetchResultObjectAll(&$rs, &$all)
  294. {
  295. $this->ClearError();
  296. if($result = $this->IsResource($rs, "FetchResultObjectAll"))
  297. {
  298. while($result = $this->FetchNextResultObject($rs, $all[])){}
  299. array_pop($all);
  300. $this->GetDriverError();
  301. $result = (strlen($this->_error) == 0);
  302. $this->_driver->FreeResult($rs);
  303. $this->GetDriverError();
  304. }
  305. return $result;
  306. }
  307. /**
  308. * Fetches a Row
  309. *
  310. * Fetches the first row and then frees the result set.
  311. * @access public
  312. * @param resource $rs A reference to a resource handle returned by executing a query.
  313. * @param array $row A reference to an array that will contain the result row.
  314. * @return bool Returns true if the operation was successful, otherwise false.
  315. * @example fetch_result.php FetchResult example.
  316. */
  317. function FetchResultRow(&$rs, &$row)
  318. {
  319. $this->ClearError();
  320. if($result = $this->IsResource($rs, "FetchResultRow"))
  321. {
  322. $result = $this->FetchNextResultRow($rs, $row);
  323. $this->GetDriverError();
  324. $this->_driver->FreeResult($rs);
  325. $this->GetDriverError();
  326. }
  327. return $result;
  328. }
  329. /**
  330. * Fetches All Rows
  331. *
  332. * Fetches all rows and then frees the result set.
  333. * @access public
  334. * @param resource $rs A reference to a resource handle returned by executing a query.
  335. * @param array $all A reference to an array that will contain the result rows.
  336. * @return bool Returns true if the operation was successful, otherwise false.
  337. * @example fetch_result_all.php FetchResultAll example.
  338. */
  339. function FetchResultRowAll(&$rs, &$all)
  340. {
  341. $this->ClearError();
  342. if($result = $this->IsResource($rs, "FetchResultRowAll"))
  343. {
  344. while($result = $this->FetchNextResultRow($rs, $all[])){}
  345. array_pop($all);
  346. $this->GetDriverError();
  347. $result = (strlen($this->_error) == 0);
  348. $this->_driver->FreeResult($rs);
  349. $this->GetDriverError();
  350. }
  351. return $result;
  352. }
  353. /**
  354. * Fetches a Row as an Associative Array
  355. *
  356. * Fetches the row at the specified position in the result set as an associative array.
  357. * @access public
  358. * @param resource $rs A reference to a resource handle returned by executing a query.
  359. * @param int $row_num The position in the result set of the row to return.
  360. * @param array $assoc A reference to an array that will contain the result row.
  361. * @return bool Returns true if the operation was successful, otherwise false.
  362. * @example fetch_seek_result.php FetchSeekResult example.
  363. */
  364. function FetchSeekResultAssoc(&$rs, $row_num, &$assoc)
  365. {
  366. $this->ClearError();
  367. if($result = $this->IsResource($rs, "FetchSeekResultAssoc"))
  368. {
  369. if(isset($this->Support["DataSeek"]) && $this->Support["DataSeek"])
  370. {
  371. if($result = $this->_driver->DataSeek($rs, $row_num))
  372. $result = $this->FetchNextResultAssoc($rs, $assoc);
  373. }
  374. else
  375. $reuslt = false;
  376. $this->GetDriverError();
  377. }
  378. return $result;
  379. }
  380. /**
  381. * Fetches a Row as an Object
  382. *
  383. * Fetches the row at the specified position in the result set as an object.
  384. * @access public
  385. * @param resource $rs A reference to a resource handle returned by executing a query.
  386. * @param int $row_num The position in the result set of the row to return.
  387. * @param object $object A reference to an object that will contain the result row.
  388. * @return bool Returns true if the operation was successful, otherwise false.
  389. * @example fetch_seek_result.php FetchSeekResult example.
  390. */
  391. function FetchSeekResultObject(&$rs, $row_num, &$object)
  392. {
  393. $this->ClearError();
  394. if($result = $this->IsResource($rs, "FetchSeekResultObject"))
  395. {
  396. if(isset($this->Support["DataSeek"]) && $this->Support["DataSeek"])
  397. {
  398. if($result = $this->_driver->DataSeek($rs, $row_num))
  399. $result = $this->FetchNextResultObject($rs, $object);
  400. }
  401. else
  402. $reuslt = false;
  403. $this->GetDriverError();
  404. }
  405. return $result;
  406. }
  407. /**
  408. * Fetches a Row
  409. *
  410. * Fetches the row at the specified position in the result set.
  411. * @access public
  412. * @param resource $rs A reference to a resource handle returned by executing a query.
  413. * @param int $row_num The position in the result set of the row to return.
  414. * @param array $row A reference to an array that will contain the result row.
  415. * @return bool Returns true if the operation was successful, otherwise false.
  416. * @example fetch_seek_result.php FetchSeekResult example.
  417. */
  418. function FetchSeekResultRow(&$rs, $row_num, &$row)
  419. {
  420. $this->ClearError();
  421. if($result = $this->IsResource($rs, "FetchSeekResultRow"))
  422. {
  423. if(isset($this->Support["DataSeek"]) && $this->Support["DataSeek"])
  424. {
  425. if($result = $this->_driver->DataSeek($rs, $row_num))
  426. $result = $this->FetchNextResultRow($rs, $row);
  427. }
  428. else
  429. $reuslt = false;
  430. $this->GetDriverError();
  431. }
  432. return $result;
  433. }
  434. /**
  435. * Frees a Result Resource
  436. *
  437. * Frees the resources associated with the given result handle returned by executing a query.
  438. * @access public
  439. * @param resource $rs A reference to a resource handle returned by executing a query.
  440. * @return bool Returns true if the resource handle was successfully freed.
  441. */
  442. function FreeResult(&$rs)
  443. {
  444. if($result = $this->IsResource($rs, "FreeResult"))
  445. {
  446. $result = $this->_driver->FreeResult($rs);
  447. $this->GetDriverError();
  448. }
  449. return $result;
  450. }
  451. /**
  452. * Gets the Number of Affected Rows
  453. * @access public
  454. * @return int Returns the number of rows affected by the last executed query, or false if the
  455. * driver does not support this feature.
  456. * @example affected_rows.php GetAffectedRows example.
  457. */
  458. function GetAffectedRows()
  459. {
  460. $this->ClearError();
  461. if(isset($this->Support["AffectedRows"]) && $this->Support["AffectedRows"])
  462. $result = $this->_driver->AffectedRows();
  463. else
  464. $result = false;
  465. $this->GetDriverError();
  466. return $result;
  467. }
  468.  
  469. /**
  470. * Gets the Name of the Current Database
  471. * @access public
  472. * @return string The name of the current database.
  473. */
  474. function GetDatabase()
  475. {
  476. return $this->_arguments["Database"];
  477. }
  478. /**
  479. * Gets the Number of Fields
  480. *
  481. * Gets the number of fields returned by the given result handle.
  482. * @access public
  483. * @param resource $rs A reference to a resource handle returned by executing a query.
  484. * @return int Returns the number of fields returned by the last executed query.
  485. * @example field_count.php GetFieldCount example.
  486. */
  487. function GetFieldCount(&$rs)
  488. {
  489. $this->ClearError();
  490. if($result = $this->IsResource($rs, "GetFieldCount"))
  491. {
  492. $result = $this->_driver->FieldCount($rs);
  493. $this->GetDriverError();
  494. }
  495. return $result;
  496. }
  497. /**
  498. * Gets the Field Names of a Query
  499. * @access public
  500. * @param resource $rs A reference to a resource handle returned by executing a query.
  501. * @param array $fields A reference to an array that will contain the field names.
  502. * @return bool Returns true if the operation was successful, otherwise false.
  503. * @example field_names.php GetFieldNames example.
  504. */
  505. function GetFieldNames(&$rs, &$fields)
  506. {
  507. $this->ClearError();
  508. if($result = $this->IsResource($rs, "GetFieldNames"))
  509. {
  510. $result = $this->_driver->FieldNames($rs, $fields);
  511. $this->GetDriverError();
  512. }
  513. return $result;
  514. }
  515. /**
  516. * Gets the Last Insert ID
  517. * @access public
  518. * @return mixed Returns either the ID of the last inserted AUTO_INCREMENT record, or -1 if the
  519. * last query was not an insert, or false if the driver does not support this feature.
  520. * @example insert_id.php GetInsertID example.
  521. */
  522. function GetInsertID()
  523. {
  524. $this->ClearError();
  525. if(isset($this->Support["InsertID"]) && $this->Support["InsertID"])
  526. $result = $this->_driver->InsertID();
  527. else
  528. $result = false;
  529. $this->GetDriverError();
  530. return $result;
  531. }
  532. /**
  533. * Gets the Last Error.
  534. * @access public
  535. * @return string The last error message.
  536. */
  537. function GetLastError()
  538. {
  539. return $this->_error;
  540. }
  541. /**
  542. * Gets the Number of Rows
  543. *
  544. * Gets the number of rows returned by the last query of the given result handle.
  545. * @access public
  546. * @param resource $rs A reference to a resource handle returned by executing a query.
  547. * @return int Returns the number of rows returned by the last executed query.
  548. * @example row_count.php GetRowCount example.
  549. */
  550. function GetRowCount(&$rs)
  551. {
  552. $this->ClearError();
  553. if($result = $this->IsResource($rs, "GetRowCount"))
  554. {
  555. $result = $this->_driver->RowCount($rs);
  556. $this->GetDriverError();
  557. }
  558. return $result;
  559. }
  560.  
  561. /**
  562. * Executes an SQL Statement
  563. *
  564. * Executes the given SQL statement.
  565. * @access public
  566. * @internal If the query did not execute successfully an error is set explaining as
  567. * best as possible the reason for the failure.
  568. * @param string $sql The SQL statement to be executed.
  569. * @return resource The result handle for use in fetch result functions.
  570. * @example query.php Query example.
  571. */
  572. function Query($sql)
  573. {
  574. $this->ClearError();
  575. $result = &$this->_driver->Query($sql);
  576. $this->GetDriverError();
  577. return $result;
  578. }
  579. /**
  580. * Executes an SQL Statement
  581. *
  582. * Executes the given SQL statement and retrieves the first result row as an associative array, then
  583. * frees the result set.
  584. * @param string $sql The SQL statement to be executed.
  585. * @param array $assoc A reference to an array that will contain the result row.
  586. * @return bool Returns true if the operation was successful, otherwise false.
  587. * @example query_result.php Query example.
  588. */
  589. function QueryAssoc($sql, &$assoc)
  590. {
  591. $this->ClearError();
  592. $result = false;
  593. if($rs = &$this->Query($sql))
  594. $result = $this->FetchResultAssoc($rs, $assoc);
  595. return $result;
  596. }
  597. /**
  598. * Executes an SQL Statement
  599. *
  600. * Executes the given SQL statement and retrieves all result rows as associative arrays, then
  601. * frees the result set.
  602. * @param string $sql The SQL statement to be executed.
  603. * @param array $all A reference to an array that will contain the result rows.
  604. * @return bool Returns true if the operation was successful, otherwise false.
  605. * @example query_result_all.php Query All example.
  606. */
  607. function QueryAssocAll($sql, &$all)
  608. {
  609. $this->ClearError();
  610. $result = false;
  611. if($rs = &$this->Query($sql))
  612. $result = $this->FetchResultAssocAll($rs, $all);
  613. return $result;
  614. }
  615. /**
  616. * Executes an SQL Statement
  617. *
  618. * Executes the given SQL statement and retrieves all rows of the first result column, then
  619. * frees the result set.
  620. * @access public
  621. * @param string $sql The SQL statement to be executed.
  622. * @param array $column A reference to an array that will contain the result column rows.
  623. * @return bool Returns true if the operation was successful, otherwise false.
  624. * @example query_column.php QueryColumn example.
  625. */
  626. function QueryColumn($sql, &$column)
  627. {
  628. $this->ClearError();
  629. $result = false;
  630. if($rs = &$this->Query($sql))
  631. $result = $this->FetchResultColumn($rs, $column);
  632. return $result;
  633. }
  634. /**
  635. * Executes an SQL Statement
  636. *
  637. * Executes the given SQL statement and retrieves the value in the first column of the first
  638. * row, then frees the result set.
  639. * @access public
  640. * @param string $sql The SQL statement to be executed.
  641. * @param mixed $field A reference to a variable that will contain the field value.
  642. * @return bool Returns true if the operation was successful, otherwise false.
  643. * @example query_field.php QueryField example.
  644. */
  645. function QueryField($sql, &$field)
  646. {
  647. $this->ClearError();
  648. $result = false;
  649. if($rs = &$this->Query($sql))
  650. $result = $this->FetchResultField($rs, $field);
  651. return $result;
  652. }
  653. /**
  654. * Executes an SQL Statement
  655. *
  656. * Executes the given SQL statement and retrieves the first result row as an object, then
  657. * frees the result set.
  658. * @param string $sql The SQL statement to be executed.
  659. * @param object $object A reference to an object that will contain the result row.
  660. * @return bool Returns true if the operation was successful, otherwise false.
  661. * @example query_result.php Query example.
  662. */
  663. function QueryObject($sql, &$object)
  664. {
  665. $this->ClearError();
  666. $result = false;
  667. if($rs = &$this->Query($sql))
  668. $result = $this->FetchResultObject($rs, $object);
  669. return $result;
  670. }
  671. /**
  672. * Executes an SQL Statement
  673. *
  674. * Executes the given SQL statement and retrieves all result rows as objects, then
  675. * frees the result set.
  676. * @param string $sql The SQL statement to be executed.
  677. * @param array $all A reference to an array that will contain the result rows.
  678. * @return bool Returns true if the operation was successful, otherwise false.
  679. * @example query_result_all.php Query All example.
  680. */
  681. function QueryObjectAll($sql, &$all)
  682. {
  683. $this->ClearError();
  684. $result = false;
  685. if($rs = &$this->Query($sql))
  686. $result = $this->FetchResultObjectAll($rs, $all);
  687. return $result;
  688. }
  689. /**
  690. * Executes an SQL Statement
  691. *
  692. * Executes the given SQL statement and retrieves the first result row, then
  693. * frees the result set.
  694. * @param string $sql The SQL statement to be executed.
  695. * @param array $row A reference to an array that will contain the result row.
  696. * @return bool Returns true if the operation was successful, otherwise false.
  697. * @example query_result.php Query example.
  698. */
  699. function QueryRow($sql, &$row)
  700. {
  701. $this->ClearError();
  702. $result = false;
  703. if($rs = &$this->Query($sql))
  704. $result = $this->FetchResultRow($rs, $row);
  705. return $result;
  706. }
  707. /**
  708. * Executes an SQL Statement
  709. *
  710. * Executes the given SQL statement and retrieves all result rows, then frees the result set.
  711. * @param string $sql The SQL statement to be executed.
  712. * @param array $all A reference to an array that will contain the result rows.
  713. * @return bool Returns true if the operation was successful, otherwise false.
  714. * @example query_result_all.php Query All example.
  715. */
  716. function QueryRowAll($sql, &$all)
  717. {
  718. $this->ClearError();
  719. $result = false;
  720. if($rs = &$this->Query($sql))
  721. $result = $this->FetchResultRowAll($rs, $all);
  722. return $result;
  723. }
  724. /**
  725. * Executes an SQL Replace Query
  726. * @access public
  727. * @param string $table The name of the table to execute the replace query on.
  728. * @param array $fields An associative array of field definitions. Keys should be the field names and
  729. * values should be an associative array containing the following keys:
  730. *
  731. * Key => bool indicating that this field is the primary key or part of a unique index. Key values must not be NULL.
  732. *
  733. * Type => either "text", "numeric", "bool".
  734. *
  735. * Value => the value of the field.
  736. *
  737. * Null => bool indicating if the value of the field should be set to NULL.
  738. *
  739. * e.g. $fields = array("Field1" => array("Key" => true, "Type" => "numeric", "Value" => 123, "Null" => false));
  740. * @return bool Returns true if the operation was successful, otherwise false.
  741. * @example replace.php Replace example.
  742. */
  743. function Replace($table, $fields)
  744. {
  745. $this->ClearError();
  746. $result = $this->_driver->Replace($table, $fields) ? true : false;
  747. $this->GetDriverError();
  748. return $result;
  749. }
  750. /**
  751. * Sets the Current Database
  752. * @access public
  753. * @param string $dbName The name of the new database to perform queries on.
  754. * @return string The old database name that was set before calling this method, or false if an error occurred.
  755. */
  756. function SetDatabase($dbName)
  757. {
  758. $this->ClearError();
  759. $result = $this->_driver->SetDatabase($dbName);
  760. if($result !== false && $result != $this->_arguments["Database"])
  761. $this->_arguments["Database"] = $result;
  762. $this->GetDriverError();
  763. return $result;
  764. }
  765. /**
  766. * Sets an Error Handling Function.
  767. * @access public
  768. * @param string $functionName The name of a function to be called when an error occurs.
  769. * @return bool Returns true if the error handling function was successfully set, otherwise false.
  770. * @example set_error_handler.php SetErrorHandler example.
  771. */
  772. function SetErrorHandler($functionName)
  773. {
  774. if(function_exists($functionName))
  775. {
  776. $this->_error_handler = $functionName;
  777. return true;
  778. }
  779. else
  780. {
  781. $this->SetError("SetErrorHandler", "Could not set error handler, function '$functionName' does not exist.");
  782. return false;
  783. }
  784. }
  785. /* PRIVATE FUNCTIONS */
  786. /**
  787. * Clears the latest error message.
  788. * @access private
  789. */
  790. function ClearError()
  791. {
  792. $this->_error = "";
  793. }
  794. /**
  795. * Ensures Required Connection Arguments Exist
  796. * @access private
  797. * @internal If there are missing arguments an error is set stating which
  798. * arguments are missing.
  799. * @return bool Returns true if all required connection arguments have been set, otherwise false.
  800. */
  801. function EnsureRequiredArguments()
  802. {
  803. $result = true;
  804. $error = "";
  805. if(isset($this->_arguments))
  806. {
  807. if(!isset($this->_arguments["Type"]))
  808. {
  809. $result = false;
  810. $error .= ((strlen($error) > 0) ? ", " : "") . "Type";
  811. }
  812. /*if(!isset($this->_arguments["Hostname"]))
  813. {
  814. $result = false;
  815. $error .= ((strlen($error) > 0) ? ", " : "") . "Hostname";
  816. }
  817. if(!isset($this->_arguments["Username"]))
  818. {
  819. $result = false;
  820. $error .= ((strlen($error) > 0) ? ", " : "") . "Username";
  821. }
  822. if(!isset($this->_arguments["Password"]))
  823. {
  824. $result = false;
  825. $error .= ((strlen($error) > 0) ? ", " : "") . "Password";
  826. }*/
  827. if(!isset($this->_arguments["Database"]))
  828. {
  829. $result = false;
  830. $error .= ((strlen($error) > 0) ? ", " : "") . "Database";
  831. }
  832. }
  833. else
  834. $result = false;
  835. if(!$result)
  836. $this->SetError("EnsureRequiredArguments", "The following required arguments have not been set: " . $error);
  837. return $result;
  838. }
  839. /**
  840. * Gets the Latest Error from the Driver
  841. * @access private
  842. * @internal Sets an error based on the driver error.
  843. */
  844. function GetDriverError()
  845. {
  846. $driverError = $this->_driver->GetLastError();
  847. if(strlen($driverError) > 0)
  848. {
  849. $error = explode(": ", $driverError);
  850. switch(count($error))
  851. {
  852. case 1:
  853. $this->SetError("{$this->_arguments["Type"]}Driver", $error[0]);
  854. break;
  855. case 2:
  856. $this->SetError($error[0], $error[1]);
  857. break;
  858. }
  859. }
  860. }
  861. /**
  862. * Checks That a Parameter is a Resource
  863. *
  864. * Checks that a given parameter is a resource type variable.
  865. * @access private
  866. * @param resource $resource A variable to ensure is a resource.
  867. * @param string $callee The name of the method calling this function. Used in the setting of the error message.
  868. * @return bool Returns true if the given parameter is a resource, otherwise false.
  869. */
  870. function IsResource($resource, $callee)
  871. {
  872. if(!($result = is_resource($resource)))
  873. $this->SetError($callee, "Resource specified is not a valid resource.");
  874. return $result;
  875. }
  876. /**
  877. * Loads an AbstractDB Database Driver
  878. *
  879. * Loads the AbstractDB driver for the type of database being connected to.
  880. * @access private
  881. * @internal If the driver could not be loaded an error is set explaining the
  882. * reason for the failure.
  883. * @return bool Returns true if the driver was successfully loaded, otherwise false.
  884. */
  885. function LoadDriver()
  886. {
  887. $dirname = dirname(__FILE__);
  888. if(!defined("ABSTRACTDB_DRIVER_INCLUDED"))
  889. {
  890. $driverfile = "$dirname/abstractdb_driver.class.php";
  891. if(!file_exists($driverfile))
  892. {
  893. $this->SetError("LoadDriver", "Could not load the AbstractDB Driver base class. File $driverfile not found.");
  894. return false;
  895. }
  896. include($driverfile);
  897. }
  898. if(!defined("ABSTRACTDB_" . strtoupper($this->_arguments["Type"]) . "_INCLUDED"))
  899. {
  900. $driverfile = "$dirname/drivers/abstractdb_" . strtolower($this->_arguments["Type"]) . ".php";
  901. if(!file_exists($driverfile))
  902. {
  903. $this->SetError("LoadDriver", "Driver file $driverfile could not be found.");
  904. return false;
  905. }
  906. include($driverfile);
  907. }
  908. $driver_class = "AbstractDB_" . $this->_arguments["Type"];
  909. $this->_driver = new $driver_class($this->_arguments);
  910. $this->GetDriverError();
  911. if(strlen($this->_error) > 0)
  912. return false;
  913. else
  914. $this->Support = $this->_driver->Support;
  915. return true;
  916. }
  917. /**
  918. * Parses Connection and Driver Specific Arguments
  919. * @access private
  920. * @param array $arguments A list of connection and driver specific arguments.
  921. * @return bool Returns true if arguments were successfully parsed, otherwise false.
  922. */
  923. function ParseArguments($arguments)
  924. {
  925. $result = false;
  926. if(isset($arguments["ConnectionString"]))
  927. $this->ParseConnectionArguments($arguments["ConnectionString"]);
  928. else
  929. {
  930. if(isset($arguments["Type"]))
  931. $this->_arguments["Type"] = $arguments["Type"];
  932. if(isset($arguments["Username"]))
  933. $this->_arguments["Username"] = $arguments["Username"];
  934. if(isset($arguments["Password"]))
  935. $this->_arguments["Password"] = $arguments["Password"];
  936. if(isset($arguments["Hostname"]))
  937. $this->_arguments["Hostname"] = $arguments["Hostname"];
  938. if(isset($arguments["Options"]))
  939. {
  940. if(isset($arguments["Options"]["Port"]))
  941. $this->_arguments["Options"]["Port"] = $arguments["Options"]["Port"];
  942. if(isset($arguments["Options"]["Persistent"]))
  943. $this->_arguments["Options"]["Persistent"] = $arguments["Options"]["Persistent"];
  944. }
  945. if(isset($arguments["Database"]))
  946. $this->_arguments["Database"] = $arguments["Database"];
  947. }
  948. return $this->EnsureRequiredArguments();
  949. }
  950. /**
  951. * Parses ConnectionString Argument
  952. *
  953. * Parses the ConnectionString argument passed in via the constructor.
  954. * @access private
  955. * @param string $connectionString A connection string in the format
  956. * <b>Type</b>://<b>User</b>:<b>Pass</b>@<b>Host</b>:<b>Port</b>/<b>Database</b>?<b>Options</b>/option1=value1&<b>Options</b>/option2=value2
  957. * @return bool Returns true if the connection string was successfully parsed, otherwise false.
  958. * @todo There may be a use for the fragment part of the parsed connection string.
  959. */
  960. function ParseConnectionArguments($connectionString)
  961. {
  962. $result = true;
  963. $parsed = parse_url($connectionString);
  964. if(isset($parsed["scheme"]))
  965. $this->_arguments["Type"] = urldecode($parsed["scheme"]);
  966. else
  967. $result = false;
  968. if(isset($parsed["host"]))
  969. $this->_arguments["Hostname"] = urldecode($parsed["host"]);
  970. else
  971. $result = false;
  972. if(isset($parsed["port"]))
  973. $this->_arguments["Options"]["Port"] = urldecode($parsed["port"]);
  974. if(isset($parsed["user"]))
  975. $this->_arguments["Username"] = urldecode($parsed["user"]);
  976. else
  977. $result = false;
  978. if(isset($parsed["pass"]))
  979. $this->_arguments["Password"] = urldecode($parsed["pass"]);
  980. else
  981. $result = false;
  982. if(isset($parsed["path"]))
  983. $this->_arguments["Database"] = substr(urldecode($parsed["path"]), 1);
  984. else
  985. $result = false;
  986. if(isset($parsed["query"]))
  987. {
  988. $options=explode("&",$parsed["query"]);
  989. for($option=0; $option < count($options); $option++)
  990. {
  991. if(gettype($equal = strpos($options[$option], "=")) != "integer")
  992. {
  993. // This option does not have a value.
  994. continue;
  995. }
  996. $argument = urldecode(substr($options[$option], 0, $equal));
  997. $value = urldecode(substr($options[$option], $equal + 1));
  998. if(gettype($slash = strpos($argument, "/")) == "integer")
  999. {
  1000. if(substr($argument, 0, $slash) != "Options")
  1001. {
  1002. // Not a valid Options argument
  1003. continue;
  1004. }
  1005. $this->_arguments["Options"][substr($argument, $slash + 1)] = $value;
  1006. }
  1007. else
  1008. $this->_arguments[$argument] = $value;
  1009. }
  1010. }
  1011. if(isset($parsed["fragment"])){}
  1012. return $result;
  1013. }
  1014. /**
  1015. * Sets the Latest Error Message.
  1016. *
  1017. * Sets the latest error message and calls an error handling function if one was set.
  1018. * @access private
  1019. * @param string $scope The scope of the error, generally the function in which it occured.
  1020. * @param string $message The actual error message.
  1021. */
  1022. function SetError($scope, $message)
  1023. {
  1024. $this->_error = "$scope: $message";
  1025. if(strcmp($function = $this->_error_handler, ""))
  1026. {
  1027. $error = array("Scope" => $scope, "Message" => $message);
  1028. $function($this, $error);
  1029. }
  1030. }
  1031. }
  1032. ?>

Documentation generated on Wed, 16 Mar 2005 23:16:48 +1100 by phpDocumentor 1.3.0RC3