Skip to content

Latest commit

 

History

History
316 lines (202 loc) · 8.05 KB

README.md

File metadata and controls

316 lines (202 loc) · 8.05 KB
Raw

Caphpe

Caphpe (pronounced like caffe or something) is a simple volatile in-memory key-value storage written in PHP.

Originally the idea was to create a Memcached clone using just PHP as an experiment.

You can read the "manual" over at rask.github.io/caphpe.

Installation

Requirements

  • PHP 7.2+ CLI with the following extensions: mbstring, sockets

Version 0.1.0 supports PHP 5.5 and newer, but is stale.

Using the built PHAR

  1. Download caphpe.phar
  2. Set as executable with chmod +x caphpe.phar
  3. Run it.

Using the source

  1. Clone this repository
  2. Make sure bin/caphpe is executable
  3. Install dependencies using composer install
  4. Run bin/caphpe.

Build PHAR for yourself

First clone this repo and fetch Composer dependencies, then run

$ box build

If you want to build a specific version, you can checkout a tag:

$ git checkout 0.2.0
$ box build

Usage

Starting a Caphpe instance

Start a Cahphe instance with the default configuration:

$ caphpe

Start a Caphpe instance with custom configuration:

$ caphpe [options]

Where [options] may contain any of the following:

--host=<host>|-h <host>
    IP or hostname to listen on

--port=<port>|-p <port>
    Port to listen on

--verbosity=<verbosity>|-v <verbosity>
    How verbose the instance output to STDOUT and STDERR is, use either 1, 2 or 3

--memorylimit=<limit>|-m <limit>
    Limit the amount of memory (in megabytes) Caphpe uses for itself

Defaults are as follows:

--host=127.0.0.1
--port=10808
--verbosity=1
--memorylimit=64

Caphpe will start and stay in the foreground unless otherwise sent to background. It will output STDOUT and STDERR messages depending on the verbosity parameter.

Using the cache

Caphpe is a volatile in-memory cache. If the Caphpe instance is stopped or killed, all data saved into its memory is lost. Caphpe currently has no grouping system, and all cached values are stored into the same namespace. You can use your own key format to define pseudo-grouping for values.

Connecting and interacting

Currently Caphpe provides an IP address based TCP connection interface which reads newline separated commands. You can send and receive data using a stream socket connection.

Caphpe reads commands that end in newlines.

Format your requests to the interface as such:

<command> <parameters>\n

In commands the <key> parameter is always the first one, and the numerical <timeout> parameter is always the last one (though optional). See what commands are available later in this README.

You can try Caphpe with telnet (tested with Windows 7 telnet):

telnet> o 127.0.0.1 10808
> add mykey value
1
> has mykey
1
> get mykey
value
> has nokey

> flush
1
> has mykey

> close
telnet>

Keys, values, types and timeouts

Keys

Keys are restricted to 64 characters in length and can only contain the following:

  • a-z
  • A-Z
  • 0-9
  • . and _
Values

Values are stored as strings by default. You can pass in a flag for each value to save internally as either a string, an integer or a boolean.

Warning: currently Caphpe can't operate on strings that contain newline characters (\n) as it uses those to delimit commands internally. For now libraries should switch newlines to some other string sequences when writing and reading from Caphpe.

Empty or no data is represented as an empty string.

Types

Types determine how Caphpe internally stores a value. There are three available types:

  • String (denoted with s)
  • Integer (denoted with i)
  • Boolean (denoted with b)

All values are saved as string by default (unless PHP does some magic casting somewhere). When using commands you need to use the flags s, i, and b to save values as certain types. Usage instructions available below in the commands section.

Timeouts

Timeouts determine when a value should be considered to be stale. Supply timeouts as the amount of seconds from now when a value should be considered stale. Caphpe clears the stale values cache at regular intervals while running, but each command checks the staleness before returning values.

Setting the timeout value to 0 will make the cached value last "forever" and this is the default behaviour if no value is supplied.

Timeouts are considered the last numeric characters in a command, preceded by a space. This means some string values ending in numbers may be misinterpreted as containing a timeout parameter.

Commands

Currently Caphpe supports the following commands:

add
add <key> <type>?|<value> <timeout>?

Add a new cache value. If the key already exists nothing is done. Returns 1 if successful, <empty string> if not. Examples:

add mykey somevalue
add mykey s|this is a string value
add mykey b|1 3600
add mykey i|123456
add mykey value with a timeout 3600
set
set <key> <type>?|<value> <timeout>?

Set a cache value. Will override values if the key exists. Returns 1 if successful, <empty string> if not. Examples:

set mykey somevalue
set mykey s|this is a string value
set mykey b|1 3600
set mykey i|123456
set mykey value with a timeout 3600
replace
replace <key> <type>?|<value> <timeout>?

Replace a cache value. If the key does not exist the nothing is done. Returns 1 if successful, <empty string> if not. Examples:

replace mykey somevalue
replace mykey s|this is a string value
replace mykey b|1 3600
replace mykey i|123456
replace mykey value with a timeout 3600
increment
increment <key> <timeout>?

Increment a numeric cached value. If the key contains non-numeric values or is not defined nothing is done. Returns 1 if successful, <empty string> if not. Examples:

increment mykey
increment mykey 3600
decrement
decrement <key> <timeout>?

See increment. This does the reverse. Returns 1 if successful, <empty string> if not. Examples:

decrement mykey
decrement mykey 3600
delete
delete <key>

Delete a cached value. If the key does not exist nothing is done. Returns 1 if successful, <empty string> if not. Examples:

delete mykey
has
has <key>

Checks whether Caphpe has the key defined. has does not check the value at all. Returns 1 if successful, <empty string> if not. Examples:

has mykey
get
get <key>

Get a value from Caphpe. Returns an empty string if not value is determined for the key or the key does not exist. Returns the value if if one exists, <empty string> if not. Examples:

get mykey
flush
flush

Flushes all data from a Caphpe instance. Returns 1 if successful, <empty string> if not. Examples:

flush
status
status

Gets a simple status message from a Caphpe instance. First line of the output contains headers (separated with \t) and the second line contains the values that correspond with the headers (also separated with \t). Examples:

status
> Memory usage (MB) \t Item count \t Smallest item (KB) \t Largest item (KB) \t Average item (KB)
> 34.5 \t 44583 \t 144 \t 256 \t 157
close
close

Close an open socket connection to Caphpe if using through telnet for instance. Examples:

close

Why Caphpe

Caphpe works where PHP CLI works. This means you can download the PHAR and just run it without the need to compile software in environments where compilers may not even be available.

Of course it is not as performant as something like Redis or Memcached, but it can provide a simple cache backend for lighter use cases.

Warning

Caphpe is not yet production ready as-is. Feel free to try it out though.

Caphpe does not persist the cached data anywhere. If the Caphpe instance is killed all stored data is gone too.

TODO

See the issue tracker for things that need to be done or would be nice to have done. Add issues to request fixes and features.

License

Caphpe is licensed with the MIT License. Please see LICENSE.md.