212 lines
6.6 KiB
Markdown
212 lines
6.6 KiB
Markdown
# 4. Using Abilities (`wp_get_ability`, `wp_get_abilities`)
|
||
|
||
Once abilities are registered, they can be retrieved and executed using global functions from the Abilities API.
|
||
|
||
## Getting a Specific Ability (`wp_get_ability`)
|
||
|
||
To get a single ability object by its name (namespace/ability-name):
|
||
|
||
```php
|
||
/**
|
||
* Retrieves a registered ability using Abilities API.
|
||
*
|
||
* @param string $name The name of the registered ability, with its namespace.
|
||
* @return ?WP_Ability The registered ability instance, or null if it is not registered.
|
||
*/
|
||
function wp_get_ability( string $name ): ?WP_Ability
|
||
|
||
// Example:
|
||
$site_info_ability = wp_get_ability( 'my-plugin/get-site-info' );
|
||
|
||
if ( $site_info_ability ) {
|
||
// Ability exists and is registered
|
||
$site_info = $site_info_ability->execute();
|
||
if ( is_wp_error( $site_info ) ) {
|
||
// Handle WP_Error
|
||
echo 'Error: ' . $site_info->get_error_message();
|
||
} else {
|
||
// Use $site_info array
|
||
echo 'Site Name: ' . $site_info['name'];
|
||
}
|
||
} else {
|
||
// Ability not found or not registered
|
||
}
|
||
```
|
||
|
||
## Getting All Registered Abilities (`wp_get_abilities`)
|
||
|
||
To get an array of all registered abilities:
|
||
|
||
```php
|
||
/**
|
||
* Retrieves all registered abilities using Abilities API.
|
||
*
|
||
* @return WP_Ability[] The array of registered abilities.
|
||
*/
|
||
function wp_get_abilities(): array
|
||
|
||
// Example: Get all registered abilities
|
||
$all_abilities = wp_get_abilities();
|
||
|
||
foreach ( $all_abilities as $name => $ability ) {
|
||
echo 'Ability Name: ' . esc_html( $ability->get_name() ) . "\n";
|
||
echo 'Label: ' . esc_html( $ability->get_label() ) . "\n";
|
||
echo 'Description: ' . esc_html( $ability->get_description() ) . "\n";
|
||
echo "---\n";
|
||
}
|
||
```
|
||
|
||
## Executing an Ability (`$ability->execute()`)
|
||
|
||
Once you have a `WP_Ability` object (usually from `wp_get_ability`), you execute it using the `execute()` method.
|
||
|
||
```php
|
||
/**
|
||
* Executes the ability after input validation and running a permission check.
|
||
*
|
||
* @param mixed $input Optional. The input data for the ability. Defaults to `null`.
|
||
* @return mixed|WP_Error The result of the ability execution, or WP_Error on failure.
|
||
*/
|
||
// public function execute( $input = null )
|
||
|
||
// Example 1: Ability with no input parameters
|
||
$ability = wp_get_ability( 'my-plugin/get-site-info' );
|
||
if ( $ability ) {
|
||
$site_info = $ability->execute(); // No input required
|
||
if ( is_wp_error( $site_info ) ) {
|
||
// Handle WP_Error
|
||
echo 'Error: ' . $site_info->get_error_message();
|
||
} else {
|
||
// Use $site_info array
|
||
echo 'Site Name: ' . $site_info['name'];
|
||
}
|
||
}
|
||
|
||
// Example 2: Ability with input parameters
|
||
$ability = wp_get_ability( 'my-plugin/update-option' );
|
||
if ( $ability ) {
|
||
$input = array(
|
||
'option_name' => 'blogname',
|
||
'option_value' => 'My Updated Site Name',
|
||
);
|
||
|
||
$result = $ability->execute( $input );
|
||
if ( is_wp_error( $result ) ) {
|
||
// Handle WP_Error
|
||
echo 'Error: ' . $result->get_error_message();
|
||
} else {
|
||
// Use $result
|
||
if ( $result['success'] ) {
|
||
echo 'Option updated successfully!';
|
||
echo 'Previous value: ' . $result['previous_value'];
|
||
}
|
||
}
|
||
}
|
||
|
||
// Example 3: Ability with complex input validation
|
||
$ability = wp_get_ability( 'my-plugin/send-email' );
|
||
if ( $ability ) {
|
||
$input = array(
|
||
'to' => 'user@example.com',
|
||
'subject' => 'Hello from WordPress',
|
||
'message' => 'This is a test message from the Abilities API.',
|
||
);
|
||
|
||
$result = $ability->execute( $input );
|
||
if ( is_wp_error( $result ) ) {
|
||
// Handle WP_Error
|
||
echo 'Error: ' . $result->get_error_message();
|
||
} elseif ( $result['sent'] ) {
|
||
echo 'Email sent successfully!';
|
||
} else {
|
||
echo 'Email failed to send.';
|
||
}
|
||
}
|
||
```
|
||
|
||
## Checking Permissions (`$ability->check_permissions()`)
|
||
|
||
You can check if the current user has permissions to execute the ability, also without executing it. The `check_permissions()` method returns either `true`, `false`, or a `WP_Error` object. `true` means permission is granted, `false` means the user simply lacks permission, and a `WP_Error` return value typically indicates a failure in the permission check process (such as an internal error or misconfiguration). You must use `is_wp_error()` to handle errors properly and distinguish between permission denial and actual errors:
|
||
|
||
```php
|
||
$ability = wp_get_ability( 'my-plugin/update-option' );
|
||
if ( $ability ) {
|
||
$input = array(
|
||
'option_name' => 'blogname',
|
||
'option_value' => 'New Site Name',
|
||
);
|
||
|
||
// Check permission before execution - always use is_wp_error() first
|
||
$has_permissions = $ability->check_permissions( $input );
|
||
if ( true === $has_permissions ) {
|
||
// Permissions granted – safe to execute.
|
||
echo 'You have permissions to execute this ability.';
|
||
} else {
|
||
// Don't leak permission errors to unauthenticated users.
|
||
if ( is_wp_error( $has_permissions ) ) {
|
||
error_log( 'Permissions check failed: ' . $has_permissions->get_error_message() );
|
||
}
|
||
|
||
echo 'You do not have permissions to execute this ability.';
|
||
}
|
||
}
|
||
```
|
||
|
||
## Inspecting Ability Properties
|
||
|
||
The `WP_Ability` class provides several getter methods to inspect ability properties:
|
||
|
||
```php
|
||
$ability = wp_get_ability( 'my-plugin/get-site-info' );
|
||
if ( $ability ) {
|
||
// Basic properties
|
||
echo 'Name: ' . $ability->get_name() . "\n";
|
||
echo 'Label: ' . $ability->get_label() . "\n";
|
||
echo 'Description: ' . $ability->get_description() . "\n";
|
||
|
||
// Schema information
|
||
$input_schema = $ability->get_input_schema();
|
||
$output_schema = $ability->get_output_schema();
|
||
|
||
echo 'Input Schema: ' . json_encode( $input_schema, JSON_PRETTY_PRINT ) . "\n";
|
||
echo 'Output Schema: ' . json_encode( $output_schema, JSON_PRETTY_PRINT ) . "\n";
|
||
|
||
// Metadata
|
||
$meta = $ability->get_meta();
|
||
if ( ! empty( $meta ) ) {
|
||
echo 'Metadata: ' . json_encode( $meta, JSON_PRETTY_PRINT ) . "\n";
|
||
}
|
||
}
|
||
```
|
||
|
||
## Error Handling Patterns
|
||
|
||
The Abilities API uses several error handling mechanisms:
|
||
|
||
```php
|
||
$ability = wp_get_ability( 'my-plugin/some-ability' );
|
||
|
||
if ( ! $ability ) {
|
||
// Ability not registered
|
||
echo 'Ability not found';
|
||
return;
|
||
}
|
||
|
||
$result = $ability->execute( $input );
|
||
|
||
// Check for WP_Error (validation, permission, or callback errors)
|
||
if ( is_wp_error( $result ) ) {
|
||
echo 'WP_Error: ' . $result->get_error_message();
|
||
return;
|
||
}
|
||
|
||
// Check for null result (permission denied, invalid callback, or validation failure)
|
||
if ( is_null( $result ) ) {
|
||
echo 'Execution returned null - check permissions and callback validity';
|
||
return;
|
||
}
|
||
|
||
// Success - use the result
|
||
// Process $result based on the ability's output schema
|
||
```
|