rkr / key-value-stores
Standard interfaces for common key-value-stores.
Requires
- php: >= 5.3
Requires (Dev)
- phpunit/phpunit: ~3.7
This package is auto-updated.
Last update: 2024-10-29 04:36:42 UTC
README
This project aims to provide a standard interface to common key-value-stores like memcache, redis or similar. If an author of a specific driver develops against these interfaces, is can be used everywhere the interfaces are implemented. This project does not ship a concrete implementations to existing stores.
Common interfaces
Stores
The simple version of the key value stores provide methods to set, get and remove a entry. There is also a method to test if a entry is existing:
interface ReadWriteStore
public function has($key);
public function get($key, $default=null);
public function set($key, $value);
public function remove($key);
The ReadWriteStore
-Interface has no own methods. It extends the 2 Interfaces ReadableStore
and WritableStore
which in turn extend from other, more basic interfaces. The idea behind this is described here.
Behavior of stores
has()
returns true when a key exists in the store and false if not. In addition to that, it throws an exception when $key
is not a valid type (see valid types).
get()
returns the content of a entry, referenced by $key
. If the entry was not found, get()
then returns $default
. $default
must be a value value-type
. In addition to that, an InvalidArgumentException
or deriving gets thrown when $key
is not a valid key-type (see valid types) and an InvalidOperationException
or deriving gets thrown for store specific reasons.
set()
sets the value of an entry. If the corresponding entry does not exist, set will create it. If the entry already exists, set will overwrite its content. set()
returns $this
for a fluent interface. In addition to that, an InvalidArgumentException
or deriving gets thrown when $key
is not a valid key-type (see valid types) and an InvalidOperationException
or deriving gets thrown for store specific reasons.
remove()
removes an entry from a store. It throws an InvalidOperationException
or deriving if this operation fails, caused by a missing entry or another process failure. In addition to that, an InvalidArgumentException
or deriving gets thrown when $key
is not a valid key-type (see valid types).
Contexts
A context is similar to a table in a RDBMS. With contexts, you can separate stores for different environments or components. So a context is like a central singleton-repository for stores.
For example, a context could be used to define a database connection. Every store created by that context inherit that connection and possibly some metadata too.
Valid types
Valid key-type
A key is valid if it is a string, int or object with a __toString() method. The store must not serialize and/or hash a key to convert any object to a string.
Valid value-type
A value (or default-value) is valid under the same criterias as a key-type. A default-value is also allowed to be null
.
Standard-tests
A store-author can make use of the provided standardtests to ensure compilance. So far, there are only tests for the ReadWriteStore
and the Contexts
. The tests are based in phpunit 3.7
.
Installation via composer
composer require "rkr/php-key-value-stores" "~v0.0"