Differences

This shows you the differences between two versions of the page.

--- reference:extending [2015/07/18 18:52] – created mnewnham
+++ v5:userguide:learn_extensions:new_driver [2020/01/15 04:13] (current) – mnewnham
@@ Line 1: / Line 1: @@
-====== Building Extensions ======
+<-  ^ v5:userguide:userguide_index|List Of Tutorials ^ v5:learn_extensions:extend_existing:modify_existing_driver|Modifying An Existing Driver ->
-You might want to modify ADOdb for your own purposes. Luckily you can still maintain backward compatibility by sub-classing ADOdb and using the ''$ADODB_NEWCONNECTION'' variable. ''$ADODB_NEWCONNECTION'' allows you to override the behaviour of ADONewConnection(). ADOConnection() checks for this variable and will call the function-name stored in this variable if it is defined.
+~~NOTOC~~
+====== Creating A New Driver ======
+The simplest way to extend ADOdb for your own use is to create a new driver. ADOdb behaves like all PHP class definitions, in that its class methods and variables can be extended. As an example, we can look at the ADOdb driver **/drivers/adodb-odbc-mssql2012.inc.php**
-In the following example, new functionality for the connection object is placed in the _hack_mysql_ and _hack_postgres7_ classes. The recordset class naming convention can be controlled using $rsPrefix. Here we set it to 'hack_rs_', which will make ADOdb use _hack_rs_mysql_ and _hack_rs_postgres7_ as the recordset classes.
+This driver was created because the behaviour of Microsoft SQL Server 2012 differs slightly from previous versions when connecting via an ODBC connection.
+The driver, in it's entirety, looks like this:
 <code php>
-class hack_mysql extends adodb_mysql {
+/**
+*  Microsoft SQL Server 2012 via ODBC
+*/
-var $rsPrefix = 'hack_rs_';
+if (!defined('ADODB_DIR'))
+	die();
-  /* Your mods here */
+include_once(ADODB_DIR."/drivers/adodb-odbc_mssql.inc.php");
-}
+class  ADODB_odbc_mssql2012 extends ADODB_odbc_mssql
+{
+	/*
+	* Makes behavior similar to prior versions of SQL Server
+	*/
+	var $connectStmt = 'SET CONCAT_NULL_YIELDS_NULL ON';
+}
-class hack_rs_mysql extends ADORecordSet_mysql {
+class  ADORecordSet_odbc_mssql2012 extends ADORecordSet_odbc_mssql
+{
+}
+</code>
- /* Your mods here */
+  * Both the connection and recordset classes must be defined, even if they are not modified
+  * The driver **must** be located in the ADODB_DIR directory. Take care that the driver is not lost when upgrading
+  * No other action is required, simply enter the name of the new driver in the newAdoConnection() statement.
-}
+===== Understanding The Data Provider =====
+Because ADOdb V5 is not truly Object Orientated, an extended driver does not necessarily extend the required parent. One might expect to see the following chain of code:
-class hack_postgres7 extends adodb_postgres7 {
+<code php>
-var $rsPrefix = 'hack_rs_';
+class ADOnewConnection
+class mysql extends ADOnewConnection
+class mysqli extends mysql
-  /* Your mods here */
+</code>
+But if we look at the source code of the [[v5:database:mysql|mysqli]] driver (**drivers/adodb-mysqli.inc.php**) , we can see that the class is defined like this
-}
+<code php>
-class hack_rs_postgres7 extends ADORecordSet_postgres7 {
+class ADODB_mysqli extends ADOConnection {
+	var $databaseType = 'mysqli';
+	var $dataProvider = 'mysql';
- /* Your mods here */
+</code>
-}
+So the class extends the connector, but much of the MySQL specific functionality is found in the **//provider//** (**drivers/adodb-mysql.inc.php**). The **provider** is effectively a parallel class. So if we wanted, for example, to create a new driver //**mydriver**// that did not directly extend an existing class, but shared much of the feature with say, the [[v5:database:microsoft_sql_server|mssqlnative]] class, our code might look like:
-$ADODB_NEWCONNECTION = 'hack_factory';
+<code php>
+class ADODB_mydriver extends ADOConnection {
+	var $databaseType = 'mydriver';
+	var $dataProvider = 'mssqlnative';
-function& hack_factory($driver)
+</code>
+===== Base Level Classes =====
+If we look at say, the [[v5:database:microsoft_sql_server|mssqlnative]] class, (**drivers/adodb-mssqlnative.inc.php**). we see the following:
-{
+<code php>
+class ADODB_mssqlnative extends ADOConnection {
+	var $databaseType = 'mssqlnative';
+	var $dataProvider = 'mssqlnative';
-         if ($driver !== 'mysql' && $driver !== 'postgres7') return false;
+</code>
+In this case, the **$databaseType** and the **$dataProvider** are the same. This means that all of the functionality of the driver is provided by the named driver (**drivers/adodb-mssqlnative.inc.php**) and datadict (**datadict/datadict-mssqlnative.inc.php**) files .
-         $driver = 'hack_'.$driver;
+===== Using Provider Classes =====
+Data Provider classes are designed exactly the same as database driver classes. Where the provider class is different from the database class, the provider class is generally associated with an obsolete database version, often 15-20 years old. As such, they cannot be used as drivers.
-         $obj = new $driver();
-         return $obj;
-}
-include_once('adodb.inc.php');
-</code>