虚谷文档 v1.0.1

适用虚谷数据库版本

v12.9



适用虚谷数据库版本

v12.9


PDO 接口 ​

PDO 类 ​

__construct ​

功能

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

原型

PHP
PDO::__construct(
    string $dsn,
    ?string $username = null,
    ?string $password = null,
    ?array $driver_options = null
)

参数

  • $dsn：数据源名称，包含了请求连接到数据库的信息
    • ip：数据库服务端的 IP 地址
    • ips：多个 IP 地址，用逗号分隔
    • port：数据库端口号
    • db：连接的数据库名
    • user：登录的用户名
    • pwd：用户对应的密码
    • char_set：字符集
    • auto_commit：自动提交，取值为 on 或 off
    • use_srvcursor：使用服务端游标，取值为 on 或 off
    • usessl：开启数据传输加密，取值为 on 或 off
  • $username：DSN 字符串中的用户名
  • $password：DSN 字符串中的密码
  • $driver_options：一个具体驱动的连接选项的键值数组

返回值

成功则返回一个PDO对象。

异常

如果未能成功连接到请求的数据库，则 PDO::__construct() 抛出一个 PDO异常（PDOException）。

示例

PHP
try {
    $pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM;", "SYSDBA", "SYSDBA");
    echo 'PDO 对象创建成功';
} catch (PDOException $e) {
    echo $e->getMessage();
}

eginTransaction ​

功能

开启事务。

原型

PHP
PDO::beginTransaction(): bool

返回值

成功时返回 true， 失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");
$res = $pdo->beginTransaction();
if($res)
    echo '事务开启成功';
else
    echo '事务开启失败';

commit ​

功能

提交事务。

原型

PHP
PDO::commit(): bool

返回值

成功时返回 true， 失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");
$pdo->beginTransaction();

$pdo->exec("INSERT INTO tab_test (name) VALUES('Tom')");

$res = $pdo->commit();
if($res)
    echo '事务提交成功';
else
    echo '事务提交失败';

rollBack ​

功能

回滚事务。

原型

PHP
PDO::rollBack(): bool

返回值

成功时返回 true， 失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");
$pdo->beginTransaction();

$pdo->exec("INSERT INTO user (name) VALUES('Jerry')");

$res = $pdo->rollBack();
if($res)
    echo '事务回滚成功';
else
    echo '事务回滚失败';

errorCode ​

功能

获取上一次操作相关的错误码。

原型

PHP
PDO::errorCode(): mixed

返回值

返回一个 SQLSTATE，一个由5个字母或数字组成的在 ANSI SQL 标准中定义的标识符。如果数据库句柄没有进行操作，则返回 null。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

try {
    $pdo->exec("This is a wrong sql");
} catch(PDOException $e) {
}

echo $pdo->errorCode();

errorInfo ​

功能

获取上一次操作相关的错误信息。

原型

PHP
PDO::errorInfo(): array

返回值

上一次操作的错误信息。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

try {
    $pdo->exec("This is a wrong sql");
} catch(PDOException $e) {
}

print_r($pdo->errorInfo());

exec ​

功能

执行一条 SQL 语句，并返回受影响的行数。

原型

PHP
PDO::exec(string $statement): int

参数

  • $statement：被执行的 SQL 语句

返回值

受影响的行数。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$res = $pdo->exec("INSERT INTO tab_test (name) VALUES('Tom')('Jerry')");

echo $res; // $res 值为 2

getAttribute ​

功能

获取一个数据库连接的属性。

原型

PHP
PDO::getAttribute(int $attribute): mixed

参数

  • $attribute：取 PDO::ATTR_* 常量中的一个，参见附录

返回值

成功调用则返回请求的 PDO 属性值，不成功则返回 null。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$attr = $pdo->getAttribute(PDO::ATTR_AUTOCOMMIT);

echo $attr;

getAvailableDrivers ​

功能

返回一个可用驱动的数组。

原型

PHP
static PDO::getAvailableDrivers(): array

返回值

包含可用 PDO 驱动名字的数组。如果没有可用的驱动，则返回空数组。

示例

PHP
print_r(PDO::getAvailableDrivers());

inTransaction ​

功能

检查是否在一个事务内。

原型

PHP
PDO::inTransaction(): bool

返回值

如果当前事务处于激活，则返回 true，否则返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");
$pdo->beginTransaction();

$res = $pdo->inTransaction();
echo $res; // true

lastInsertId ​

功能

返回最后插入行的ID或序列值。

原型

PHP
PDO::lastInsertId(string $name = null): string

参数

  • $name：返回 ID 的那个序列对象的名称

返回值

行的 rowid。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$pdo->exec("INSERT INTO tab_test (name) VALUES('Tom')");

$id = $pdo->lastInsertId();
echo $id;

prepare ​

功能

准备要执行的语句，并返回语句对象。

原型

PHP
PDO::prepare(string $statement, array $driver_options = array()): PDOStatement

参数

  • $statement：必须是对目标数据库服务器有效的 SQL 语句模板
  • $driver_options：数组包含一个或多个键值对，为返回的 PDOStatement 对象设置属性

返回值

如果数据库服务器成功准备了语句，PDO::prepare 返回 PDOStatement 对象。 如果数据库服务器无法准备语句，PDO::prepare 抛出 PDOException。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

try {
    $stmt = $pdo->prepare("INSERT INTO tab_test (name) VALUES(?)");
    echo '准备语句成功';
} catch (PDOException $e) {
    echo '准备语句失败，原因：' . $e->getMessage();
}

query ​

功能

执行 SQL 语句，以 PDOStatement 对象形式返回结果集。

原型

PHP
PDO::query(string $statement): PDOStatement

参数

  • $statement：SQL 语句

返回值

返回 PDOStatement 对象，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->query("SELECT * FROM tab_test");

foreach ($stmt as $row) {
    print_r($row);
}

quote ​

功能

为 SQL 查询里的字符串添加引号。

原型

PHP
PDO::quote(string $string, int $parameter_type = PDO::PARAM_STR): string

参数

  • $string：要添加引号的字符串
  • $parameter_type：为驱动提示数据类型，以便选择引号风格

返回值

返回加引号的字符串，可以安全用于 SQL 语句。若失败，则返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$str = "php string";

echo $pdo->quote($str);

setAttribute ​

功能

设置属性。

原型

PHP
PDO::setAttribute(int $attribute, mixed $value): bool

参数

  • $attribute：取 PDO::ATTR_** 常量中的一个，参见附录
  • $value：属性值

返回值

成功时返回 true，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$res = $pdo->setAttribute(PDO::ATTR_AUTOCOMMIT, false);
if ($res)
    echo '参数设置成功';
else 
    echo '参数设置失败';

PDOStatement 类 ​

bindColumn ​

功能

绑定一个 PHP 变量到结果集的一列。

原型

PHP
PDOStatement::bindColumn(
    mixed $column,
    mixed &$param,
    ?int $type = PDO::PARAM_STR,
    ?int $maxlen = 0,
    ?mixed $driverdata = null
): bool

参数

  • $column：结果集中的列号（从1开始）或列名。如果使用列名，注意名称应该与由驱动返回的列名大小写保持一致
  • $param：将绑定到列的 PHP 变量名称
  • $type：通过 PDO::PARAM_* 常量指定的参数的数据类型
  • $maxlen：预分配提示
  • $driverdata：驱动的可选参数

返回值

成功时返回 true，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

$stmt->bindColumn(1, $id);
$stmt->bindColumn("NAME", $name);

while($stmt->fetch())
    echo "$id, $name" . PHP_EOL;

bindParam ​

功能

绑定一个参数到指定的变量名。

原型

PHP
PDOStatement::bindParam(
    mixed $parameter,
    mixed &$variable,
    ?int $data_type = PDO::PARAM_STR,
    ?int $length = 0,
    ?mixed $driver_options = null
): bool

参数

  • $parameter：参数标识符。对于使用命名占位符的预处理语句，应是类似 :name 形式的参数名。对于使用问号占位符的预处理语句，应是以 1 开始索引的参数位置
  • $variable：绑定到 SQL 语句参数的 PHP 变量名
  • $data_type：使用 PDO::PARAM_* 常量明确地指定参数的类型。要从一个存储过程中返回一个 INOUT 参数，需要为 data_type 参数使用按位或操作符去设置 PDO::PARAM_INPUT_OUTPUT 位
  • $length：数据类型的长度。为表明参数是一个存储过程的 OUT 参数，必须明确地设置此长度
  • $driver_options：驱动属性

返回值

成功时返回 true，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("INSERT INTO tab_test (name) VALUES(?)");

$name = "Tom";
$stmt->bindParam(1, $name);

$stmt->execute();

bindValue ​

功能

绑定一个值到用作预处理的 SQL 语句中的对应命名占位符或问号占位符。

原型

PHP
PDOStatement::bindValue(
    mixed $parameter, 
    mixed $value, 
    ?int $data_type = PDO::PARAM_STR
): bool

参数

  • $parameter：参数标识符。对于使用命名占位符的预处理语句，应是类似 :name 形式的参数名。对于使用问号占位符的预处理语句，应是以 1 开始索引的参数位置
  • $value：绑定到参数的值
  • $data_type：使用 PDO::PARAM_* 常量明确地指定参数的类型

返回值

成功时返回 true，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("INSERT INTO tab_test (name) VALUES(?)");

$stmt->bindValue(1, "Tom");

$stmt->execute();

closeCursor ​

功能

关闭游标，使语句能再次被执行。

原型

PHP
PDOStatement::closeCursor(): bool

返回值

成功时返回 true，失败时返回 false。

columnCount ​

功能

获取结果集中的列数。

原型

PHP
PDOStatement::columnCount(): int

返回值

返回由 PDOStatement 对象代表的结果集中的列数。如果没有结果集，则返回 0。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

echo $stmt->columnCount(); // 2

debugDumpParams ​

功能

打印出一条预处理语句包含的信息。

原型

PHP
PDOStatement::debugDumpParams(): bool

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test WHERE id = ?");
$stmt->bindValue(1, 1);

$stmt->debugDumpParams();

errorCode ​

功能

获取上一次操作相关的错误码。

原型

PHP
PDOStatement::errorCode(): string

返回值

PDOStatement 对象执行操作中的错误码。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test WHERE id = ?");
try {
    $stmt->execute();
} catch (PDOException $e) {
}

echo $stmt->errorCode();

errorInfo ​

功能

获取上一次操作相关的错误信息。

原型

PHP
PDOStatement::errorInfo(): array

返回值

上一次执行操作的错误信息的数组。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test WHERE id = ?");
try {
    $stmt->execute();
} catch (PDOException $e) {
}

print_r($stmt->errorInfo());

execute ​

功能

执行一条预处理语句。

原型

PHP
PDOStatement::execute(array $input_parameters = ?): bool

参数

  • $input_parameters：一个元素个数和将被执行的 SQL 语句中绑定的参数一样多的数组。所有的值作为 PDO::PARAM_STR 对待

返回值

成功时返回 true，失败时返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT * FROM tab_test");

$res = $stmt->execute();
if ($res)
    echo '执行成功';
else 
    echo '执行失败';

fetch ​

功能

从结果集中获取下一行记录。

原型

PHP
PDOStatement::fetch(
    ?int $mode = PDO::FETCH_DEFAULT, 
    ?int $cursorOrientation = PDO::FETCH_ORI_NEXT, 
    ?int $cursorOffset = 0
): mixed

参数

  • $mode：控制下一行如何返回给调用者。此值必须是 PDO::FETCH_* 系列常量中的一个，默认为 PDO::FETCH_BOTH
  • $cursorOrientation：对于 一个 PDOStatement 对象表示的可滚动游标，该值决定了哪一行将被返回给调用者。此值必须是 PDO::FETCH_ORI_* 系列常量中的一个，默认为 PDO::FETCH_ORI_NEXT。要想让 PDOStatement 对象使用可滚动游标，必须在用 PDO::prepare() 预处理SQL语句时，设置 PDO::ATTR_CURSOR 属性为 PDO::CURSOR_SCROLL
  • $cursorOffset：偏移量

返回值

此方法成功时返回的值依赖于提取类型。在所有情况下失败均返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

while ($row = $stmt->fetch()) {
    echo "{$row['ID']}, {$row['NAME']}" . PHP_EOL;
}

fetchAll ​

功能

返回一个包含结果集中所有行的数组。

原型

PHP
public PDOStatement::fetchAll(int $mode = PDO::FETCH_DEFAULT): array
PHP
public PDOStatement::fetchAll(int $mode = PDO::FETCH_COLUMN, int $column): array
PHP
public PDOStatement::fetchAll(int $mode = PDO::FETCH_CLASS, string $class, ?array $constructorArgs): array
PHP
public PDOStatement::fetchAll(int $mode = PDO::FETCH_FUNC, callable $callback): array

参数

  • $mode：控制如何返回数组的内容
    • PDO::FETCH_DEFAULT：默认为 PDO::ATTR_DEFAULT_FETCH_MODE 的值（ 其缺省值为 PDO::FETCH_BOTH ）
    • PDO::FETCH_COLUMN：包含结果集中单独一列所有值的数组
    • PDO::FETCH_CLASS：返回指定类的实例，映射每行的列名到类中对应的属性名
    • PDO::FETCH_FUNC：将每行的列作为参数传递给指定的函数，并返回调用函数后的结果
  • $column：与 PDO::FETCH_COLUMN 一起使用。返回指定以 0 开始索引的列
  • $class：与 PDO::FETCH_CLASS一起使用
  • $constructorArgs：当 mode 参数为 PDO::FETCH_CLASS 时自定义类构造方法的参数
  • $callback：与 PDO::FETCH_FUNC一起使用

返回值

一个包含结果集中所有剩余行的数组。此数组的每一行要么是一个列值的数组，要么是属性对应每个列名的一个对象。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

$rows = $stmt->fetchAll();

foreach ($rows as $row) {
    echo "{$row['ID']}, {$row['NAME']}" . PHP_EOL;
}

fetchColumn ​

功能

从结果集中的下一行返回单独的一列。

原型

PHP
PDOStatement::fetchColumn(int $column_number = 0): string

参数

  • $column_number：从行里取回的列的索引数字（以0开始的索引）

返回值

结果集中的下一行单独的一列。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

while ($name = $stmt->fetchColumn(1)) {
    echo $name . PHP_EOL;
}

fetchObject ​

功能

获取下一行并作为一个对象返回。此方法是使用 PDO::FETCH_CLASS 或 PDO::FETCH_OBJ 风格的 PDOStatement::fetch() 的一种替代。

原型

PHP
PDOStatement::fetchObject(
    string $class_name = "stdClass", 
    array $ctor_args = ?
): mixed

参数

  • $class_name：创建类的名称
  • $ctor_args：此数组的元素被传递给构造方法

返回值

一个属性名对应于列名的所要求类的实例，失败时返回 false。

示例

PHP
class User {
    private $id;
    private $name;

    public function getId() {
        return $this->id;
    }

    public function getName() {
        return $this->name;
    }
}

$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare('SELECT id as "id", name as "name" FROM tab_test');
$stmt->execute();

while ($user = $stmt->fetchObject("User")) {
    echo "{$user->getId()}, {$user->getName()}" . PHP_EOL;
}

getAttribute ​

功能

检索一个语句属性。

原型

PHP
PDOStatement::getAttribute(int $attribute): mixed

参数

  • $attribute：属性类型

返回值

属性值。

getColumnMeta ​

功能

返回结果集中一列的元数据。

原型

PHP
PDOStatement::getColumnMeta(int $column): array

参数

  • $column：结果集中以0开始索引的列

返回值

返回一个关联数组，它包含了下列表示一个单独列的元数据的值：

  • native_type

    用于表示列值的 PHP 原生类型。

  • driver:decl_type

    在数据库中用于表示列值的 SQL 类型。如果结果集中的列是一个函数的结果，则该值不能被 PDOStatement::getColumnMeta() 返回。

  • flags

    任何设置于此列的标记。

  • name

    通过数据库返回的列名。

  • table

    通过数据库返回的该列的表名。

  • len

    该列的长度。除浮点小数外通常为 -1。

  • precision

    该列的数值精度。除浮点小数外通常为 0。

  • pdo_type

    以 PDO::PARAM_* 常量为代表的列类型。

如果结果集不存在，或者是请求的列在结果集中不存在，则返回 false。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("SELECT id, name FROM tab_test");
$stmt->execute();

print_r($stmt->getColumnMeta(0));

getIterator ​

功能

获取结果集迭代器。

原型

PHP
PDOStatement::getIterator(): Iterator

nextRowset ​

功能

查询结果有多个结果集，切换到下一个结果集。虚谷数据库不支持 prepare 多个 SQL 语句，因此一般不会出现多结果集。

原型

PHP
PDOStatement::nextRowset(): bool

返回值

成功时返回 true，失败时返回 false。

rowCount ​

功能

返回执行 SQL 语句后受影响的行数。

原型

PHP
PDOStatement::rowCount(): int

返回值

受影响的行数。

示例

PHP
$pdo = new PDO("xugusql:ip=127.0.0.1;port=5138;db=SYSTEM", "SYSDBA", "SYSDBA");

$stmt = $pdo->prepare("INSERT INTO tab_test (name) VALUES (?)");
$stmt->bindValue(1, "Tom");
$stmt->execute();

echo $stmt->rowCount();

setAttribute ​

功能

设置一个语句属性。

原型

PHP
PDOStatement::setAttribute(int $attribute, mixed $value): bool

参数

  • $attribute：属性
  • $value：属性值

返回值

成功时返回 true，失败时返回 false。

setFetchMode ​

功能

为语句设置默认的获取模式。

原型

PHP
PDOStatement::setFetchMode(int $mode): bool
PHP
PDOStatement::setFetchMode(int $PDO::FETCH_COLUMN, int $colno): bool
PHP
PDOStatement::setFetchMode(int $PDO::FETCH_CLASS, string $classname, array $ctorargs): bool
PHP
PDOStatement::setFetchMode(int $PDO::FETCH_INTO, object $object): bool

参数

  • $mode：获取模式必须是 PDO::FETCH_* 系列常量中的一个
  • $colno：列号
  • $classname：类名
  • $ctorargs：构造函数参数
  • $object：对象

返回值

成功时返回 true，失败时返回 false。