spfalz / db_mysqli

使用mysqli扩展的MySQL数据库类

1.0.2 2020-01-02 22:17 UTC

This package is auto-updated.

Last update: 2024-09-29 04:49:41 UTC


README

最后更新于2018年5月31日

1. 简介

此类用作旧db_mysql类的1:1替换,该类将在不久的将来停止工作,因为PHP开发者决定放弃"mysql"扩展,转而使用"mysqli"扩展。

此类使用"mysqli"(MySQL改进版)扩展,并提供db_MySQL类所有的方法,同时也在mysqli扩展的扩展功能期间提供了额外的功能。例如,绑定变量现在是此类的一部分。

2. 要求

要使用此类,必须满足以下要求:

  • PHP 5.x或7.x,已启用"mysqli"扩展。已测试5.6.29,7.0.14和7.1.1版本。

  • MySQL数据库4.x或更高版本。已测试MySQL 5.6.35,5.7.17和MariaDB 5.5版本。

3. 安装和使用

3.1 Composer

如果您使用composer,可以通过调用以下命令将此类添加到项目中:

composer require spfalz/db_mysqli

3.2 手动安装

将提供的db_mysqli.class.php复制到您选择的目录中,一个不错的选择是将inc/目录放在您的项目目录中。同时,将dbdefs.inc.php文件复制到与db_mysqli.class.php文件相同的目录。

3.3 配置

"dbdefs.inc.php"文件用作类的配置文件。您可以在类的构造函数中指定此文件的备用路径。

以下定义可以在dbdefs.inc.php中使用,以在类中使用该类:

MYSQLDB_HOST

目标数据库的主机名或IP地址。

MYSQLDB_PORT

目标数据库的端口,默认为3306。

MYSQLDB_USER

用作默认连接的MySQL用户名。

MYSQLDB_PASS

上面用户帐户的MySQL密码。

MYSQLDB_DATABASE

要使用的模式名称。

MYSQLAPPNAME

您应用程序的名称。这在错误消息中使用。

DB_ERRORMODE

如何处理错误。默认情况下,出于安全原因只显示有限的信息。有关详细信息,请参阅setErrorHandling()的描述。

MYSQLDB_ADMINEMAIL

指定一个电子邮件地址,在发生错误时使用。此电子邮件地址在错误消息中显示,如果设置了MYSQLDB_SENTMAILONERROR,则还会将自动电子邮件发送到该地址。

MYSQLDB_SENTMAILONERROR

标志表示类是否应在发生错误时自动向定义的电子邮件地址发送电子邮件。将其设置为1以启用自动发送,并将其设置为0以禁用此行为。

MYSQLDB_MAIL_EXTRAARGS

使用此定义将额外的参数传递给mail()命令中的SendmailOnError()。某些服务器可能需要在使用PHP的mail()命令时设置-f参数,并且为了允许在此类中这样做,您可以使用此定义。默认为未设置。

MYSQLDB_USE_PCONNECT

如果设置为1,则使用持久连接,否则使用标准连接。这也可以通过setPConnect()方法按脚本逐个设置。

MYSQLDB_CHARACTERSET

您可以在其中设置类应在连接阶段设置给MySQL的字符集。这允许将MySQL通信设置为'utf8'。如果未设置此定义,则使用MySQL的默认字符集。

MYSQLDB_TIME_NAMES

您可以在此处设置用于日期和时间翻译的默认语言。请在此处指定以下URL下列出的值

https://dev.mysqlserver.cn/doc/refman/5.0/en/locale-support.html

如果未设置此定义,则使用MySQL服务器的默认语言。

MYSQLDB_COMPATIBLE_MODE

如果您正在将此类用作旧 "db_MySQL" 类的替代品,请启用此开关并将其设置为 TRUE。该类将模拟旧类并自动定义所有必要的定义,因此您只需更改构造函数调用,其他所有内容应该都能正常工作。新项目绝不应使用此功能,应保留默认值 FALSE。

如何使用

要使用该类,您必须调用类代码,其余部分将在您首次实例化该类时自动完成。通常,您可能有一个包含其他几个脚本的PHP脚本,这里放置类调用require()语句的理想位置,即

// ...Your require() statements

require("path/to/mysqlidb_class.php");

// ..Rest of your code here

一旦完成此操作,并在dbdefs.inc.php中添加了正确的值,您现在可以开始使用该类,例如如下所示

require("mysqlidb_class.php");

$db = new spfalz\db_mysqli;
$db->Connect();
$mver = $db->Version();
$db->Disconnect();
echo("Your MySQL Server is V".$mver);

如您在此示例中看到的,dbdefs.inc.php文件是在您创建db_mysqli对象的第一实例时自动加载的。您也可以通过在构造函数中指定不同的路径来使用不同的配置文件,如下所示

require("mysqlidb_class.php");

$db = new spfalz\db_mysqli('/path/to/my/own/config.inc.php');
$db->Connect();
$mver = $db->Version();
$db->Disconnect();
echo("Your MySQL Server is V".$mver);

4. 方法概述

我已提供由phpDocumentor生成的自动生成的方法概述,位于分发归档的docs子目录中。

该类提供了以下方法

__construct([mixed $extconfig = ''])

这是类的构造函数。在您可以使用任何类函数之前,您必须创建一个新的实例。注意:如果您的PHP安装没有内置mysqli功能,则类在构造函数中抛出异常。

示例

$db = new spfalz\db_mysqli;

您还可以提供数据库定义文件的替代路径

$db = new spfalz\db_mysqli("/path/to/your/own/dbdefs.inc.php");

如果您省略了dbdefs.inc.php的路径,则类尝试从类所在的同一目录中包含此文件。

integer AffectedRows ([mixed $extsock = -1])

基于之前的DML操作返回受影响的行数。注意单词DML(数据操作语言),这意味着此方法仅返回INSERT、UPDATE、DELETE或REPLACE命令的值!如果没有提供外部连接句柄,则使用内部保存的句柄。

void CheckSock ()

内部函数,用于检查内部套接字变量是否已填充。如果没有填充,则类调用Print_Error()并打印出错误信息,指出 "!!! 未连接到MySQL数据库!!!"。

void Commit ()

提交事务。请注意,这仅适用于支持事务的存储引擎,如InnoDB;MyISAM表不是事务性的,因此此命令简单地不做任何事情。

mixed Connect ([string $user = ''], [string $pass = ''], [string $host = ''],[string $db = ''], [integer $port=0])

执行到MySQL数据库服务器的连接。通常,您不需要在此处提供任何参数,因为这些参数将自动从dbdefs.inc.php文件中获取。如果在连接尝试期间发生错误,则类会返回错误代码给调用者(如果 DB_ERRORMODE 设置为 db_mysqli::DBOF_RETURN_ALL_ERRORS)或打印出错误信息并终止执行。如果一切顺利,此方法返回连接句柄。您不需要保存此值,类会内部保存此句柄并在您不提供句柄时使用此句柄。

string ConvertMySQLDate (string $mysqldate, string $fmtstring)

将MySQL默认日期字符串(YYYY-MM-DD HH:MI:SS)转换为 strftime() 兼容的格式。您可以使用strftime()支持的所有格式标签,此函数简单地将mysql日期字符串转换为时间戳,然后将此时间戳与您提供的格式一起传递给strftime()。如果 $fmtstring 为空,则类使用 '%c' 作为默认格式字符串。

转换后的日期字符串随后返回。

请勿将其作为默认日期转换器使用,尽可能在查询中使用 DATE_FORMAT() 函数,因为这样做比使用此函数要快得多!只有在无法使用 MySQL SQL 日期转换函数的情况下,才考虑使用此函数。

array DescTable (string $tname)

此方法描述了给定的表,并返回表的结构的数组。以下字段被返回

| 0 | 列名 | 1 | 列类型 | 2 | 列大小 | 3 | 列标志

请注意,此方法仅返回关于表结构的基信息,不返回约束或其他元信息。

请参阅 examples/test_desc_tables.php 以了解如何使用此方法的示例。

void Disconnect ([mixed $other_sock = -1])

从 MySQL 数据库断开连接。如果没有提供外部连接句柄,则类将断开内部连接句柄,否则将使用提供的句柄。

string EscapeString (string $str)

允许在将其添加到 MySQL 之前转义字符串。为了安全起见,您应该在执行查询之前始终使用此方法。主要如果您计划从 Web 表单中保存数据,您必须(!)转义所有数据,否则可能发生 SQL 注入!此方法还首先检查 magic_quotes_gpc() 设置是否启用,并在激活时调用 stripslashes()

array FetchResult (mixed $result, [integer $resflag = MYSQLI_ASSOC])

从语句句柄 $result 中检索下一行,并根据标志 $resflag 以数字或关联数组格式返回数据。语句句柄由 QueryResult() 返回。如果没有更多数据,则返回 NULL。典型用法如下

$stmt = $db->QueryResult("SELECT FOO FROM BAR ORDER BY FOO");
while($data = $db->FetchResult($stmt))
  {
  echo($data['FOO']);
  }
$db->FreeResult($stmt);

默认返回格式始终为关联数组,如果您想获取数字数组,则必须将上面的行更改为 $db->FetchResult($stmt,MYSQLI_NUM)

array Flags2TXT (integer $flags_num)

返回给定列的所有标志的空格分隔列表。此方法返回的典型值可能包括:"NOT_NULL","PRI_KEY" 等。用法在 DescTable() 方法中展示。

bool GetAutoCommit(mixed $extsock = -1)

返回连接的 MySQL 会话的自动提交标志状态。《TRUE》表示自动提交已启用。

mixed FreeResult (mixed $result)

在从 FetchResult() 接收最后一行之后,您应使用此函数释放语句句柄。PHP 通常在脚本终止时自动释放所有分配的资源,但您应该始终自己释放所有分配的资源,因为这是一种良好的编程实践。

string GetClassVersion ()

返回类的版本。版本字符串的格式为 MAJOR.MINOR.PATHLEVEL versionnumber,例如 "0.1.3"。

mixed GetConnectionHandle ()

返回由 Connect() 返回的内部保存的连接句柄。如果您想使用 PHP 的 mysqli_* 函数处理已连接的数据库句柄,则这很有用。如果不存在活动连接句柄,则返回 -1

integer GetDebug ()

返回当前用于调试处理的位掩码。有关使用此类进行调试的详细信息,请参阅 SetDebug()

integer GetErrno ([mixed $other_sock = -1])

返回上次 SQL 操作的错误代码。您可以通过传递自己的连接句柄来在此处。

integer GetErrorHandling(void)

返回当前由类使用的错误处理方法。有关详细信息,请参阅 SetErrorHandling()

string GetErrorText ([mixed $other_sock = -1])

返回上次 SQL 操作的错误描述。您可以通过传递自己的连接句柄来在此处。

bool GetPConnect()

返回当前使用的持久连接设置。《TRUE》表示已启用持久连接,否则为 FALSE

integer GetQueryCount ()

返回当前查询计数器。每当类对数据库服务器执行查询时,内部计数器都会增加。这有助于跟踪错误,因为 Print_Error() 函数会输出此值,这使得通过简单地按查询计数到发生错误的查询来查找脚本中的错误变得更加容易。

float GetQueryTime ()

返回该类执行查询所花费的时间。格式为 "秒.微秒"。

array get_CharSet ()

方法用于返回当前MySQL字符集变量设置的当前值。

请注意,MySQL返回一个设置列表,因此此方法返回所有与character_set相关的设置,作为一个关联数组。

请参阅 examples/test_locale.php 中的示例。

string get_TimeNames ()

方法用于返回当前MySQL lc_time_names 变量的设置。

请参阅 examples/test_locale.php 中的示例。

integer LastInsertId ([mixed $extsock = -1])

返回最后使用的auto_increment ID。每次在基础表中定义了auto_increment字段的行插入时,MySQL都会自动增加该字段。使用此方法可以检索新更新的值。如果没有提供外部连接句柄,则使用内部句柄。

integer NumRows()

返回结果集中的行数。在执行SELECT或SHOW等命令后使用此方法。对于INSERT、UPDATE、DELETE等DML操作,必须使用AffectedRows()方法。

array PerformNewInsert(string $table_name, array &$fields,[string $sql='INSERT'])

执行从给定变量列表中提取的INSERT或REPLACE语句。这些语句将按NEW Insert样式构造,并调整到 max_allowed_packet 边界。这可以显着提高与逐个执行每个INSERT语句相比的大批量插入。请注意,此方法仅支持INSERT和REPLACE语句,不支持其他类型。

传递的数组必须以字段名作为键,以相应值作为值。

看起来像这样

$data[0]['fieldname1'] = 'value0/1';
$data[0]['fieldname2'] = 'value0/2';
$data[1]['fieldname1'] = 'value1/2';
$data[1]['fieldname2'] = 'value1/2';

注意:数据库必须已连接!

请参阅 examples/new_insert.php 中的此方法的实际示例。

void PrintDebug (string $msg)

根据当前的DEBUG设置,类将调试信息输出到屏幕、PHP的错误日志或两者。如果未启用调试,则此函数不执行任何操作。这在跟踪错误时非常有用,您可以在有关查询之前简单地使用您选择的调试级别调用SetDebug(),然后类将输出发生的情况。

示例

$db->SetDebug(db_mysqli::DBOF_DEBUGSCREEN);
$db->Query('SELECT FOO FROM BAR WHERE DUMMY=1');

将导致在屏幕上输出查询。请参阅示例以获取更多详细信息如何使用此方法。

mixed Query (string $querystring, [integer $resflag = MYSQLI_ASSOC],integer $no_exit)

执行单行查询并返回结果,根据 $resflag 设置,结果可以是数值或关联数组。使用 $no_exit 标志,您可以选择性地指示类在出现错误时不退出(设置为1),即使您的 DB_ERRORMODE 主定义有不同的设置。此方法在mysql_query()方法返回非布尔值时,将调用结果作为数组返回。对于所有其他命令,仅返回调用结果的数值。

mixed QueryResult (string $querystring, integer $no_exit)

执行多行查询并返回一个可以传递给FetchResult()FreeResult()的语句句柄。使用 $no_exit 标志,您可以选择性地指示类在出现错误时不退出(设置为1),即使您的 DB_ERRORMODE 主定义有不同的设置。

void Rollback ()

回滚当前事务。请注意,这仅支持启用事务的存储引擎(如InnoDB);MyISAM表不是事务性的,因此此命令简单地不执行任何操作。

bool SetAutoCommit (bool $state,mixed $extsock = -1)

启用($state = TRUE)或禁用($state = FALSE)MySQL AutoCommit标志。返回mysqli_autocommit()函数调用的值。如果给出$extsock,则此标志的设置属于您传递的资源,否则使用内部资源。有关详细信息,请参阅https://php.ac.cn/manual/en/mysqli.autocommit.php

void SetCompatMode(void)

如果您正在用这个db_mysqli类替换旧的db_MySQL类,您可能首先想检查所有操作是否正常,而不影响您的源代码。此方法通过定义所有旧类常量作为宏来帮助您。以下列表是已定义的(如果尚未定义):

如果可能的话,请重写您的源代码以仅使用新的宏!

void SetConnectionHandle (mixed $extsock)

允许通过外部值覆盖内部套接字。但是您在这里真的应该知道自己在做什么,因为这个类不会跟踪此更改,它只是简单地覆盖内部句柄!

void SetDebug (integer $state)

此函数允许在脚本中调试SQL查询。

$state可以有以下值

您可以通过添加相应的宏来混合调试级别。您还可以通过调用方法GetDebug()来检索当前的调试级别设置。

void setErrorHandling (integer $val)

允许设置类的错误处理方式。

boolean setPConnect($conntype)

更改连接方法为持久连接或标准连接。

将$conntype设置为TRUE以激活持久连接。将$conntype设置为FALSE以禁用持久连接。

默认为标准连接。

integer set_CharSet(string $charset)

此方法用于设置当前连接的字符集。

您必须指定一个有效的字符集名称,否则类将报告错误。有关支持字符集的列表,请参阅https://dev.mysqlserver.cn/doc/refman/5.0/en/charset-charsets.html

成功时返回1,否则失败。

integer set_TimeNames (string $locale)

此方法用于设置MySQL服务器的time_names设置。

传递一个有效的区域字符串以更改MySQL的区域设置。请注意,这仅自MySQL 5.0.25版起受支持!区域字符串类似于'de_DE'。

如果发生错误则返回0,如果更改成功则返回1。

string Type2TXT(integer $type_id)

返回给定列类型的文本表示。典型的返回值将是例如"VAR_STRING"。

请参见examples/test_desc_table.php中的示例。

string Version()

返回数据库版本字符串。当调用此函数时如果没有活动的连接,此方法会自动连接到数据库,检索版本字符串然后断开连接。如果存在活动连接,则使用此连接,当然不会终止。

QueryHash($SQL, $resflag = MYSQLI_ASSOC, $no_exit = 0, &$bindvars=null)

一个支持绑定变量的单一查询函数。为了避免SQL注入和其他可能针对您的数据库的攻击,您应该考虑只为新应用程序使用仅有的(!)绑定变量。绑定变量是安全地从/向您的MySQL服务器传递数据的方式,SQL本身只包含占位符,数据将在之后“绑定”。

以下是一个示例:

INSERT INTO foo(field1,field2) VALUES(?,?)

如您所见,field1和field2的值不是直接写入SQL语句的,而是在后面的bind_param调用中添加。这样就不会发生SQL注入,因为所有数据都是单独添加的。此外,这也具有很好的效果,因为SQL语句可以被缓存,因为它在运行时不会更改。此类支持双向绑定变量,因此您可以在INSERT/UPDATE/DELETE/MERGE中使用绑定变量,也可以在SELECT语句的WHERE子句中使用绑定变量。

绑定变量作为包含值/类型对的关联数组传递。

如果要将以下值插入上面的示例SQL中

field1 => 1 (整数) field2 => 'TEST' (字符串)

您必须为QueryHash()的bindvars参数定义以下数组

$bindvars = array([1,'i'],['TEST','s']);

'i'和's'是传递变量的类型定义,MySQL定义了以下类型

'i' => Integer 's' => String 'd' => Double 'b' => Blob

该类定义了四个常量用于这些值

db_mysqli::DBOF_TYPE_INT; db_mysqli::DBOF_TYPE_DOUBLE; db_mysqli::DBOF_TYPE_STRING; db_mysqli::DBOF_TYPE_BLOB;

查看 examples/test_bind_vars.php 了解如何使用它。

QueryResultHash($SQL,$no_exit =0, &$bindvars=null)

与 QueryResult() 具有相同的功能,但也支持绑定变量。参见 QueryHash() 了解如何使用这些绑定变量。

查看 examples/test_bind_vars.phpexamples/test_queryresulthash.php 了解如何使用此方法。

Prepare($SQL)

"Prepares" 一个 SQL 语句以绑定变量。如果您想手动绑定并执行 SQL,则必须调用此方法。如果一切正常则返回 TRUE,否则返回 FALSE 并填充内部错误变量。

查看 examples/test_bind_vars.php 了解如何使用它。

Execute($stmt,$no_exit = 0, &$bindvars=null)

执行一个已准备好的语句,并可选地绑定变量。如果提供了 bindvars,则在执行语句之前先绑定这些变量。如果存在结果集,则返回一个可用于 "FetchResult()" 的结果集;如果没有结果集(如 INSERT 等),则返回 FALSE。如果发生错误且自动错误报告被禁用,则返回一个整数。

查看 examples/test_bind_vars.php 了解如何使用它。

5. 将 "db_MySQL" 替换为 "db_mysqli"

如果您已使用我的其他 MySQL 类 db_MySQL,则只需将旧类替换为 db_mysqli 类,将构造函数从

$db = new db_MySQL;

更改为

$db = new spfalz\db_mysqli;

如果您在代码中使用了 db_MySQL 类的常量,您应将配置定义 MYSQLDB_COMPATIBLE_MODE 设置为 TRUE,或者作为替代,调用兼容性方法 SetCompatMode()。此方法将设置所有类定义,如 "DBOF_SHOW_NO_ERRORS",以及 MYSQL_* 定义,如果您的 PHP 安装没有包含 mysql 扩展。请尽量避免使用 SetCompatMode(),因为它总是更好的使用类前缀,因此使用例如 db_mysqli::DBOF_SHOW_NO_ERRORS。

6. 最后的话和联系方式

我现在在几个项目中使用这个类,从未遇到过任何问题。然而,我们都知道没有任何软件是100%无错误的,所以如果您发现了错误,或者有建议或功能请求,请随时通过以下 URL 联系我:http://www.saschapfalz.de/contact.php

编码愉快!