<head><title>DB Connection implementation guide</title></head>
<html>
<body>
<h1>Introduction</h1>
<p>This guide describes how you can add support to other databases to DbConnection / PersistClass. To see an existing implementation, check DbConnectionMysql.php</p>
<h1>The abstract DbConnection class</h1>
<h2>Responsibilities</h2>
<p>
Objects of this class are responsible for holding and managing a database connection and the resultset of the last executed query. It provides an abstraction layer that allows any database system to be used in the same way.
</p>
<h2>Attributes<h2>
<p>
The base class defines the following attributes:
<ul>
<li><b>$link</b>: Database link</li>
<li><b>$result</b>: ResultSet object (containing the results of the previous query)</li>
<li><b>$numRows</b>: Containing the number of returned rows or the number of updated/deleted rows of the previous query</li>
</ul>
</p>
<h2>Methods</h2>
<p>
This class declares the following methods that will need to be implemented:
<ul>
<li><b>query($q)</b>: Executes an SQL query.</li>
<li><b>next()</b>: returns next row from the resultset as an associative array</li>
<li><b>getLastId()</b>: returns the ID of the last inserted row</li>
<li><b>closeConnection()</b>: closes database connection</li>
<li><b>getLastId()</b>: returns the primary key of the last inserted row</li>
<li><b>cloneConnection()</b>: creates a new DbConnection object by reusing the existing database connection</li>
<li><b>escape($string, $quoted = true)</b>: escapes a string value and wraps them into quotes (optional)</li>
<li><b>startTransaction()</b>: starts transaction</li>
<li><b>commit()</b>: commits transaction</li>
<li><b>rollBack()</b>: rolls back transaction</li>
</ul>
</p>
<h1>Implementation</h1>
<h2>Construction & connection</h2>
<p>
The object has to be responsible for opening a database connection. Throws ConnectionException if it fails to do so. The DbConnectionMysql does that with its connect() method. (not in constructor, makes "cloning" easier in cloneConnection)
</p>
<h2>Additional method implementation requirements</h2>
<p>
<li><b>query($q)</b>: Executes an SQL query. Puts number of affected rows into numRows and returns it. Throws ConnectionException if there is a connection error, throws QueryException in case of an SQL query error.</li>
<li><b>next()</b>: Returns next row from the recordset as an associative array. Returns null if there are no more rows.</li>
<li><b>getLastId()</b>: Optional. Only implement for databases that support auto-increment</li>
</p>
</body>
</html> |