Source for file abstractdb_driver.class.php

Documentation is available at abstractdb_driver.class.php

  1. <?php
  2. /**
  3. * AbstractDB Driver Base Class Definition
  4. *
  5. * @package AbstractDB
  6. * @author Pacific-Cybersoft
  7. * @copyright (C) 2005 Pacific-Cybersoft. All Rights Reserved.
  8. * @version v 1.0.2
  9. * @license http://www.gnu.org/copyleft/lesser.txt GNU Lesser General Public License
  10. */
  11.  
  12. /**
  13. * AbstractDB Driver included constant.
  14. *
  15. * Flag that indicates that the driver base class file has been included.
  16. * @access public
  17. */
  18. define("ABSTRACTDB_DRIVER_INCLUDED", true);
  19.  
  20. /**
  21. * AbstractDB Driver Base Class
  22. *
  23. * Driver base class from which all other AbstractDB drivers extend.
  24. * @package AbstractDB
  25. * @abstract
  26. */
  27. class AbstractDB_Driver
  28. {
  29. /* PRIVATE FIELDS */
  30. /**
  31. * List of connection and driver specific arguments.
  32. * @access private
  33. * @var array
  34. */
  35. var $_arguments;
  36. /**
  37. * Database connection handle.
  38. * @access private
  39. * @var resource
  40. */
  41. var $_connection;
  42. /**
  43. * The last error message.
  44. * @access private
  45. * @var string
  46. */
  47. var $_error;
  48.  
  49. /* PUBLIC PROPERTIES */
  50. /**
  51. * List of supported features of the currently loaded driver.
  52. * @access public
  53. * @var array
  54. */
  55. var $Support;
  56. /**
  57. * AbstractDB Driver Constructor
  58. *
  59. * Initilises an instance of the AbstractDB Driver base class.
  60. * @access public
  61. * @internal Stores the arguments parameter as a local field.
  62. * @param array $arguments A list of connection and driver specific arguments.
  63. * See {@link AbstractDB} for details concerning connection arguments.
  64. */
  65. function AbstractDB_Driver($arguments)
  66. {
  67. $this->ClearError();
  68. $this->_arguments = $arguments;
  69. }
  70.  
  71. /* PUBLIC FUNCTIONS */
  72. /**
  73. * Gets the Number of Affected Rows
  74. *
  75. * Gets the number of rows affected by the last query.
  76. * @access public
  77. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  78. *
  79. * If this feature is not supported an error should be set explaining this.
  80. * @return int Returns the number of rows affected by the last executed query.
  81. */
  82. function AffectedRows()
  83. {
  84. $this->ClearError();
  85. return 0;
  86. }
  87. /**
  88. * Closes the Database Connection
  89. * @access public
  90. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  91. *
  92. * If this feature is not supported this method should return a default value of true.
  93. * @return bool Returns true if the database connection was successfully closed, otherwise false.
  94. */
  95. function Close()
  96. {
  97. $this->ClearError();
  98. return false;
  99. }
  100. /**
  101. * Move a Result Pointer to the Specified Row
  102. * @access public
  103. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  104. *
  105. * If this feature is not supported an error should be set explaining this.
  106. * @param resource $rs A reference to a result handle returned by executing a query.
  107. * @param int $row_num The 0 based index of the row that the result pointer should move to.
  108. * @return bool Returns true if the operation was successful, otherwise false.
  109. */
  110. function DataSeek(&$rs, $row_num)
  111. {
  112. $this->ClearError();
  113. return false;
  114. }
  115. /**
  116. * Fetches a Result Row as an Associative Array
  117. * @access public
  118. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  119. *
  120. * If this feature is not supported an error should be set explaining this.
  121. * @param resource A reference to a resource handle returned by executing a query.
  122. * @return array Returns an associative array if the operation was successful, otherwise false.
  123. */
  124. function FetchAssoc(&$rs)
  125. {
  126. $this->ClearError();
  127. return false;
  128. }
  129. /**
  130. * Fetches the First Field Value
  131. *
  132. * Fetches the value from the first field of a result row.
  133. * @access public
  134. * @internal This method must be overriden in extended classes with a call to parent.
  135. * @param resource A reference to a resource handle returned by executing a query.
  136. * @return mixed Returns the field value if the operation was successful, otherwise false.
  137. */
  138. function FetchField(&$rs)
  139. {
  140. $this->ClearError();
  141. return false;
  142. }
  143.  
  144. /**
  145. * Fetches a Result Row as an Object
  146. * @access public
  147. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  148. *
  149. * If this feature is not supported an error should be set explaining this.
  150. * @param resource A reference to a resource handle returned by executing a query.
  151. * @return object Returns an object if the operation was successful, otherwise false.
  152. */
  153. function FetchObject(&$rs)
  154. {
  155. $this->ClearError();
  156. return false;
  157. }
  158. /**
  159. * Fetches a Result Row
  160. * @access public
  161. * @internal This method must be overriden in extended classes with a call to parent.
  162. * @param resource A reference to a resource handle returned by executing a query.
  163. * @return array Returns an array if the operation was successful, otherwise false.
  164. */
  165. function FetchRow(&$rs)
  166. {
  167. $this->ClearError();
  168. return false;
  169. }
  170. /**
  171. * Gets the Number of Fields
  172. *
  173. * Gets the number of fields returned by given result handle.
  174. * @access public
  175. * @internal This method must be overriden in extended classes with a call to parent.
  176. * @param resource $rs A reference to a resource handle returned by executing a query.
  177. * @return int Returns the number of fields returned by the last executed query.
  178. */
  179. function FieldCount(&$rs)
  180. {
  181. $this->ClearError();
  182. return 0;
  183. }
  184. /**
  185. * Gets the Field Names of a Query
  186. * @access public
  187. * @internal This method must be overriden in extended classes with a call to parent.
  188. * @param resource $rs A reference to a resource handle returned by executing a query.
  189. * @param array $fields A reference to an array that will contain the field names.
  190. * @return bool Returns true if the operation was successful, otherwise false.
  191. */
  192. function FieldNames(&$rs, &$fields)
  193. {
  194. $this->ClearError();
  195. return false;
  196. }
  197. /**
  198. * Frees a Result Resource
  199. *
  200. * Frees the resources associated with the given result handle.
  201. * @access public
  202. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  203. *
  204. * If this feature is not supported the method should return a default value of true.
  205. * @param resource A reference to a resource handle returned by executing a query.
  206. * @return bool Returns true if the resource handle was successfully freed.
  207. */
  208. function FreeResult(&$rs)
  209. {
  210. $this->ClearError();
  211. return true;
  212. }
  213. /**
  214. * Gets the Last Error.
  215. * @access public
  216. * @return string The last error message.
  217. */
  218. function GetLastError()
  219. {
  220. return $this->_error;
  221. }
  222. /**
  223. * Gets the Last Inserted AUTO_INCREMENT ID
  224. *
  225. * Gets the ID of the last AUTO_INCREMENT record inserted into the databse.
  226. * @access public
  227. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  228. *
  229. * If this feature is not supported an error should be set explaining this.
  230. * @return mixed Returns either the ID of the last inserted AUTO_INCREMENT record, or -1 if the
  231. * last query was not an insert.
  232. */
  233. function InsertID()
  234. {
  235. $this->ClearError();
  236. return -1;
  237. }
  238. /**
  239. * Executes an SQL Statement.
  240. *
  241. * Executes an SQL statement passed in as a parameter.
  242. * @access public
  243. * @internal This method must be overriden in extended classes or it will cause
  244. * the script to exit.
  245. *
  246. * If the query fails an error should be set that explains as best as possible the
  247. * reason for the query failure.
  248. * @param string $sql The SQL statement to execute on the database.
  249. * @return resource If the query was successful, the result handle of the query
  250. * used in result fetching functions, otherwise false.
  251. */
  252. function Query($sql)
  253. {
  254. die("Method AbstractDB_Driver::Query() must be redefined in extended classes without calling parent.");
  255. }
  256. /**
  257. * Executes an SQL Replace Query
  258. * @access public
  259. * @internal This method must be overriden in extended classes with a call to parent if this feature is supported.
  260. *
  261. * If this feature is not supported an error should be set explaining this.
  262. * @param string $table The name of the table to execute the replace query on.
  263. * @param array $fields An associative array of field definitions. Keys should be the field names and
  264. * values should be an associative array containing the following keys:
  265. *
  266. * Key => bool indicating that this field is the primary key or part of a unique index. Key values must not be NULL.
  267. *
  268. * Type => either "text", "numeric", "bool".
  269. *
  270. * Value => the value of the field.
  271. *
  272. * Null => bool indicating if the value of the field should be set to NULL.
  273. *
  274. * e.g. $fields = array("Field1" => array("Key" => true, "Type" => "numeric", "Value" => 123, "Null" => false));
  275. * @return resource If the replace query was successful, the result handle of the query, otherwise false.
  276. */
  277. function Replace($table, $fields)
  278. {
  279. $this->ClearError();
  280. return false;
  281. }
  282. /**
  283. * Gets the Number of Rows
  284. *
  285. * Gets the number of rows returned by given result handle.
  286. * @access public
  287. * @internal This method must be overriden in extended classes with a call to parent.
  288. * @param resource $rs A reference to a resource handle returned by executing a query.
  289. * @return int Returns the number of fields returned by the last executed query.
  290. */
  291. function RowCount(&$rs)
  292. {
  293. $this->ClearError();
  294. return 0;
  295. }
  296. /**
  297. * Sets the Current Active Database
  298. * @access public
  299. * @internal This method must be overriden in extended classes with a call to parent.
  300. *
  301. * If this operation fails an error should be set explaining as best as possible the reason for the failure.
  302. * @param string $dbName The name of the database to set active.
  303. * @return mixed The name of the previously active database, or false if an error occured.
  304. */
  305. function SetDatabase($dbName)
  306. {
  307. $this->ClearError();
  308. return false;
  309. }
  310. /* PRIVATE FUNCTIONS */
  311. /**
  312. * Clears the latest error message.
  313. * @access private
  314. */
  315. function ClearError()
  316. {
  317. $this->_error = "";
  318. }
  319. /**
  320. * Opens a Database Connection
  321. *
  322. * Attempts to connect to the database using the parameters given in the constructor.
  323. * @access private
  324. * @internal This method must be overriden in extended classes or it will cause
  325. * the script to exit.
  326. *
  327. * The _connection field should be set to hold the resource link.
  328. *
  329. * If the connection fails an error should be set that explains as best as possible the
  330. * reason for the connection failure.
  331. * @return bool Returns true if the connection was successfully made, otherwise false.
  332. */
  333. function Connect()
  334. {
  335. die("Method AbstractDB_Driver::Connect() must be redefined in extended classes without calling parent.");
  336. }
  337.  
  338. /**
  339. * Sets the Error Message
  340. * @access private
  341. * @param string $scope The scope of the error, generally the function in which it occured.
  342. * @param string $message The actual error message.
  343. */
  344. function SetError($scope, $message)
  345. {
  346. $this->_error = "$scope: $message";
  347. }
  348. }
  349. ?>

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