README

Table of contents:

About
Configuration
Execution
Installation
Unit Tests
Examples
Reference Guide

About

This API is a ultra light weight Data Access Layer that acts like an equivalent of PDO for NoSQL key-value databases (aka key-value stores). As a data access layer, its purpose is to to shield complexity of working with different NoSQL vendors and provide a simple as well as elegant interface for connecting and querying. At this time, following vendors are supported:

APC: an extremely fast database without persistence abilities, handled directly by PHP that uses opcode cache and data store
APCu: an extremely fast database without persistence abilities, handled directly by PHP that uses only data store
Memcache: a very fast database with persistence abilities, requiring you to have MemCache server installed on your machine
Memcached: a very fast database with persistence abilities, requiring you to have MemCache server installed on your machine
Redis: a slightly slower database with persistence abilities and many extra features, requiring you to have Redis server installed on your machine
Couchbase: a slower database with persistence abilities and many extra features, requiring you to have Couchbase server installed on your machine

The whole idea of working with NoSQL databases (vendors) is reduced to following steps:

configuration: setting up an XML file where NoSQL vendors used by your site are configured per development environment
execution: using Lucinda\NoSQL\Wrapper to read above XML based on development environment, compile Lucinda\NoSQL\DataSource object(s) storing connection information and inject them statically into Lucinda\NoSQL\ConnectionFactory class

API is fully PSR-4 compliant, only requiring PHP8.1+ interpreter, SimpleXML extension and official extension for each vendor. To quickly see how it works, check:

installation: describes how to install API on your computer, in light of steps above
unit tests: API has 100% Unit Test coverage, using UnitTest API instead of PHPUnit for greater flexibility
examples: shows a deep example of API functionality

Configuration

To configure this API you must have a XML with a nosql tag inside:

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

Where:

nosql: holds global connection information for NoSQL vendors used
- {ENVIRONMENT}: name of development environment (to be replaced with "local", "dev", "live", etc)
  - server: stores connection information about a single vendor via attributes:
    - name: (optional) unique identifier. Required if multiple nosql vendors are used for same environment!
    - driver: (mandatory) NoSQL vendor name. Supported values: apc, apcu, memcache, memcached, redis, couchbase
    - {OPTIONS}: a list of extra attributes necessary to configure respective vendor identified by driver above:
      - host: server host name (eg: 127.0.0.1), host name and port (eg: 127.0.0.1:1234) or list of host names and ports separated by commas (eg: 192.168.1.9:1234,192.168.1.10:4567). Required unless driver is APC/APCu!
      - timeout: (not recommended) time in seconds by which idle connection is automatically closed. Not supported if driver is APC/APCu/Couchbase!
      - persistent: (not recommended) whether or not connections should be persisted across sections (value can be: 0 or 1). Not supported if driver is APC/APCu/Couchbase!
      - username: user name to use in connection. Required if driver is Couchbase, ignored otherwise!
      - password: password to use in connection. Required if driver is Couchbase, ignored otherwise!
      - bucket_name: name of bucket (equivalent of SQL schema) where key-value pairs are stored. Required if driver is Couchbase, ignored otherwise!
      - bucket_password: (optional) bucket password. Optional if driver is Couchbase, ignored otherwise!

Example:

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

Execution

Once you have completed step above, you need to run this in order to be able to connect and query database(s) later on:

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

This will wrap each server tag found for current development environment into Lucinda\NoSQL\DataSource objects and inject them statically into Lucinda\NoSQL\ConnectionFactory class.

Class above insures a single Lucinda\NoSQL\Driver is reused per server throughout session (input-output request flow) duration when . If vendor associated is not embedded (APC/APCu) and requires a server, same object also implements Lucinda\NoSQL\Server, which can be used in connection management.

There may be situations when abstraction provided by Lucinda\NoSQL\Driver is not enough and you need to run specific operations known only to respective vendor. You can do so by extra getDriver method, available unless vendor is APC/APCu:

Installation

First choose a folder where API will be installed then write this command there using console:

composer require lucinda/nosql-data-access

Then create a configuration.xml file holding configuration settings (see configuration above) and a index.php file (see initialization above) in project root with following code:

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

Then you are able to query server, as in below example:

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

Unit Tests

For tests and examples, check following files/folders in API sources:

test.php: runs unit tests in console
unit-tests.xml: sets up unit tests
tests: unit tests for classes from src folder
tests_drivers: unit tests for classes from drivers folder

Examples

Working With Shared Driver

Usage example:

$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

Working With Native Driver

Usage example (assumes driver was redis):

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

Reference Guide

Class ConnectionFactory

Lucinda\NoSQL\ConnectionFactory class insures a single Lucinda\NoSQL\Driver is used per session and server name. Has following public static methods:

^ if your application uses a single database server per environment and name attribute @ server XML tag isn't set, empty string must be used as server name!

Usage example:

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

Interface Server

Lucinda\NoSQL\Server interface defines operations to manage connection to key-value store servers via following methods:

Above methods HANDLED BY API AUTOMATICALLY, so to be used only in niche situations!

Interface Driver

Lucinda\NoSQL\Driver interface defines operations to perform on key-value stores via following methods:

If any of above operations fails due to server issues, a Lucinda\NoSQL\OperationFailedException is thrown!

lucinda / nosql-data-access

Maintainers

Details