PHPerKaigi 2024

PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct 创建一个表示数据库连接的 PDO 实例

说明

public PDO::__construct(
    string $dsn,
    ?string $username = null,
    ?string $password = null,
    ?array $options = null
)

创建一个表示连接到请求数据库的数据库连接 PDO 实例。

参数

dsn

数据源名称或叫做 DSN,包含了请求连接到数据库的信息。

通常,一个 DSN 由 PDO 驱动名、紧随其后的冒号、以及具体 PDO 驱动的连接语法组成。更深入的信息能从 PDO 具体驱动文档找到。

dsn 参数支持三种不同的方式 创建一个数据库连接:

驱动程序调用

dsn 包含完整的DSN。

URI invocation

dsnuri: 后跟 URI 组成,该 URI 包含定义 DSN 字符串的文件位置。URI 可以指定本地文件或远程 URL。

uri:file:///path/to/dsnfile

Aliasing

dsn 由映射到 php.ini 中定义 DSN 字符串的 pdo.dsn.namename 名组成。

注意:

别名必须得在 php.ini 中定义了,不能是在 .htaccesshttpd.conf 中 。

username

DSN字符串中的用户名。对于某些PDO驱动,此参数为可选项。

password

DSN字符串中的密码。对于某些PDO驱动,此参数为可选项。

options

一个具体驱动的连接选项的键=>值数组。

错误/异常

如果试图连接到请求的数据库失败,无论当前设置了哪个 PDO::ATTR_ERRMODEPDO::__construct() 抛出 PDOException

示例

示例 #1 通过驱动程序调用创建 PDO 实例

<?php
/* Connect to a MySQL database using driver invocation */
$dsn = 'mysql:dbname=testdb;host=127.0.0.1';
$user = 'dbuser';
$password = 'dbpass';

$dbh = new PDO($dsn, $user, $password);

?>

示例 #2 通过 URI 调用创建 PDO 实例

The following example assumes that the file /usr/local/dbconnect exists with file permissions that enable PHP to read the file. The file contains the PDO DSN to connect to a DB2 database through the PDO_ODBC driver:

odbc:DSN=SAMPLE;UID=john;PWD=mypass

PHP 脚本可以简单的传递指向文件 URI 的 uri: 参数来创建数据库连接:

<?php
/* Connect to an ODBC database using driver invocation */
$dsn = 'uri:file:///usr/local/dbconnect';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>

示例 #3 使用别名创建一个PDO实例

The following example assumes that php.ini contains the following entry to enable a connection to a MySQL database using only the alias mydb:

[PDO]
pdo.dsn.mydb="mysql:dbname=testdb;host=localhost"
<?php
/* 使用别名连接到 ODBC 数据库 */
$dsn = 'mydb';
$user = '';
$password = '';

$dbh = new PDO($dsn, $user, $password);

?>

add a note

User Contributed Notes 16 notes

up
124
Kiipa at live dot com
10 years ago
To get UTF-8 charset you can specify that in the DSN.

$link = new PDO("mysql:host=localhost;dbname=DB;charset=UTF8");
up
4
theking2 at king dot ma
1 year ago
A generic pattern to connect to a mariadb or mysql database using a settings file

<?php
$_SETTINGS
= parse_ini_file('./settings.ini', true);

$db = new \PDO(
"mysql:hostname={$_SETTINGS['db']['host']};dbname={$_SETTINGS['db']['name']}",
$_SETTINGS['db']['user'],
$_SETTINGS['db']['pass'],
[
\PDO::ATTR_DEFAULT_FETCH_MODE => \PDO::FETCH_ASSOC,
\PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES 'utf8mb4'"
]
);
?>
You might not need the options depicted here but I find them convenient.

Works with a settings.ini file containing for instance:
[db]
host = "localhost"
name = "dbname"
user = "dbuser"
pass = "dbpassword"
up
40
subme at interia dot pl
15 years ago
To specify a database connection port use the following DSN string

<?php
$dsn
= 'mysql:dbname=testdb;host=127.0.0.1;port=3333';
?>
up
7
Aymeric S
3 years ago
When trying to connect to a local database, it seems "uri:file:///" is no longer needed. Just write the PDO pilot name followed by the absolute path of the file.
Example : sqlite:C:\VirtualHosts\phpliteadmin\dbs\surveillance_logeas.s3DB
up
29
piotrekkr at o2 dot pl
13 years ago
To connect throught unix socket you need to use
<?php
$dsn
= 'mysql:dbname=testdb;unix_socket=/path/to/socket';
?>

You musn't specify host when using socket.
up
21
daviddlavier at gmail dot com
8 years ago
I'd like to point out that in PHP 7.0 in the dsn parameter you can't use 'host=localhost' to solve this you can use 'host=127.0.0.1' instead.
up
2
Michal Stefanak
1 year ago
If you override PDO with own class and you want to implement alias from php.ini, you have to get it with `get_cfg_var` instead of `ini_get`.

<?php
class PDO extends \PDO
{
public function
__construct(string $dsn, ?string $username = null, ?string $password = null, ?array $options = null)
{
//alias
if (!str_contains($dsn, ':')) {
$dsn = get_cfg_var('pdo.dsn.' . $dsn);
if (!
$dsn) {
throw new
PDOException('Argument #1 ($dsn) must be a valid data source name');
}
}

// your additional logic

parent::__construct($dsn, $username, $password, $options);
}
}
?>
up
8
Francesco Montanari
3 years ago
Most of the information in the comment here is outdated or wrong.

You do can use host=localhost to connect via socket, which is faster than TCP, so setting 127.0.0.1 is a performance loss.

To use proper utf you should use utf8mb4, for example:

$db = new PDO('mysql:host=' . DATABASE_HOST . ';dbname='. DATABASE_NAME .';charset=utf8mb4', DATABASE_USER, DATABASE_PASSWORD);
up
13
Victor T.
14 years ago
If you use the UTF-8 encoding, you have to use the fourth parameter :

<?php
$db
= new PDO('mysql:host=myhost;dbname=mydb', 'login', 'password', array(PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES \'UTF8\''));
?>
up
0
max1josef
9 months ago
SQLite3: by default, the database file is created on opening if it does not exist (PDO::SQLITE_OPEN_CREATE).

<?php
$dsn
= 'sqlite:D:\Databases\non_existing.db'; // file does not exist

try {
$dbh = new PDO($dsn);
}
catch(
PDOException $e) {
print
$e->getMessage();
}
?>

No Exception is thrown, instead file "non_existing.db" will be created. To avoid this, use:

<?php
$dsn
= 'sqlite:D:\Databases\non_existing.db';
$options = [
PDO::SQLITE_ATTR_OPEN_FLAGS => PDO::SQLITE_OPEN_READWRITE,
];

try {
$dbh = new PDO('sqlite:D:\Databases\non_existing.db', null, null, $options);
}
catch(
PDOException $e) {
print
$e->getMessage();
}
?>
This will ouput:
SQLSTATE[HY000] [14] unable to open database file

If you want to open the database read-only, use PDO::SQLITE_OPEN_READONLY.
up
0
Anonymous
10 years ago
Sqlite:

<?php
try{
$pdo = new PDO('sqlite:example.db');
}catch (
PDOException $e){
die (
'DB Error');
}
?>

If 'example.db' does not exist, no exception is thrown but the file 'example.db' is created.
up
-1
ohcc at 163 dot com
8 years ago
You will get a fatal error if you don't catch the exception threw by PDO when it fails to connect to the database server like this.

Fatal error: in xxx.php on line xx

This error neither can be handled by error handlers nor can it be erased by the @ sign, which can make your script uncontrollable.

<?php
$db
= new pdo('mysql:host=127.0.0.1;port=3306;dbname=mysql;charset=utf8','user','password',array(
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
));
?>

You should always try ... catch ...

<?php
try{
$db = new pdo('mysql:host=127.0.0.1;port=3306;dbname=mysql;charset=utf8','user','password',array(
PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
));
}catch(
PDOException $pe){
echo
$pe->getMessage();
}
?>
up
-1
453034559 at qq dot com
2 years ago
// set DEFAULT_FETCH_MODE
<?php
try {
$p = new PDO("mysql:host=$db_host;port=$db_port;dbname=$db_dbname", $db_user, $db_pass,array(
PDO::ATTR_DEFAULT_FETCH_MODE =>PDO::FETCH_ASSOC,
PDO::MYSQL_ATTR_INIT_COMMAND => 'SET NAMES utf8', //after php5.3.6
));
//$p->exec('SET NAMES utf8');
} catch (PDOException $e) {
print
"Error!: " . $e->getMessage() . "<br/>";
die();
}
?>
up
-3
berk0081 at umn dot edu
9 years ago
Although not explicitly stated, parameters in the PDO $dsn string may be case-sensitive on some platforms or drivers.

<?php
// The dbname will not be parsed with incorrect casing:
$pdo = new PDO("mysql:host=hostname;DBName=database", "user", "password");

// The correct dbname is lowercase, as displayed in the manual:
$pdo = new PDO("mysql:host=hostname;dbname=database", "user", "password");
?>
up
-9
srycroft at excelsystems dot com
7 years ago
For IBM i / iSeries / AS400 DB2 connections, you can specify system naming and library lists for php_pdo modules > 1.3.3-sg2

<?php
$pdo
= new PDO(
'ibm:' . $host,
$user,
$password,
array(
PDO::I5_ATTR_DBC_SYS_NAMING => true,
PDO::I5_ATTR_DBC_LIBL => "QGPL QSYS"
)
);
?>

See http://yips.idevcloud.com/wiki/index.php/XMLSERVICE/PHPPDOChangeLog
up
-30
olivernybroe at gmail dot com
7 years ago
The PDO connection is case-sensitive, this means that you cannot write
`$PDO = new PDO("MySQL:DBName=dbname;host=localhost");`
You would have to write it
`$PDO = new PDO("mysql:dbname=dbname;host=localhost");`

The difference here is that `mysql` and `dbname` is with all lower-case.

Some IDE's like PHPStorm will show a `TYPO ERROR`, at `dbname` if it's written with lower-case only, this is just to be ignored and have been reported to PHPStorm for them to fix. (Currrent version 10.0.2)
To Top