• Developer guides

Data storage

Whereas File storage counts towards the total storage used by the community, using key-value data storage is free.

Data storage is also limited to a module-scope: you can only access data added by your own module, in the current community.

There are two ways to use data storage:

  • Collections
  • Manual key-value storage

Both are accessable through $this->storage.

Using collections

Collections are groups of items, comparable to a traditional database table, but without a pre-set data scheme.

Look at the Collections API documentation, or take a look at the following example to learn how they work:

Example

// Initialize collection
$messages = $this->storage->collection('messages');

// Add a new message
$new_id = $messages->add([
    'from' => 'Thomas',
    'to' => 'Julie',
    'body' => 'How about dinner tonight?'
]);
echo 'Added message with id: ' . $new_id;

// List all the messages
$list = $messages->list();
foreach($list as $message){
    echo 'Message from ' . $message['from'] . ' to ' . $message['to'] . ': ' . $message['body'];
}

// Delete a message
$messages->delete($new_id);

Key-value storage

Saving a data object

You can save data objects using the method keyvalue() with 2 parameters:

  • string $key – The key of the data object
  • mixed $value – The (new) value of the data object

Example

<?php

// Save object with key 'myStorageKey'

$request = $this->storage->keyvalue('myStorageKey', 'myStorageValue');
if ($request === true) {
    echo ('Storage object saved.');
} else {
    echo ('Unknown error occurred.');
}

Retrieving a data object

You can retrieve data objects using the method keyvalue() with 1 parameter:

  • string $key – The key of the data object

Example

<?php

// Get the value for key 'myStorageKey'

$value = $this->storage->keyvalue('myStorageKey');
if ($value !== false) {
    echo ('The value is: ' . $value);
} else {
    echo ('Something went wrong. Probably the key did not exist yet.');
}

Listing data objects

You can list data using the method keyvalue_list(). It returns associative array with keys and values. This method takes 1 argument, which is optional:

  • string $query – A query selector supporting some basic regular expressions:
    • my% matches every key that starts with my
    • %end matches every key that ends with end
    • my%end matches every key that starts with my and ends with end
    • %my% matches every key that contains my
    • not: in front of the query reverses the effect: it returns the objects that didn’t match the query.
    • When ommitted, every key is matched

Example

<?php

// List objects with a key starting with 'my'
// Use keyvalue_list() without arguments to get all keys

$keys = $this->storage->keyvalue_list('my%');
if ($keys !== false) {
    if (count ($keys) > 0) {
        var_dump ($keys);
    } else {
        echo ('No matching objects found.');
    }
} else {
    echo ('Unknown error occurred.');
}

Removing a data object

You can remove data objects using the method keyvalue_delete().

Example

<?php

// Remove the object with key 'myStorageKey'

$request = $this->storage->keyvalue_delete('myStorageKey');
if ($request === true) {
    echo ('Storage object removed.');
} else {
    echo ('Unknown error occurred. The key probably doesn\'t exist.');
}