Caphpe

A volatile in-memory key-value storage written in PHP.

About

Caphpe originally started as an experiment on creating a Memcached clone of sorts in pure PHP.

Caphpe has various commands to store, alter, fetch and delete values. It does not persist the cached values anywhere. If you kill the process the data is gone for good.

Caphpe is not meant to be used as a direct replacement of something like Redis or Memcached. They play in an entirely other league when it comes to caching software. Caphpe is good for light use small object storage. PHP ain't as performant as C either, so it can be slower than Memcached and the like. Preliminary benchmarks clocked around 10000 writes per second through a persistent socket connection.

Read more about Caphpe or browse the code over at the GitHub repository.

Installation

Requirements

Caphpe should work anywhere where a relatively new (5.5+) PHP CLI installation is available and where socket creation is allowed.

Caphpe has been tested on Linux and Windows.

Download

Download the Phar and move it somewhere convenient for now (maybe your $PATH).

Running Caphpe

Make sure the downloaded Phar is executable using

$ chmod +x caphpe.phar
        

You can make it easier to invoke by using

$ mv caphpe.phar caphpe
        

Then you can run Caphpe as such

$ caphpe
        

Options

Cache offers a few options to alter how it runs:

--host=[host]|-h [host]
    Define a hostname to listen on. Defaults to 127.0.0.1.

--port=[port]|-p [port]
    Define the port to listen on. Defaults to 10808.

--memorylimit=[limit]|-m [limit]
    Define a memory limit (in megabytes) for Caphpe to use. Defaults to 64MB.

--verbosity=[verbosity]|-v [verbosity]
    Define output verbosity. 1, 2 or 3. Higher means more messages. Defaults to 1.
        

Example:

$ caphpe \
    --host=192.168.0.123 \
    --port=12345 \
    --memorylimit=128 \
    --verbosity=3
        

Connecting to Caphpe

Caphpe listens on the host and port as defined by the given options host and port.

You can test the connection by using telnet:

$ telnet 127.0.0.1 10808
> flush
1
> close
$ ...
        

If you wish to connect from an application you need to connect to the Caphpe TCP socket using your language's features.

Types and data in Caphpe

Internally Caphpe data types and data storing itself is quite simple.

Keys

All values in Caphpe are tied to a single key. Keys must be under 64 characters long and can contain only the following characters:

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

Types

Internally Caphpe supports the following types: string, integer and boolean. All values are stored as strings unless otherwise instructed (or if PHP does some magic type-casting with no respect to the author).

When issuing value-altering commands a user can tell Caphpe to cast to different types using the keys s, i and b. More on using those keys later when commands are explained.

Values

Each value is tied to a single key in Caphpe. Value can be one of the types mentioned above.

Values currently have two restrictions:

• They cannot contain newlines (\n)
• They cannot end into an <space>+integer combination.

Caphpe delimits commands using newlines (\n), so if there is one inside a value the commands breaks. Caphpe sets timeouts as the final command parameter so values ending in integers may not work properly.

The following values would be OK

this is an awesome value
this value is 100x awesomer
        

The following values may/will break

this is some not cool value 12345
this is a naughty\nvalue which has a newline
        

Plans are in place to lift these restrictions, maybe by enforcing some delimiters around values for library/wrapper implementations.

Timeouts

Each value in Caphpe has a timeout. A timeout internally is an absolute Unix timestamp which marks the time when a value is considered stale (and will be removed automatically from Caphpe).

When giving timeout values, users must provide the timeout value as seconds from now. In other words how many seconds a value is considered "fresh".

If no timeout value is given (or 0 is given) then Caphpe treats the value as "fresh forever" unless otherwise removed.

Managing data in Caphpe

You can add, alter, fetch and delete data in Caphpe using the following commands.

Commands

add

add [key] [type]?[value] [timeout]?
    where
        [key] is a valid key
        [type] is one of
            s|
            i|
            b|
        [value] is a valid value
        [timeout] is an integer marking seconds
        

Add a value to Caphpe. If the key already exists this command does nothing. Examples:

add mykey myvalue 3600
add mykey s|some string value
add mykey i|123456 3600
add mykey b|1 0
        

set

set [key] [type]?[value] [timeout]?
    see add command for reference
        

Sets a value to Caphpe. Will create and override keys where needed. Examples:

set mykey myvalue 3600
set mykey s|awesome string with awesome value
        

replace

replace [key] [type]?[value] [timeout]?
    see add command for reference
        

Replaces a value in Caphpe. If the key does not exist this command does nothing. Examples:

replace mykey myvalue 3600
replace mykey s|awesome string with awesome value
        

delete

delete [key]
    where
        [key] is a valid key
        

Deletes a value from Caphpe. Does nothing if the key does not exist. Examples:

delete mykey
        

increment

increment [key] [timeout]?
    where
        [key] is a valid key
        [timeout] is an integer marking seconds
        

Increment a numeric value in Caphpe by 1. If the value is not a numeric value or does not exist nothing is done. Examples:

increment mykey 3600
increment somekey
        

decrement

See increment. This one does the opposite.

has

has [key]
    where
        [key] is a valid key
        

Checks if a value exists for the given key. Returns 1 if does, empty value if not. Examples:

has mykey
has someotherkey
        

get

get [key]
    where
        [key] is a valid key
        

Get a value from Caphpe for a key. Returns the value or an empty string if no value exists for the key. Examples:

get mykey
get somekey
        

flush

flush
    (no parameters)
        

Flushes all data from Caphpe. Returns 1 if successful and an empty string if not. Example:

flush
        

status

status
    (no parameters)
        

Displays a status message. Note: Caphpe currently approximates memory usage per cache item, so there may be some error in the values returned by the status command.

Here is an example output of the status command. Please note the separate header and value lines, with columns separated with a single \t character:

Memory usage (MB)\tItem count\tSmallest item (KB)\tLargest item (KB)\tAverage item (KB)
12.3456\t123\t0.704\t1.567\t0.888
        

Example:

status
        

Issues, errors and bugs

Currently Caphpe is in an unstable development phase. Bugs come and go and it may sometimes not work at all.

If you encounter stuff that does not work as documented or does not work at all, please create an issue over at the GitHub issue tracker.

Known issues and limitations

• There is currently no way to get a status report of sorts from Caphpe via the command API, e.g. memory usage, item count, key listing, etc.