I had a client running a critical membership site. We’d built some custom roles and capabilities using the tried-and-true WordPress approach for years. Everything was solid, battle-tested. Then, after a recent WordPress Core Updates rollout—specifically WordPress 6.9 Release Candidate 1 was out, as discussed in the latest dev chat agenda—some users suddenly couldn’t access parts of the admin dashboard they absolutely needed. Total headache.
You see, WordPress isn’t a static target. The core team is constantly improving things, pushing out new features and refining old APIs. Sometimes, these “incremental improvements,” as they were discussing in the dev chat, can introduce subtle shifts. In this case, it was the new Abilities API in WordPress 6.9 that caused the ruckus. Our custom roles, which relied on filtering `user_has_cap`, were suddenly behaving erratically. Users with a custom “bbioon_manager” role, for instance, were locked out of their custom post type editing screen. Not good. At all.
My first thought, and probably yours too if you’ve been in the game long enough, was to just whack a `remove_cap` and `add_cap` pair into an `init` hook, trying to forcibly reset the permissions. It’s a quick-and-dirty fix that *feels* right in the heat of the moment, but it’s a hack. It only masked the real issue and, trust me on this, would have been a nightmare to maintain across future WordPress Core Updates. You’d be chasing your tail with every patch release.
Understanding the New Abilities API in WordPress 6.9
The real fix, as always, is to understand what’s actually changed. WordPress 6.9 introduced enhancements to the Abilities API. While `user_has_cap` still works, changes in how capabilities are evaluated under the hood can lead to unexpected conflicts if your custom logic isn’t aligned with the new flow. The updated API aims for better performance and flexibility, but it demands a different approach for granular control.
Instead of battling core with brute-force `add_cap` calls, the robust way forward is to leverage the new, intended extension points. This often means hooking into filters that expose the capability checks at a deeper level or registering custom capability types explicitly. Here’s a simplified example of how you might ensure a custom `bbioon_manager` role retains a specific capability, acknowledging the new Abilities API structure without fighting it:
<?php
/**
* Register custom capabilities for the bbioon_manager role.
*
* This function adds specific capabilities to the 'bbioon_manager' role,
* ensuring they are correctly registered and recognized by the Abilities API.
*
* @since 1.0.0
*/
function bbioon_register_custom_capabilities() {
$role = get_role( 'bbioon_manager' );
if ( $role ) {
// Ensure the role can edit its own custom post type.
$role->add_cap( 'edit_bbioon_custom_posts' );
$role->add_cap( 'read_bbioon_custom_posts' );
$role->add_cap( 'delete_bbioon_custom_posts' );
// Add more specific capabilities as needed.
}
}
add_action( 'admin_init', 'bbioon_register_custom_capabilities' );
/**
* Filter user capabilities to ensure specific custom caps are granted.
*
* This filter acts as a fallback or a way to enforce capabilities
* that might be affected by subtle changes in core, specifically
* with the new Abilities API.
*
* @param array $allcaps The user's capabilities.
* @param array $caps Required capabilities.
* @param array $args Arguments that accompany the capability check.
* @param WP_User $user The user object.
* @return array Modified capabilities.
*/
function bbioon_filter_user_capabilities( $allcaps, $caps, $args, $user ) {
if ( in_array( 'bbioon_manager', (array) $user->roles ) ) {
// Always grant this specific cap to bbioon_manager.
$allcaps['edit_bbioon_custom_posts'] = true;
// Add other necessary capabilities for this role here.
}
return $allcaps;
}
add_filter( 'user_has_cap', 'bbioon_filter_user_capabilities', 10, 4 );
/**
* Register a custom post type with appropriate capability_type.
*
* This is crucial for the Abilities API to correctly map
* capabilities to our custom post type.
*
* @since 1.0.0
*/
function bbioon_register_custom_post_type() {
$labels = array(
// ... (standard labels) ...
);
$args = array(
'labels' => $labels,
'public' => true,
'capability_type' => array( 'bbioon_custom_post', 'bbioon_custom_posts' ), // Plural form matters!
'map_meta_cap' => true, // Important for custom capabilities.
'hierarchical' => false,
'menu_icon' => 'dashicons-admin-post',
'supports' => array( 'title', 'editor', 'author', 'thumbnail' ),
'has_archive' => true,
'rewrite' => array( 'slug' => 'bbioon-items' ),
'query_var' => true,
);
register_post_type( 'bbioon_custom_post', $args );
}
add_action( 'init', 'bbioon_register_custom_post_type' );
/**
* Map custom meta capabilities to primitive capabilities.
*
* This tells WordPress how our custom capabilities (e.g., 'edit_bbioon_custom_post')
* relate to the standard capabilities it understands.
*
* @param array $caps Primitive capabilities required.
* @param string $cap Capability being checked.
* @param int $user_id The user ID.
* @param array $args Arguments for the capability check.
* @return array Filtered capabilities.
*/
function bbioon_map_meta_caps( $caps, $cap, $user_id, $args ) {
if ( 'edit_bbioon_custom_post' == $cap || 'delete_bbioon_custom_post' == $cap || 'read_bbioon_custom_post' == $cap ) {
$post = get_post( $args[0] );
$post_type = get_post_type_object( $post->post_type );
$caps = array();
if ( 'edit_bbioon_custom_post' == $cap ) {
if ( $user_id == $post->post_author ) {
$caps[] = $post_type->cap->edit_posts;
} else {
$caps[] = $post_type->cap->edit_others_posts;
}
} elseif ( 'delete_bbioon_custom_post' == $cap ) {
if ( $user_id == $post->post_author ) {
$caps[] = $post_type->cap->delete_posts;
} else {
$caps[] = $post_type->cap->delete_others_posts;
}
} elseif ( 'read_bbioon_custom_post' == $cap ) {
$caps[] = $post_type->cap->read;
}
}
return $caps;
}
add_filter( 'map_meta_cap', 'bbioon_map_meta_caps', 10, 4 );
Notice the `capability_type` in `register_post_type` and the `map_meta_cap` filter. This is where you tell WordPress explicitly how your custom capabilities should behave and which core capabilities they map to. The Abilities API is smarter now; it expects this kind of clear definition, rather than just simple `user_has_cap` filters to catch everything. This way, your custom roles integrate seamlessly, even with core enhancements.
The Long and Short of It: Test and Adapt
The lesson here is twofold: First, always pay attention to the dev notes for major WordPress releases. They’re there for a reason. Second, never assume your old custom code will just ‘keep working’ through significant core updates without verification. Things change. APIs evolve. The platform gets better, but sometimes that means adapting your approach. Running beta releases and testing on staging environments is your best friend. It gives you a heads-up on potential conflicts, like the one that caught my client off guard, before they hit production. It’s all about being proactive, not reactive.
Look, this stuff gets complicated fast. If you’re tired of debugging someone else’s mess and just want your site to work, drop my team a line. We’ve probably seen it before.
Leave a Reply