Dbal.sql connect
From phpBB Development Wiki
dbal::connect –– Open a new connection to the Selected DBAL Database server
Contents |
Description
-
object dbal::sql_connect ( String $host, String $username, String $passwd, String $dbname [, int $port [, bool $persistency [, bool $new_link ]]] )
The $db->sql_connect function creates a link to the selected DBAL driver database. phpBB3 automatically handles error reporting, therefore manual error handling is not needed in phpBB3.
Parameters
| Parameter | Usage |
|---|---|
| host | The host of the database. When using config.php you should use $dbhost. Can be either a host name or an IP address. Passing the NULL value or the string "localhost" to this parameter, the local host is assumed. When possible, pipes will be used instead of the TCP/IP protocol. |
| username | The database user (username) to connect to the database. When using config.php you should use $dbuser. |
| passwd | The password for the user to connect to the database. When using config.php you should use $dbpasswd. |
| dbname | The database where the tables you want to query are located. When using config.php you should use $dbname. |
| port | (optional) Specifies the port number to attempt to connect to the database. Leave empty/false to use the default port. When using config.php you should use $dbport |
| persistency | (optional) Database connection persistence, defaults to false. Used by all DBAL drivers except for MySQLi. |
| new_link | (optional) Use a new connection to the database for this instance of the DBAL. Defaults to false. |
Return Values
Returns a object which represents the connection to a MySQL Server.
Examples
Example #1 Creating a Database Link from config data
In this example, the config.php file is used for the correct parameters to connect to the database. The parameters are the same as noted above. The unset is used to be sure that the $dbpasswd can not be stolen later in the script.
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
include($phpbb_root_path . 'config.' . $phpEx);
include($phpbb_root_path . 'includes/db/' . $dbms . '.' . $phpEx);
$db = new $sql_db();
$db->sql_connect($dbhost, $dbuser, $dbpasswd, $dbname, $dbport);
// We do not need this any longer, unset for safety purposes
unset($dbpasswd);
Example #2 Creating a Database Link manually
In this example the config.php file isn't used. All data is directly passed to the sql_connect function to illustrate the system.
define('IN_PHPBB', true);
$phpbb_root_path = './';
$phpEx = substr(strrchr(__FILE__, '.'), 1);
$dbms = 'mysql';
include($phpbb_root_path . 'includes/db/' . $dbms . '.' . $phpEx);
$db = new $sql_db();
$db->sql_connect('localhost', 'my_user', 'my_password', 'phpbb', '');
Notes
Initialising a Connection
To use the functions of the DBAL class, you need to instantiate the DBAL class and create a connection. Before you can do so, you need to include the correct DBAL driver from /includes/db/.
Using a DBAL driver
The variable $dbms must be set to the name of the used driver. This variable is needed in /includes/db/dbal.php to set $sql_db.
Using $dbms from config
If you use the variable $dbms from config.php, you can use $sql_db to instantiate the class.
Automatically instantiating the DBAL
If you include common.php the DBAL is automatically instantiated and initialised, so you don't need to instantiate it manually. The object is called $db.
See Also
