Download the PHP package lucinda/nosql-data-access without Composer
On this page you can find all versions of the php package lucinda/nosql-data-access. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package nosql-data-access
NoSQL Data Access API
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
- 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
- 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:
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!
- server: stores connection information about a single vendor via attributes:
- {ENVIRONMENT}: name of development environment (to be replaced with "local", "dev", "live", etc)
Example:
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:
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\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:
Method | Arguments | Returns | Description |
---|---|---|---|
getDriver | void | Redis | Gets access to redis native driver if data source is redis. |
getDriver | void | Memcache | Gets access to memcache native driver if data source is memcache. |
getDriver | void | Memcached | Gets access to memcached native driver if data source is memcached. |
getDriver | void | CouchbaseBucket | Gets access to couchbase native driver if data source is couchbase. |
Installation
First choose a folder where API will be installed then write this command there using console:
Then create a configuration.xml file holding configuration settings (see initialization above) in project root with following code:
Then you are able to query server, as in below example:
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:
Working With Native Driver
Usage example (assumes driver was redis):
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:
Method | Arguments | Returns | Description |
---|---|---|---|
static setDataSource | string $serverName, Lucinda\NoSQL\DataSource | void | Sets data source detected beforehand per value of name attribute @ server tag. Done automatically by API! |
static getInstance | string $serverName | Lucinda\NoSQL\Driver | Gets driver from data source based on value of name attribute @ server tag, opens connection in case object implements Lucinda\NoSQL\Server and returns it for later querying. Throws Lucinda\NoSQL\ConnectionException if connection fails! |
^ 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:
Interface Server
Lucinda\NoSQL\Server interface defines operations to manage connection to key-value store servers via following methods:
Method | Arguments | Returns | Description |
---|---|---|---|
connect | Lucinda\NoSQL\DataSource | void | Connects to database server based on matching vendor's data source. Throws Lucinda\SQL\ConnectionException if connection fails! |
disconnect | void | void | Closes connection to database server. |
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:
Method | Arguments | Returns | Description |
---|---|---|---|
set | string $key, $value, int $expiration=0 | void | Sets value in store by key, available for seconds defined by expiration (unless later is zero). |
get | string $key | mixed | Gets value from store by key. |
contains | string $key | bool | Checks if key exists in store. |
increment | string $key, int $offset = 1 | int | Increments value in store by existing key and offset, then returns it. Throws Lucinda\NoSQL\KeyNotFoundException if key doesn't exist in store! |
decrement | string $key, int $offset = 1 | int | Decrements value in store by existing key and offset, then returns it. Throws Lucinda\NoSQL\KeyNotFoundException if key doesn't exist in store! |
delete | string $key | void | Deletes value from store by existing key. Throws Lucinda\NoSQL\KeyNotFoundException if key doesn't exist in store! |
flush | void | void | Clears all values in store. |
If any of above operations fails due to server issues, a Lucinda\NoSQL\OperationFailedException is thrown!