README

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

关于

此API是一个超轻量级的数据访问层，它类似于PDO，用于NoSQL键值数据库（又称键值存储）。作为一个数据访问层，其目的是屏蔽与不同NoSQL供应商合作的复杂性，并提供一个简单而优雅的接口用于连接和查询。目前，以下供应商得到支持

APC：一个没有持久化能力的极快数据库，由PHP直接处理，使用opcode缓存和数据存储
APCu：一个没有持久化能力的极快数据库，由PHP直接处理，只使用数据存储
Memcache：一个具有持久化能力的非常快的数据库，要求你在机器上安装MemCache服务器
Memcached：一个具有持久化能力的非常快的数据库，要求你在机器上安装MemCache服务器
Redis：一个略微慢速的具有持久化能力和许多额外功能的数据库，要求你在机器上安装Redis服务器
Couchbase：一个较慢的具有持久化能力和许多额外功能的数据库，要求你在机器上安装Couchbase服务器

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

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

API完全符合PSR-4规范，仅需要PHP8.1+解释器、SimpleXML扩展以及每个供应商的官方扩展。要快速了解其工作原理，请查看

安装：描述如何根据上述步骤在您的计算机上安装API
单元测试：API有100%的单元测试覆盖率，使用UnitTest API而不是PHPUnit以获得更大的灵活性
示例：展示了API功能的深入示例

配置

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

<nosql>
	<{ENVIRONMENT}>
		<server name="..." driver="..." {OPTIONS}/>
		...
	</{ENVIRONMENT}>
	...
</nosql>

位置

nosql：保存用于NoSQL供应商的全局连接信息
- {ENVIRONMENT}：开发环境名称（将被替换为"local"、"dev"、"live"等）
  - server：通过属性存储单个供应商的连接信息
    - name：(可选)唯一标识符。如果同一环境使用多个nosql供应商时是必需的！
    - driver：(必填) NoSQL供应商名称。支持值：apc、apcu、memcache、memcached、redis、couchbase
    - {OPTIONS}：配置上述driver所需额外属性列表
      - host：(必填) 服务器主机名（例如：127.0.0.1），主机名和端口号（例如：127.0.0.1:1234）或用逗号分隔的主机名和端口号列表（例如：192.168.1.9:1234,192.168.1.10:4567）。除非driver是APC/APCu，否则是必需的！
      - timeout：(不推荐) 空闲连接自动关闭的秒数。如果driver是APC/APCu/Couchbase，则不支持！
      - persistent：(不推荐) 是否应在部分之间持久连接（值可以是：0或1）。如果driver是APC/APCu/Couchbase，则不支持！
      - username：(必填) 用于连接的用户名。如果driver是Couchbase，则是必需的，否则被忽略！
      - password：(必填) 用于连接的密码。如果driver是Couchbase，则是必需的，否则被忽略！
      - bucket_name：(必填) 存储键值对的bucket名称（相当于SQL模式）。如果driver是Couchbase，则是必需的，否则被忽略！
      - bucket_password：(可选) bucket密码。如果driver是Couchbase，则是可选的，否则被忽略！

示例

<nosql>
    <local>
        <server driver="memcached" host="127.0.0.1"/>
    </local>
    <live>
        <server driver="redis" host="127.0.0.1"/>
    </live>
</nosql>

执行

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

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

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

上述类确保在整个会话（输入输出请求流程）期间，每个服务器只使用一个Lucinda\NoSQL\Driver。如果关联的供应商不是嵌入的（APC/APCu）并且需要服务器，则相同的对象还实现了Lucinda\NoSQL\Server接口，该接口可用于连接管理。

可能存在这样的情况，即Lucinda\NoSQL\Driver提供的抽象不足以执行只有相应供应商才知道的特定操作。您可以通过可选的getDriver方法来完成此操作，除非供应商是APC/APCu。

安装

首先选择一个文件夹安装API，然后在控制台中输入以下命令

composer require lucinda/nosql-data-access

然后创建一个包含配置设置的configuration.xml文件（见上文的configuration）和一个在项目根目录中的index.php文件（见上文的initialization），代码如下

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

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

$driver = Lucinda\NoSQL\ConnectionFactory::getInstance("");
$driver->set("hello", "world");

单元测试

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

test.php：在控制台运行单元测试
unit-tests.xml：设置单元测试
tests：src文件夹中类的单元测试
tests_drivers：drivers文件夹中类的单元测试

示例

使用共享驱动程序

使用示例

$driver = Lucinda\NoSQL\ConnectionFactory::getInstance("");
$driver->set("i", 1, 10); // sets key i as 1 for 10 seconds
$driver->get("i"); // returns 1
$driver->contains("i"); // returns true
$driver->increment("i"); // returns 2
$driver->decrement("i"); // returns 1
$driver->delete("i"); // deletes key i from store
$driver->flush(); // clears all value in store

使用本地驱动程序

使用示例（假设驱动程序为redis）

$driver = Lucinda\NoSQL\ConnectionFactory::getInstance("");
$redisDriver = $driver->getDriver();
if ($redisDriver->ping()) {
    echo "Success!";
}

参考指南

类 ConnectionFactory

Lucinda\NoSQL\ConnectionFactory 类确保每个会话和服务器名称仅使用一个 Lucinda\NoSQL\Driver。具有以下公共静态方法：

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

使用示例

$driver = Lucinda\NoSQL\ConnectionFactory::getInstance("myServer");
$driver->get("hello"); // gets value of "hello" key from store

接口 Server

Lucinda\NoSQL\Server 接口通过以下方法定义了管理通过键值存储服务器连接的操作：

以上方法由 API 自动处理，因此 仅在特定情况下使用！

接口 Driver

Lucinda\NoSQL\Driver 接口通过以下方法定义了在键值存储上执行的操作：

如果上述任何操作由于服务器问题而失败，则会抛出 Lucinda\NoSQL\OperationFailedException 异常！

lucinda / nosql-data-access

维护者

详细信息