Updating Plugins for Craft 3.1

Here’s what you should consider testing your plugins for Craft 3.1 compatibility.

Don’t Change Database Data Directly #

Review the list of things Craft is now storing in the project config, and make sure you’re not manipulating that data directly in the database anywhere, such as from your plugin migrations. (The list includes plugins’ global settings.)

You can either use service APIs (e.g. craft\services\Fields::saveField()), or manipulate the project config data directly using craft\services\ProjectConfig::set(), which will trigger event listeners to update database data when necessary.

Either way, be especially careful about doing this from migrations, where changes to the project config (directly or indirectly) could result in a sync conflict. Take a minute to read the Project Config Migrations documentation, which explains how to avoid that.

Store UIDs Instead of IDs #

Plugin settings are now stored in the project config. If your plugin is storing references to sections, category groups, or anything else that’s now stored in the project config, you should update those references to use UIDs instead of IDs. That’s because their IDs will potentially be different on each environment, but their UIDs will always stay the same across all environments.

Update Element Source Key References #

The source keys used for assets, entries, categories, tags, and users have changed in Craft 3.1:

Element Type	Old Source Format	New Source Format
Assets	folder:<ID>	folder:<UID>
Entries	section:<ID>	section:<UID>
Categories	group:<ID>	group:<UID>
Tags	taggroup:<ID>	taggroup:<UID>
Users	group:<ID>	group:<UID>

Update Live Preview Initialization Settings #

If your plugin implements Live Preview support, you’ll need to start hashing the previewAction key you pass to Craft.LivePreview.init().

// Old
$jsSettings = Json::encode([
    'previewAction' => 'entries/preview-entry',
    // ...
]);
$this->view->registerJs("Craft.LivePreview.init($jsSettings);");

// New
$jsSettings = Json::encode([
    'previewAction' => Craft::$app->security->hashData('entries/preview-entry'),
    // ...
]);
$this->view->registerJs("Craft.LivePreview.init($jsSettings);");

Consider Adding Project Config and Soft-Delete Support #

If your plugin defines its own configurable component types, you may want to consider adding project config and/or soft-delete support to it.

If you have any questions or comments, please let us know!