📝 The Role That Kept Forgetting What It Learned
A plugin that adds custom capabilities to an existing role, say granting Editors the ability to manage a custom post type, typically does that work inside its activation hook, under the reasonable assumption that activation happens exactly once, the moment the plugin is installed and turned on. In practice, an activation hook can run again any time the plugin is deactivated and reactivated, restored from a staging environment sync, or reset by a site management tool, and if that hook unconditionally re-adds the role’s default capability set rather than checking what’s already there, any capability an administrator manually added or removed afterward, directly through a role-editor plugin or custom code, gets silently overwritten back to the plugin’s original defaults the next time activation fires.
🔎 The Problem
// Runs every time the plugin is activated - which site owners
// reasonably assume means "once," but can actually happen again
// on reactivation, a staging-to-production sync, or a reset tool.
register_activation_hook( __FILE__, 'myplugin_activate' );
function myplugin_activate() {
$role = get_role( 'editor' );
// BUG: unconditionally re-adds capabilities every time this
// runs, with no check for what an admin may have deliberately
// changed since the first activation.
$role->add_cap( 'manage_custom_catalog' );
$role->add_cap( 'publish_catalog_items' );
// An admin later used a role-editor plugin to specifically
// REMOVE 'publish_catalog_items' from Editors, restricting
// that capability to Administrators only. The next time this
// plugin is deactivated and reactivated - even just to test
// something unrelated - that manual restriction is silently
// undone, and Editors can publish catalog items again.
}
✅ Fix: Make Activation Idempotent, Not Destructive
- Store a version number or a one-time flag in the plugin’s own options when capabilities are first added, and check it inside the activation hook before re-adding anything, so a second or third activation doesn’t blindly repeat work that may have been deliberately reversed since.
- Where a capability genuinely needs to be guaranteed present as part of an upgrade routine, check the role’s current capabilities first and only add what’s missing, logging or surfacing the change, rather than unconditionally overwriting whatever an administrator has since customized.
- Document clearly, in the plugin’s own settings screen, which roles and capabilities it manages automatically, so an administrator who customizes role capabilities through a separate tool knows exactly which changes a future reactivation of this specific plugin might silently undo.
⚠️ Why This Is Easy to Miss
- Activation hooks are documented as running on activation, which every site owner reasonably reads as ‘this happens once, when I first install the plugin,’ with nothing in that documentation calling out the much less obvious cases where the same hook fires again later.
- The capability change happens instantly and without any confirmation dialog or log entry the moment the plugin is reactivated, so unless an administrator happens to notice a specific permission has changed during routine use, the reset can go unnoticed for a long time after it happens.
An activation hook that only ever adds capabilities isn’t remembering your site’s configuration – it’s reapplying its own defaults every time it gets the chance, whether or not you’d already decided otherwise.
