Download the PHP package wpboilerplate/wpb-access-control without Composer

wpb-access-control

Extensible per-resource access control library for WordPress plugins.

Answers one question: "Does this user have access to this resource?"

The library owns its own database table (managed by BerlinDB), ships WordPress role and user providers out of the box, exposes a REST API for managing rules from any client, and provides a ready-to-drop-in React component so consuming plugins get a full admin UI without writing any front-end code.

Table of Contents

1. Requirements
2. Installation
3. PHP Setup
4. Complete Integration Example
5. Two Plugins on One Site
6. Checking Access
7. React Component UI
8. Reading & Writing Rules (PHP)
9. REST API
10. Events
11. Custom Providers
12. Built-in Providers
13. Important Notes
14. Database Table Reference
15. Upgrading from 1.x

Requirements

Installation

Your composer.json must include Jetpack Autoloader:

Why Jetpack Autoloader is mandatory

If two plugins install this library at different versions, PHP throws a fatal "class already declared" error. Jetpack Autoloader scans every installed plugin, finds all copies, and loads only the newest one.

In your plugin's main file, require the Jetpack Autoloader entry point — not the standard vendor/autoload.php:

PHP Setup

1. Boot the manager

Declare $manager at file scope (outside any closure) so every subsequent hook can capture it via use. Pass two arguments:

1. A plugin-specific provider filter tag so your providers don't bleed into other plugins using the library.
2. A per-plugin table slug (must match ^[a-z0-9_]{1,32}$) so your database table, object-cache group, and REST routes are isolated from every other plugin embedding the library.

AccessControlManager owns a RuleQuery internally. Instantiating it registers RuleTable via BerlinDB, which creates or upgrades the {prefix}my_plugin_access_control table automatically on admin_init.

Need to wait for other plugins first? Use a reference capture instead:

2. Register the REST API

Call register_rest_api() from rest_api_init to expose the wpb-ac/v1 endpoints. The consuming plugin decides whether to enable them.

Complete Integration Example

Below is a self-contained my-plugin.php showing all pieces wired together: initialising the manager, registering the REST API, enqueueing the React UI, rendering the mount point, and checking access.

Key points:

• $manager is declared once at file scope; all hooks capture it with use ( $manager ).
• add_submenu_page() (or add_menu_page()) returns the hook suffix — store it and compare in admin_enqueue_scripts to load assets only on your page.
• vendor/autoload_packages.php is the Jetpack Autoloader entry point, not the standard vendor/autoload.php.

Two Plugins on One Site

The whole reason $table_slug exists: when two consumer plugins embed this library on the same WordPress install, each gets its own table, cache group, transient keys, and REST routes. They cannot collide. Pick a distinct slug per plugin — that is the only coordination required between them.

Plugin A — mcp-server

Plugin B — abilities-manager

What you actually get

Both managers can call $manager->register_rest_api() in the same request; the slug-scoped paths mean WordPress registers two distinct sets of routes instead of clobbering each other.

Picking a slug. Must match ^[a-z0-9_]{1,32}$ — lowercase ASCII letters, digits, and underscores; 1 to 32 characters. Invalid slugs throw \InvalidArgumentException at construction time, never reaching SQL. Recommend using your plugin's composer.json name (or a short form of it) so the slug is stable and obviously yours.

Checking Access

Access hierarchy

React Component UI

The library ships a pre-built React component that renders a complete Access Control settings panel. Drop it into any WordPress admin page and it wires itself to the wpb-ac/v1 REST API automatically.

What it looks like

The component is driven by a single "Who can access" dropdown:

Custom providers registered via the filter also appear in the dropdown. If they expose options, checkboxes are rendered automatically.

Third-party integrations (BuddyBoss, MemberPress, LearnDash, LifterLMS, Paid Memberships Pro, Restrict Content Pro, WooCommerce Memberships, s2Member, Wishlist Member, Memberium) shipped in the library through v2.0.x have moved to a separate add-on plugin: AcrossAI User Access Pro (acrossai/user-access-pro). Install and activate it and the corresponding option appears in the dropdown automatically whenever the underlying plugin is active — no add_filter wiring required. See "Writing a third-party provider add-on" below to build your own.

Enqueue the built assets

The compiled assets live in assets/build/. The .asset.php file declares all required WordPress script dependencies so you never need to list them manually.

Getting the right hook suffix: add_menu_page() and add_submenu_page() both return a hook suffix string (e.g. "settings_page_my-plugin"). Capture that return value and compare it in admin_enqueue_scripts so assets load only on your page.

Render target

Add an empty <div> with the id wpb-access-control anywhere in your admin page template. The component mounts itself automatically.

Component props reference

Using the component as a JS import

If your plugin has its own webpack build, import the component directly:

Note: When importing directly the nonce middleware must be registered before the first apiFetch call. The auto-render path (index.js) handles this automatically.

Namespace slashes

Namespaces containing slashes (e.g. procureco/v1) are handled automatically by the component — each segment is encodeURIComponent-encoded so they reach the REST API as %2F.

Reading & Writing Rules (PHP)

Use RuleQuery when you need to read or write rules from PHP directly.

You can also access the same instance through the manager:

REST API

REST namespace: wpb-ac/v1. Every route is scoped under the consumer's table slug — {slug} in the paths below is the same string you pass to new AccessControlManager(...).

All endpoints require manage_options (administrator) by default. Use the wpb_access_control_rest_permission filter to override.

Endpoints

Slashes in namespace: The {namespace} URL segment cannot contain literal slashes — encode them as %2F: .../my_plugin/rules/procureco%2Fv1/my-key. The {key} segment allows literal slashes.

Request / response shapes

GET /rules/{namespace}/{key}

PUT /rules/{namespace}/{key} — body:

Response:

DELETE /rules/{namespace}/{key}

DELETE /namespaces/{namespace}

GET /providers

GET /users?search=jane&limit=10

Authentication

WordPress admin (nonce)

Include the wp_rest nonce in the X-WP-Nonce header:

Application Passwords (external clients)

Code examples

cURL

PHP (wp_remote_request)

@wordpress/api-fetch

Vanilla fetch

Permission filter

Override who may call any endpoint:

Write authorization filter

Restrict which namespace/key pairs may be modified:

Events

wpb_access_control_denied

Fires whenever user_has_access() returns false (steps 3–5 of the hierarchy).

wpb_access_control_saved

Fires after any successful write via the REST API (PUT rule, DELETE rule, DELETE namespace). $ac_key is '' on a clear.

Custom Providers

Register

The filter tag must match the string passed to AccessControlManager. Register at init priority ≤ 4 (the filter fires at priority 5).

Contract (AbstractProvider)

Example provider

Providers and their options are surfaced by GET /wpb-ac/v1/providers, so any front-end UI (including the built-in React component) can render the correct controls dynamically without hard-coding provider IDs.

Built-in Providers

Providers for BuddyBoss, MemberPress, LearnDash, LifterLMS, Paid Memberships Pro, Restrict Content Pro, WooCommerce Memberships, s2Member, Wishlist Member, and Memberium ship in the AcrossAI User Access Pro add-on plugin — not in this library. See "Writing a third-party provider add-on" below for how to add your own.

WpRoleProvider filters

WpUserProvider

Options are user IDs stored as strings ("42"), not usernames or emails — sanitize_key() strips @ and ., so email addresses would be corrupted.

WpCapabilityProvider

Options are WordPress capability slugs (e.g. install_plugins, edit_posts, manage_options). The list is built dynamically from every role returned by wp_roles() — capabilities added by plugins like WooCommerce, Members, or User Role Editor appear automatically. Access is granted when user_can() returns true for any selected capability.

Writing a third-party provider add-on

Anyone can ship a WordPress plugin that adds providers to every consumer of wpb-access-control on the site, with no per-consumer bootstrap code. The reference implementation is AcrossAI User Access Pro, which packages 10 membership-plugin integrations this way.

The mechanism is one global filter registered by the library since v3.0.0:

It fires once per consumer instance during load_providers(), before the consumer-specific filter, and receives the running providers array plus the consumer's $table_slug. Any provider you append here is visible to that consumer's REST /providers endpoint and its React dropdown.

Minimal add-on skeleton

Providers extend \WPBoilerplate\AccessControl\AbstractProvider and implement get_id(), get_label(), get_options(), and user_has_access(). Override is_available() when the provider depends on an optional plugin — the library's REST layer forwards that flag to the React UI so unavailable options are hidden automatically.

To scope an add-on to specific consumers, inspect the $table_slug argument and short-circuit for consumers you don't want to inject into.

Consumers can still filter the resulting list per-instance via the consumer-specific filter passed to AccessControlManager, so they retain final say over what shows up in their own UI.

Important Notes

Filter tag isolation

Always pass a plugin-specific tag to AccessControlManager. Two plugins sharing the same filter tag will bleed providers into each other's checks.

Table management

BerlinDB handles all table creation and upgrades automatically on admin_init. No activation hook is needed — instantiating new AccessControlManager(...) is sufficient.

Caching

Always use RuleQuery::set_rule() and clear_rule(). Direct $wpdb writes bypass BerlinDB's object cache and leave it stale.

Administrator bypass is unconditional

Any user with manage_options always passes user_has_access() regardless of the stored rule. This cannot be disabled.

Uninstall cleanup

Each consuming plugin removes its own rows:

Multisite

The table uses $wpdb->prefix — each sub-site has its own {prefix}wpb_access_control table. Network-wide rules must be handled by the consuming plugin.

Database Table Reference

Table: {prefix}{slug}_access_control — one per consumer (e.g. wp_mcp_access_control, wp_abilities_access_control). DB layer: BerlinDB ^3.0 · Schema version: 202605120001

Each consumer's table is created on the first admin_init after the manager is instantiated. The schema is identical across consumers; only the name and the wpb_ac_{slug}_db_version option differ.

Indexes: PRIMARY KEY (id) · UNIQUE (namespace, key(191), access_control_value) · KEY (namespace, key(191))

Rule storage convention

Upgrading from 1.x

v2.0.0 introduces a required $table_slug constructor argument. Each consumer plugin now owns its own table, object-cache group, and REST route prefix — fixing the silent collision when two plugins embed the library on the same WordPress install.

1. Update the manager constructor

Invalid slugs throw \InvalidArgumentException immediately.

2. Update wpbAcConfig / React props

3. Update REST URLs

Every endpoint moves under /wpb-ac/v1/{slug}/...:

4. (Optional) Migrate existing rows

The library does not auto-migrate from {prefix}wpb_access_control. Run a one-off SQL copy from your plugin's update routine, filtering by the namespaces your plugin owns:

Drop the legacy table only after every consumer plugin on the site has upgraded — otherwise an un-upgraded plugin will lose its rules.