Differences

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

--- reference:adonewconnection [2015/07/26 16:20] – created mnewnham
+++ v5:reference:connection:adonewconnection [2020/12/08 10:39] (current) – better use PHP string concatenation for example instead of javascript's ;-) peterdd
@@ Line 1: / Line 1: @@
 ====== adoNewConnection ======
 ~~NOTOC~~
-<WRAP alert>
-Not passing a driver name as the parameter to this function does nothing but return an error. This behavior will be removed in version 6.0.0.
-</WRAP>
 <WRAP right box>
-== Syntax before version 6.0.0 ==
+== Syntax ==
   mixed adoNewConnection(
       optional string $driverType=''
   )
-== Syntax version 6.0.0 ==
-  mixed adoNewConnection(
-      string $driverType
-  )
 </WRAP>
 ===== Description =====
-The function adoNewConnection, in the simple form, loads the database driver specific files as specified by the string '' $driverType ''.
+The function adoNewConnection, in the simple form, loads the database driver specific files as specified by the string '' $driverType''. The driver name must match the name of a file '' adodb-**$driverType**-inc.php'' in the '' adodb/drivers'' directory. As there is no 'master list' of drivers, the driver can be named anything, it's existence in this directory is the only way of checking it's validity. This simplicity makes it easy to create a new driver.
+===== Passing a connection DSN =====
+In addition to the simple form, a DSN connection string can be passed to any database that supports that connection type. The ''$driverType'' string must be in the following format:
+**
+<nowiki>
+"valid driver name" + "://" + "standard DSN string"
+</nowiki>
+**
+If the DSN string parses correctly, an attempt is made to automatically connect to the database. If the connection succeeds, then there is no need to issue a [[v5:reference:connection:connect|connect()]] statement.
+===== Usage =====
+==== Simple Usage ====
+<code php>
+include 'adodb.inc.php';
+/*
+* Simple connection
+*/
+$driver = 'mysqli';
+$db     = adoNewConnection($driver);
+/*
+* Now connect to the database
+*/
+$db->connect('localhost','user','password','employees');
+</code>
+==== DSN Usage ====
+<code php>
+include 'adodb.inc.php';
+/*
+* Set DSN
+*/
+$driver = 'mysqli';
+$DSN    = "user:password@localhost/employees";
+$db     = adoNewConnection($driver . '://' . $DSN);
+/*
+* Now connected
+*/
+</code>
+===== Additional Parameters To DSN connection ====
+The following additional parameter can be added to the DSN connection string. Some of the parameters only work with specific drivers.
+^ Code              ^ Driver             ^ Value                                      ^ Parameter                                        ^ Description                                                          ^
+| new               |                    | true                                       | [[v5:reference:connection:nconnect|nConnect()]]  | Forces a new connection                                              |
+| persist           |                    | true                                       | [[v5:reference:connection:pconnect|pConnect()]]  | Creates a persistent connection                                      |
+| persistent        |                    | true                                       | [[v5:reference:connection:pconnect|pConnect()]]  | Creates a persistent connection                                      |
+| debug             |                    | true| [[v5:userguide:debug|debug]]                                                            | Enables debug mode                                                   |
+| port              | mysqli, postgres9  | int   |                                                                                       | Sets the connection port                                             |
+| socket            | mysqli             | string |                    | Sets the connection socket |
+| nls_date_format   | oci8               | string |                    | Set date format            |
+| cachesecs         |                    | int    |                                                                                      | Sets the number of cache seconds                                     |
+| memCache          |                    | false |[[v5:userguide:memcached|memcache]]                                                    | Enables memcache library for caching                                 |
+| memCacheHost      |                    | array |[[v5:userguide:memcached|memcache]]                                                    | Array of one or more memcached servers                               |
+| memCachePort      |                    | int   |[[v5:userguide:memcached|memcache]]                                                      | Optional alternative port to connect to memcache server(s)           |
+| memCacheCompress  |                    | false |[[v5:userguide:memcached|memcache]]                                                    | Enables memcache compression (not supported with memcached library)  |
+===== Error Codes =====
+Note that, because no connection object is available, the codes cannot be retrieved via [[v5:reference:connection:errormsg|errorMsg()]]