README

目录

• 关于
• 配置
• 执行
• 安装
• 单元测试
• 示例
• 参考指南

关于

此 API 是基于 PDO 并受 JDBC 架构启发的超轻量级 数据访问层。作为一个数据访问层，它的目的是屏蔽与不同 SQL 供应商合作的复杂性，并提供一个简单而优雅的接口来连接、查询和解析查询结果，克服 PDO 设计缺陷（如混乱的架构和功能）。

与 SQL 数据库（供应商）合作的整个想法简化为以下步骤

• 配置：设置一个 XML 文件，其中配置了您的网站使用的 SQL 供应商以及开发环境
• 执行：使用 Lucinda\SQL\Wrapper 读取上述 XML，根据开发环境编译 Lucinda\SQL\DataSource 对象（存储连接信息），并将其静态注入到 Lucinda\SQL\ConnectionFactory 类中以用于查询

API 完全符合 PSR-4 标准，只需 PHP8.1+ 解释器、SimpleXML 和 PDO 扩展。要快速了解其工作原理，请查看

• 安装：描述了如何在您的计算机上安装 API，考虑到上述步骤
• 单元测试：API 具有高达 100% 的单元测试覆盖率，使用 UnitTest API 而不是 PHPUnit 以获得更大的灵活性
• 示例：展示了如何使用此 API 实现 CRUD 查询的多个示例

配置

要配置此 API，您必须有一个包含 sql 标签的 XML 文件

<sql>
	<{ENVIRONMENT}>
		<server name="..." driver="..." host="..." port="..." username="..." password="..." schema="..." charset="..."/>
		...
	</{ENVIRONMENT}>
	...
</sql>

其中

• sql：保存用于 SQL 服务器的全局连接信息
  • {ENVIRONMENT}：开发环境名称（将被替换为 "local"、"dev"、"live" 等）
    • server：通过属性存储单个服务器的连接信息
      • name：唯一标识符（可选）。如果同一环境中使用多个 SQL 服务器，则必需！
      • driver：必填项。PDO 驱动名称（pdo 驱动）
      • host：必填项。服务器主机名。
      • port：可选项。服务器端口。如果没有设置，则使用默认服务器端口。
      • username：必填项。用于连接的用户名。
      • password：必填项。用于连接的密码。
      • schema：可选项。连接后使用的默认模式。
      • charset：可选项。连接后查询中使用的默认字符集。
      • autocommit：不推荐使用。是否应自动提交 INSERT/UPDATE 操作（值可以是：0 或 1）。并非所有供应商都支持！
      • 持久连接： (不推荐) 是否应在不同部分之间保持连接（值可以是：0 或 1）。并非所有供应商都支持！
      • 超时： (不推荐) 空闲连接自动关闭的时间（以秒为单位）。并非所有供应商都支持！

示例

<sql>
    <local>
        <server driver="mysql" host="localhost" port="3306" username="root" password="" schema="example" charset="utf8"/>
    </local>
    <live>
        <server driver="mysql" host="localhost" port="3306" username="hello" password="world" schema="example" charset="utf8"/>
    </live>
</sql>

执行

完成上述步骤后，您需要运行以下命令才能稍后连接和查询数据库

new Lucinda\SQL\Wrapper(simplexml_load_file(XML_FILE_NAME), DEVELOPMENT_ENVIRONMENT);

这将把当前开发环境中找到的每个 服务器 标签包装成 Lucinda\SQL\DataSource 对象，并将它们静态注入到 Lucinda\SQL\ConnectionFactory 类中。

上面的类确保在会话（输入输出请求流）持续期间，每个服务器只使用一个 Lucinda\SQL\Connection。要使用该连接进行查询，以下方法可用

• statement：返回一个 Lucinda\SQL\Statement 对象，用于创建和执行 SQL 语句
• preparedStatement：返回一个 Lucinda\SQL\PreparedStatement 对象，用于创建和执行 SQL 预处理语句
• transaction：返回一个 Lucinda\SQL\Transaction 对象，用于将上述两个操作包装在事务中

通过上述 execute 方法执行 SQL 语句后，用户可以基于返回的 Lucinda\SQL\StatementResults 对象进行处理。

安装

首先选择一个文件夹，API 将安装到该文件夹，然后使用控制台在此处写入以下命令

composer require lucinda/sql-data-access

然后创建一个包含配置设置的 configuration.xml 文件（见上面的 配置），并在项目根目录中创建一个 index.php 文件（见上面的 初始化），包含以下代码

require(__DIR__."/vendor/autoload.php");
new Lucinda\SQL\Wrapper(simplexml_load_file("configuration.xml"), "local");

然后您就可以查询服务器，如下例所示

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$users = $connection->statement("SELECT id, name FROM users")->toMap("id", "name");

单元测试

有关测试和示例，请检查 API 源中的以下文件/文件夹

• unit-tests.sql：在执行单元测试之前，需要在服务器上运行一次的 SQL 命令（假设 MySQL）
• test.php：在控制台中运行单元测试
• unit-tests.xml：设置单元测试并模拟 "sql" 标签
• tests：来自 src 文件夹的类的单元测试

如果您想自己运行 test.php，请首先导入 unit-tests.sql 文件！

示例

INSERT

INSERT 查询结果的示例处理

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$resultSet = $connection->statement("INSERT INTO users (first_name, last_name) VALUES ('John', 'Doe')");
$lastInsertID = $resultSet->getInsertId();

UPDATE/DELETE

UPDATE/DELETE 查询结果的示例处理

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$resultSet = $connection->statement("UPDATE users SET first_name='Jane' WHERE id=1");
if($resultSet->getAffectedRows()>0) {
    // update occurred
}

SELECT

从 SELECT 结果集中获取单个值的示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$firstName = $connection->statement("SELECT first_name FROM users WHERE id=1")->toValue();

按行解析 SELECT 结果集的示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$resultSet = $connection->statement("SELECT * FROM users");
while ($row = $resultSet->toRow()) {
    // process row
}

从 SELECT 结果集中获取第一列所有值的示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$ids = $connection->statement("SELECT id FROM users")->toColumn();

从 SELECT 结果集中获取所有行作为数组，其中第一列的值成为键，第二列的值成为值的示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$users = $connection->statement("SELECT id, name FROM users")->toMap("id", "name");
// above is an array where id of user becomes key and name becomes value

从 SELECT 结果集中获取所有值的示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$users = $connection->statement("SELECT * FROM users")->toList();
// above is an array containing all rows, each as column-value associative array

参考指南

Connection 类

Lucinda\SQL\Connection 可用于执行连接上的操作。

以下方法与连接管理相关（由API自动处理，因此仅在特定情况下使用

以下方法与查询相关

类 ConnectionFactory

Lucinda\SQL\ConnectionFactory 类确保每个会话和服务器名称只有一个 Lucinda\SQL\Connection。具有以下静态方法

^ 如果您的应用程序在每种环境中使用单个数据库服务器，并且服务器XML标签中没有设置 name 属性，则必须使用空字符串作为服务器名称！

使用示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("myServer");
$conection->statement()->execute("UPDATE users SET name='John' WHERE name='Jane'");

请注意，此类在销毁时会自动关闭所有打开的连接！

类 Statement

Lucinda\SQL\Statement 实现了常规SQL非预处理语句操作，并具有以下公共方法

使用示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$statement = $connection->statement();
$resultSet = $statement->execute("SELECT id FROM users WHERE name='".$statement->quote($name)."'");

请注意，此类在销毁时会自动关闭所有打开的连接！

类 PreparedStatement

Lucinda\SQL\PreparedStatement 实现了SQL预处理语句操作，并具有以下公共方法

使用示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$preparedStatement = $connection->preparedStatement();
$preparedStatement->prepare("SELECT id FROM users WHERE name=:name");
$preparedStatement->bind(":name", $name);
$resultSet = $preparedStatement->execute();

类 Transaction

Lucinda\SQL\Transaction 可以将上述两个类的 execute 方法包裹在事务中，以保持数据完整性，因此具有以下公共方法

使用示例

$connection = Lucinda\SQL\ConnectionFactory::getInstance("");
$transaction = $connection->transaction();
$transaction->begin();
$connection->statement()->execute("UPDATE users SET name='John Doe' WHERE id=1");
$transaction->commit();

类 StatementResults

Lucinda\SQL\StatementResults 封装了处理SQL语句执行结果的模式，并具有以下公共方法

上述方法的使用示例可以在以下内容或单元测试中查看！