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. Checking Access
6. React Component UI
7. Reading & Writing Rules (PHP)
8. REST API
9. Events
10. Custom Providers
11. Built-in Providers
12. Important Notes
13. Database Table Reference

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. Always pass a plugin-specific filter tag to prevent your providers bleeding into other plugins that also use this library.

AccessControlManager owns a RuleQuery internally. Instantiating it registers RuleTable via BerlinDB, which creates or upgrades the {prefix}wpb_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.

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 has four states 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.

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

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: .../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

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.

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}wpb_access_control · DB layer: BerlinDB ^2.0 · Schema version: 202605120001

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

Rule storage convention