Plesk key-value storage is used for storing user settings or secret keys. To access the Plesk key-value storage, use the pm_Settings class. Keys and values are stored in the context of an extension.

If you need to assign a variable, use the method

• set()

pm_Settings::set('authToken', $authToken);

Special case:

pm_Settings::set('something', null);

Now you can retrieve the value of this variable by using the method

• get()

$authToken = pm_Settings::get('authToken');

An additional optional parameter can be used to specify a default value to be returned in case the corresponding key is not found:

$message = pm_Settings::get('message', 'default message');

To obtain access to them in some places of code, initialize the context first:

pm_Context::init('extension-id');

It is mandatory to initialize the context in the following places in code:

• Scheduled tasks.
• Post- and Pre- installation scripts.
• Event handlers.

Encrypting Data

The key-value storage allows for storing and retrieving data in encrypted form.

• setEncrypted() method stores an encrypted value in the key-value storage

pm_Settings::setEncrypted('secretValue', $secretValue);

• getDecrypted() method retrieves an encrypted value from the key-value storage.

$secretValue = pm_Settings::getDecrypted('secretValue');

Key-value Cleaning

Starting with Plesk 12.5, it is possible to clear the extension settings using the clean() method. You can use it to add the Reset to default button to the UI of your extension.

Remarks

Value length is limited to 2000 characters

The string length of the stored value is limited to 2000 characters.

Precautions:

• Avoid storing values that are larger than 2000 characters in length.

  Note: Before Plesk 17.0, only the first 2000 characters will be saved, the remainder will be truncated. Beginning with Plesk 17.0, the value will not be saved at all, an exception will be thrown.

• Avoid storing values that can tend to grow in length, for example, a list of domains as a JSON string.

Testing tips:

• Check lengths of values stored by the extension.
• For the stored values whose length is near 2000 characters, check how the extension validates the value’s string length.
• Test extension on multiple domains or in similar conditions (multiplying entities), depending on the extension’s functionality.

Values are saved in plain text

The data saved in the key-value storage is stored as plain text and is not encrypted.

Avoid storing sensitive information.

Key-value storage is subject to server backup and restore

Plesk key-value storage is backed up as part of the server back up. It is therefore possible that restoring a Plesk server from a backup may revert some or all changes done to the key-value storage data by the extension.

Testing tips:

Check that the extension behaves correctly following a server restore. For example, create a backup, remove some extension-related entries from the key-value storage, restore the server from the backup, make sure the extension functions as expected.

Make use of Plesk object GUIDs

To ensure there are no object collisions, use Plesk object GUIDs (or IDs, when GUIDs are unavailable) to uniquely identify domains, users, etc. This will help safely deal with situations when an object is removed from system by one user and then created with the same name by a different user.

Testing tips:

Check that GUIDs are used as object identifiers.

Clearing key-value storage at extension’s removal

Key-value storage is automatically cleared when extension is removed. You don’t need to do it yourself in pre-uninstall.php script.