Skip to main content

benecaster_store_secret()

Utilities Free 
benecaster_store_secret( string $addon_slug, string $name, string $value ): bool

Stores a secret for an add-on, such as the API key a podcaster brings for a provider, encrypted, so your add-on never keeps it in clear. Read it back with benecaster_get_secret() and remove it with benecaster_delete_secret().

Benecaster encrypts it with the same key it uses for payment credentials: the BENECASTER_PAYMENT_CRYPTO_KEY constant in wp-config.php when the site sets one, otherwise a key it generates and stores. A site that has set the constant is already covered, and there is no extra key to back up.

Parameters

Name Type Default Required Description
addon_slug string — Yes Your add-on's slug, in either form (my-addon or benecaster-addon-my-addon); both name the same add-on.
name string — Yes Your own name for the secret, e.g. api_key. Passed through sanitize_key(), so use lower case.
value string — Yes The secret itself. An empty string deletes it.

Return Value

Type: bool

true when the secret was stored (or, for an empty value, removed). false when the slug or name is empty after cleaning, or no encryption key can be stored.

Example

// In your settings route's callback, after checking manage_options.
$key = trim( (string) $request['api_key'] );

if ( '' !== $key && ! benecaster_store_secret( 'my-addon', 'api_key', $key ) ) {
    return new WP_Error( 'my_addon_key_not_saved', __( 'The key could not be saved.', 'my-addon' ), [ 'status' => 500 ] );
}

// Report whether a key is set, never the key itself.
return [ 'api_key_set' => null !== benecaster_get_secret( 'my-addon', 'api_key' ) ];

Notes

Store add-on secrets here, never in an option of your own. Because Benecaster keeps the secret, its key repair can find it. When a site adds BENECASTER_PAYMENT_CRYPTO_KEY after credentials were saved, the admin notice's Re-encrypt with the key in wp-config.php button moves every stored credential onto the new key and deletes the old one. A secret kept anywhere else would be left under the deleted key and could never be read again.

Never send a secret to the browser. A settings route should report whether a key is set, yes or no, never the value.

There is no capability check: check manage_options on the route that saves it. A site's add-on secrets share one stored row, so two different secrets saved in the same instant can lose one. Storing a secret does not depend on the add-on's license; whether the add-on may use it is your own entitlement check.

Need this built rather than just documented? See our services →