phpBB

Development Wiki

Dbal.sql connect

From phpBB Development Wiki

dbal::connect –– Open a new connection to the Selected DBAL Database server

Description

  1. 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