From 5c9d92ca1e59af9e1b990fb01f84d7263bc9e77b Mon Sep 17 00:00:00 2001 From: vinay chavada Date: Wed, 13 Aug 2025 12:23:53 +0530 Subject: [PATCH 1/2] Add developer documentation for Abilities API --- docs/getting-started.md | 0 docs/intro.md | 0 docs/registering-abilities.md | 0 docs/rest-api-endpoints.md | 0 docs/using-abilities.md | 0 5 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/getting-started.md create mode 100644 docs/intro.md create mode 100644 docs/registering-abilities.md create mode 100644 docs/rest-api-endpoints.md create mode 100644 docs/using-abilities.md diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/intro.md b/docs/intro.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/registering-abilities.md b/docs/registering-abilities.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/rest-api-endpoints.md b/docs/rest-api-endpoints.md new file mode 100644 index 00000000..e69de29b diff --git a/docs/using-abilities.md b/docs/using-abilities.md new file mode 100644 index 00000000..e69de29b From 1cc557966ae385e87ca4e69fb3a2ceaa589a2f0b Mon Sep 17 00:00:00 2001 From: vinay chavada Date: Wed, 13 Aug 2025 12:35:46 +0530 Subject: [PATCH 2/2] Add developer documentation for Abilities API (#5) --- docs/README.md | 21 +++++++++++++++++++++ docs/getting-started.md | 28 ++++++++++++++++++++++++++++ docs/intro.md | 19 +++++++++++++++++++ docs/registering-abilities.md | 28 ++++++++++++++++++++++++++++ docs/rest-api-endpoints.md | 29 +++++++++++++++++++++++++++++ docs/using-abilities.md | 28 ++++++++++++++++++++++++++++ 6 files changed, 153 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..4fcdc166 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,21 @@ +Add this near the top after the main heading: + +````md +## Quick Start + +```php +// Register a custom ability +register_ability( + 'my_plugin_edit_data', + array( + 'label' => __( 'Edit plugin data', 'my-plugin' ), + 'description' => __( 'Allows editing of My Plugin data.', 'my-plugin' ), + ) +); + +// Check if a user has the ability +if ( user_can( get_current_user_id(), 'my_plugin_edit_data' ) ) { + // Perform restricted action +} +``` +```` diff --git a/docs/getting-started.md b/docs/getting-started.md index e69de29b..44e9d11f 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -0,0 +1,28 @@ +# Getting Started + +## Prerequisites +- WordPress development environment (e.g., LocalWP, Docker, XAMPP) +- PHP 7.4+ (recommended PHP 8.0+) +- Git for version control +- Composer (optional, if the package will be installed via Composer in the future) + +## Steps + +1. **Clone or Install** + ```bash + git clone https://github.com/YOUR-USERNAME/abilities-api.git + cd abilities-api + +2. **Activate in WordPress** + +Place the abilities-api code inside your wp-content/plugins folder. + +Activate it from the WordPress admin. + +3. **Verify** + +Check that the Abilities API functions (e.g., register_ability()) are available. + +Optionally, use WP-CLI or REST API to confirm abilities can be listed. + +Next: Registering Abilities \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index e69de29b..3c2b82b2 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -0,0 +1,19 @@ +# Introduction to the Abilities API + +The Abilities API is a proposed WordPress feature for defining and checking custom permissions (called "abilities") in a standardized way. + +It allows plugins and themes to: + +- Register new abilities +- Assign abilities to specific roles or users +- Check if a user has a specific ability before performing an action +- Expose abilities through the REST API for integration with external systems + +This documentation will guide you through getting started, registering abilities, using abilities in your code, and interacting with the REST API. + +--- +**Related Docs:** +- [Getting Started](./getting-started.md) +- [Registering Abilities](./registering-abilities.md) +- [Using Abilities](./using-abilities.md) +- [REST API Endpoints](./rest-api-endpoints.md) diff --git a/docs/registering-abilities.md b/docs/registering-abilities.md index e69de29b..a8034bf6 100644 --- a/docs/registering-abilities.md +++ b/docs/registering-abilities.md @@ -0,0 +1,28 @@ +# Registering Abilities + +The Abilities API allows you to define new permissions in WordPress. + +## Basic Example + +```php + +register_ability( + 'my_plugin_edit_data', + array( + 'label' => __( 'Edit My Plugin Data', 'my-plugin' ), + 'description' => __( 'Allows editing of data in My Plugin.', 'my-plugin' ), + ) +); +``` + +Next Step : **Parameters** + +Name (string) – Unique identifier for the ability. + +Args (array) – Associative array with: + +label (string) – Human-readable name. + +description (string) – Short explanation. + +Tip: Always prefix your ability names to avoid conflicts. diff --git a/docs/rest-api-endpoints.md b/docs/rest-api-endpoints.md index e69de29b..22360a06 100644 --- a/docs/rest-api-endpoints.md +++ b/docs/rest-api-endpoints.md @@ -0,0 +1,29 @@ +# REST API Endpoints + +The Abilities API exposes REST routes for managing abilities. + +## List Abilities +```bash +GET /wp-json/abilities/v1/list + +Response: + +[ + { + "name": "my_plugin_edit_data", + "label": "Edit My Plugin Data", + "description": "Allows editing of data in My Plugin." + } +] + + + 2. **Register Ability** : + +POST /wp-json/abilities/v1/register +Content-Type: application/json + +{ + "name": "my_plugin_view_stats", + "label": "View Plugin Stats", + "description": "Allows viewing analytics data." +} diff --git a/docs/using-abilities.md b/docs/using-abilities.md index e69de29b..1343f227 100644 --- a/docs/using-abilities.md +++ b/docs/using-abilities.md @@ -0,0 +1,28 @@ +# Using Abilities + +After registering abilities, you can check them in your code to control access. + +## Check if Current User Has Ability + +```php + +if ( user_can( get_current_user_id(), 'my_plugin_edit_data' ) ) { + // Perform action +} else { + wp_die( __( 'You do not have permission to do this.', 'my-plugin' ) ); +} +``` + +``` + +```Abilities can be assigned via: + +WordPress role management functions + +Custom role editing plugins + +Direct database queries (not recommended unless necessary) + +Removing Abilities : + +remove_ability( 'my_plugin_edit_data' );