diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..7710295a --- /dev/null +++ b/.gitattributes @@ -0,0 +1,30 @@ +# Automatically normalize line endings. +* text=auto + +# Files and directories to exclude from the generated archive (export-ignore). +# These will be omitted from GitHub/Packagist ZIP archives to keep packages small. + +# Tests and test fixtures +/tests/ export-ignore + +# PHP unit / static analysis configs. +/phpcs.xml.dist export-ignore +/phpstan.neon.dist export-ignore +/phpunit.xml.dist export-ignore + +# Continuous Integration configs. +/.github/ export-ignore + +# Node and build artifacts. +package.json export-ignore +package-lock.json export-ignore +/composer.lock export-ignore + +# Don't include the dotfiles for distribution. +/.* export-ignore + +# Mark docs as documentation for GitHub Linguist. +/docs/ linguist-documentation export-ignore +/CONTRIBUTING.md linguist-documentation export-ignore +/LICENSE.md linguist-documentation +/README.md linguist-documentation diff --git a/.wordpress-org/.gitkeep b/.wordpress-org/.gitkeep deleted file mode 100644 index e69de29b..00000000 diff --git a/abilities-api.php b/abilities-api.php index 678fb20d..3a9014d6 100644 --- a/abilities-api.php +++ b/abilities-api.php @@ -26,27 +26,8 @@ */ define( 'WP_ABILITIES_API_DIR', plugin_dir_path( __FILE__ ) ); -/** - * Version of the plugin. - */ -define( 'WP_ABILITIES_API_VERSION', '0.1.0' ); +require_once WP_ABILITIES_API_DIR . 'includes/bootstrap.php'; -/** - * First the WP_Ability class that users can extend. - */ -require_once WP_ABILITIES_API_DIR . 'includes/abilities-api/class-wp-ability.php'; - -/** - * Then the WP_Abilities_Registry class that manages the abilities. - */ -require_once WP_ABILITIES_API_DIR . 'includes/abilities-api/class-wp-abilities-registry.php'; - -/** - * Then the public access functions that users can use to interact with the abilities. - */ -require_once WP_ABILITIES_API_DIR . 'includes/abilities-api.php'; - -/** - * Initialize REST API controllers. - */ -require_once WP_ABILITIES_API_DIR . 'includes/rest-api/class-wp-rest-abilities-init.php'; +if ( function_exists( 'add_action' ) ) { + add_action( 'rest_api_init', array( 'WP_REST_Abilities_Init', 'register_routes' ) ); +} diff --git a/composer.json b/composer.json index 72c9750d..a63d8e05 100644 --- a/composer.json +++ b/composer.json @@ -1,33 +1,39 @@ { "name": "wordpress/abilities-api", - "description": "AI Abilities for WordPress", + "description": "AI Abilities for WordPress.", "license": "GPL-2.0-or-later", "type": "wordpress-plugin", - "version": "0.1.0", "keywords": [ "ai", + "api", "llm", "abilities", - "abilities-api", "wordpress" ], - "homepage": "https://github.com/WordPress/abilities-api/issues", + "authors": [ + { + "name": "WordPress AI Team", + "homepage": "https://make.wordpress.org/ai/" + } + ], + "homepage": "https://github.com/WordPress/abilities-api", "support": { - "issues": "https://github.com/WordPress/abilities-api/issues" + "issues": "https://github.com/WordPress/abilities-api/issues", + "source": "https://github.com/WordPress/abilities-api" }, + "minimum-stability": "dev", + "prefer-stable": true, "config": { - "sort-packages": true, - "platform": { - "php": "7.4" - }, "allow-plugins": { "dealerdirect/phpcodesniffer-composer-installer": true, "phpstan/extension-installer": true, "composer/installers": true - } + }, + "platform": { + "php": "7.4" + }, + "sort-packages": true }, - "minimum-stability": "dev", - "prefer-stable": true, "repositories": [ { "type": "composer", diff --git a/composer.lock b/composer.lock index 3c400ed5..1f59a291 100644 --- a/composer.lock +++ b/composer.lock @@ -501,16 +501,16 @@ }, { "name": "guzzlehttp/promises", - "version": "2.2.0", + "version": "2.3.0", "source": { "type": "git", "url": "https://github.com/guzzle/promises.git", - "reference": "7c69f28996b0a6920945dd20b3857e499d9ca96c" + "reference": "481557b130ef3790cf82b713667b43030dc9c957" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/guzzle/promises/zipball/7c69f28996b0a6920945dd20b3857e499d9ca96c", - "reference": "7c69f28996b0a6920945dd20b3857e499d9ca96c", + "url": "https://api.github.com/repos/guzzle/promises/zipball/481557b130ef3790cf82b713667b43030dc9c957", + "reference": "481557b130ef3790cf82b713667b43030dc9c957", "shasum": "" }, "require": { @@ -518,7 +518,7 @@ }, "require-dev": { "bamarni/composer-bin-plugin": "^1.8.2", - "phpunit/phpunit": "^8.5.39 || ^9.6.20" + "phpunit/phpunit": "^8.5.44 || ^9.6.25" }, "type": "library", "extra": { @@ -564,7 +564,7 @@ ], "support": { "issues": "https://github.com/guzzle/promises/issues", - "source": "https://github.com/guzzle/promises/tree/2.2.0" + "source": "https://github.com/guzzle/promises/tree/2.3.0" }, "funding": [ { @@ -580,7 +580,7 @@ "type": "tidelift" } ], - "time": "2025-03-27T13:27:01+00:00" + "time": "2025-08-22T14:34:08+00:00" }, { "name": "guzzlehttp/psr7", @@ -760,16 +760,16 @@ }, { "name": "nikic/php-parser", - "version": "v5.6.0", + "version": "v5.6.1", "source": { "type": "git", "url": "https://github.com/nikic/PHP-Parser.git", - "reference": "221b0d0fdf1369c71047ad1d18bb5880017bbc56" + "reference": "f103601b29efebd7ff4a1ca7b3eeea9e3336a2a2" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/221b0d0fdf1369c71047ad1d18bb5880017bbc56", - "reference": "221b0d0fdf1369c71047ad1d18bb5880017bbc56", + "url": "https://api.github.com/repos/nikic/PHP-Parser/zipball/f103601b29efebd7ff4a1ca7b3eeea9e3336a2a2", + "reference": "f103601b29efebd7ff4a1ca7b3eeea9e3336a2a2", "shasum": "" }, "require": { @@ -788,7 +788,7 @@ "type": "library", "extra": { "branch-alias": { - "dev-master": "5.0-dev" + "dev-master": "5.x-dev" } }, "autoload": { @@ -812,9 +812,9 @@ ], "support": { "issues": "https://github.com/nikic/PHP-Parser/issues", - "source": "https://github.com/nikic/PHP-Parser/tree/v5.6.0" + "source": "https://github.com/nikic/PHP-Parser/tree/v5.6.1" }, - "time": "2025-07-27T20:03:57+00:00" + "time": "2025-08-13T20:13:15+00:00" }, { "name": "phar-io/manifest", @@ -1075,12 +1075,12 @@ "source": { "type": "git", "url": "https://github.com/PHPCompatibility/PHPCompatibility.git", - "reference": "a32035ecd801d827b85c3d8fdb281a43660115b7" + "reference": "6e10469b0f3827862b37df2ac2b7ec4580ce888f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/PHPCompatibility/PHPCompatibility/zipball/a32035ecd801d827b85c3d8fdb281a43660115b7", - "reference": "a32035ecd801d827b85c3d8fdb281a43660115b7", + "url": "https://api.github.com/repos/PHPCompatibility/PHPCompatibility/zipball/6e10469b0f3827862b37df2ac2b7ec4580ce888f", + "reference": "6e10469b0f3827862b37df2ac2b7ec4580ce888f", "shasum": "" }, "require": { @@ -1161,7 +1161,7 @@ "type": "thanks_dev" } ], - "time": "2025-08-06T19:48:56+00:00" + "time": "2025-08-20T03:33:09+00:00" }, { "name": "phpcompatibility/phpcompatibility-paragonie", @@ -2059,16 +2059,16 @@ }, { "name": "phpunit/phpunit", - "version": "9.6.24", + "version": "9.6.25", "source": { "type": "git", "url": "https://github.com/sebastianbergmann/phpunit.git", - "reference": "ea49afa29aeea25ea7bf9de9fdd7cab163cc0701" + "reference": "049c011e01be805202d8eebedef49f769a8ec7b7" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/ea49afa29aeea25ea7bf9de9fdd7cab163cc0701", - "reference": "ea49afa29aeea25ea7bf9de9fdd7cab163cc0701", + "url": "https://api.github.com/repos/sebastianbergmann/phpunit/zipball/049c011e01be805202d8eebedef49f769a8ec7b7", + "reference": "049c011e01be805202d8eebedef49f769a8ec7b7", "shasum": "" }, "require": { @@ -2142,7 +2142,7 @@ "support": { "issues": "https://github.com/sebastianbergmann/phpunit/issues", "security": "https://github.com/sebastianbergmann/phpunit/security/policy", - "source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.24" + "source": "https://github.com/sebastianbergmann/phpunit/tree/9.6.25" }, "funding": [ { @@ -2166,7 +2166,7 @@ "type": "tidelift" } ], - "time": "2025-08-10T08:32:42+00:00" + "time": "2025-08-20T14:38:31+00:00" }, { "name": "psr/container", @@ -3989,7 +3989,7 @@ }, { "name": "symfony/polyfill-ctype", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-ctype.git", @@ -4048,7 +4048,7 @@ "portable" ], "support": { - "source": "https://github.com/symfony/polyfill-ctype/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-ctype/tree/v1.33.0" }, "funding": [ { @@ -4059,6 +4059,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" @@ -4068,16 +4072,16 @@ }, { "name": "symfony/polyfill-intl-grapheme", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-intl-grapheme.git", - "reference": "b9123926e3b7bc2f98c02ad54f6a4b02b91a8abe" + "reference": "380872130d3a5dd3ace2f4010d95125fde5d5c70" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/b9123926e3b7bc2f98c02ad54f6a4b02b91a8abe", - "reference": "b9123926e3b7bc2f98c02ad54f6a4b02b91a8abe", + "url": "https://api.github.com/repos/symfony/polyfill-intl-grapheme/zipball/380872130d3a5dd3ace2f4010d95125fde5d5c70", + "reference": "380872130d3a5dd3ace2f4010d95125fde5d5c70", "shasum": "" }, "require": { @@ -4126,7 +4130,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-intl-grapheme/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-intl-grapheme/tree/v1.33.0" }, "funding": [ { @@ -4137,16 +4141,20 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" } ], - "time": "2024-09-09T11:45:10+00:00" + "time": "2025-06-27T09:58:17+00:00" }, { "name": "symfony/polyfill-intl-normalizer", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-intl-normalizer.git", @@ -4207,7 +4215,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-intl-normalizer/tree/v1.33.0" }, "funding": [ { @@ -4218,6 +4226,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" @@ -4227,7 +4239,7 @@ }, { "name": "symfony/polyfill-mbstring", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-mbstring.git", @@ -4288,7 +4300,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-mbstring/tree/v1.33.0" }, "funding": [ { @@ -4299,6 +4311,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" @@ -4308,7 +4324,7 @@ }, { "name": "symfony/polyfill-php73", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php73.git", @@ -4364,7 +4380,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php73/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-php73/tree/v1.33.0" }, "funding": [ { @@ -4375,6 +4391,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" @@ -4384,7 +4404,7 @@ }, { "name": "symfony/polyfill-php80", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php80.git", @@ -4444,7 +4464,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php80/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-php80/tree/v1.33.0" }, "funding": [ { @@ -4455,6 +4475,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" @@ -4464,7 +4488,7 @@ }, { "name": "symfony/polyfill-php81", - "version": "v1.32.0", + "version": "v1.33.0", "source": { "type": "git", "url": "https://github.com/symfony/polyfill-php81.git", @@ -4520,7 +4544,7 @@ "shim" ], "support": { - "source": "https://github.com/symfony/polyfill-php81/tree/v1.32.0" + "source": "https://github.com/symfony/polyfill-php81/tree/v1.33.0" }, "funding": [ { @@ -4531,6 +4555,10 @@ "url": "https://github.com/fabpot", "type": "github" }, + { + "url": "https://github.com/nicolas-grekas", + "type": "github" + }, { "url": "https://tidelift.com/funding/github/packagist/symfony/symfony", "type": "tidelift" diff --git a/docs/2.getting-started.md b/docs/2.getting-started.md index c8e3c291..add03a0d 100644 --- a/docs/2.getting-started.md +++ b/docs/2.getting-started.md @@ -1,12 +1,153 @@ # 2. Getting Started -## Installation Options +## Installation -Currently, the Abilities API is available as a WordPress plugin. You can install it by cloning the repository into your `wp-content/plugins` directory. +Until the Abilities API is merged into WordPress core, it must be installed before it can be used. + +### As a plugin + +The best and easiest way to try and use the Abilities API is to install it as a plugin by downloading the latest release from the [GitHub Releases page](https://github.com/WordPress/abilities-api/releases/latest). + +#### With WP-CLI + +```bash +wp plugin install https://github.com/WordPress/abilities-api/releases/latest/download/abilities-api.zip +``` + +#### With WP-Env + +```jsonc +// .wp-env.json +{ + "$schema": "https://schemas.wp.org/trunk/wp-env.json", + // ... other config ... + "plugins": [ + "WordPress/abilities-api", + // ... other plugins ... + ], + // ... more config ... +} +``` + +#### With Composer + +Until the plugin is available on Packagist, you will need to add the repository to your `composer.json` file. + +```jsonc +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/WordPress/abilities-api.git" + } + // ... other repositories. + ], + "extra": { + "installer-paths": { + // This should match your WordPress+Composer setup. + "wp-content/plugins/{$name}/": [ + "type:wordpress-plugin" + ] + // .. other paths. + } + } + // ... rest of your composer.json. +} +``` + +Then, require the package in your project: + +```bash +composer require wordpress/abilities-api +``` + +### As a dependency + +Plugin authors and developers may wish to rely on the Abilities API as a dependency in their own projects, before it is merged into core. You can do that in one of the following ways. + +#### As a Plugin Dependency (Recommended) + +The best way to ensure the Abilities API is available for your plugins is to include it as one of your `Requires Plugins` in your [Plugin header](https://developer.wordpress.org/plugins/plugin-basics/header-requirements/). For example: + +```diff +# my-plugin.php +/* + * + * Plugin Name: My Plugin + * Plugin URI: https://example.com/plugins/the-basics/ + * Description: Handle the basics with this plugin. + * {all the other plugin header fields...} + * Requires Plugins: abilities-api + */ +``` + +While this is enough to ensure the Abilities API is loaded before your plugin, if you need to ensure specific version requirements or provide users guidance on installing the plugin, you can use the methods described [later on](#checking-availability-with-code) + +#### As a Composer dependency + +Until the plugin is available on Packagist, you will need to add the repository to your `composer.json` file. + +```jsonc +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/WordPress/abilities-api.git" + } + // ... other repositories. + ], + // ... rest of your composer.json. +} +``` + +Then, require the package in your project: ```bash -cd wp-content/plugins -git clone https://github.com/WordPress/abilities-api +composer require wordpress/abilities-api +``` + +Once installed, you can then choose whether to load the _entire_ Abilities API plugin (including the REST API endpoints), or just the core library. + +```php +if ( ! class_exists( 'WP_Ability' ) ) { + // Require the entire plugin. + require_once __DIR__ . '/path/to/vendor/wordpress/abilities-api/abilities-api.php'; + + // OR just the core API without the WordPress integration parts. + require_once __DIR__ . '/path/to/vendor/wordpress/abilities-api/includes/bootstrap.php'; +} +``` + +### Checking availability with code + +To ensure the Abilities API is loaded in your plugin: + +```php +if ( ! class_exists( 'WP_Ability' ) ) { + // E.g. add an admin notice about the missing dependency. + add_action( 'admin_notices', static function() { + wp_admin_notice( + esc_html__( 'This plugin requires the Abilities API to use. Please install and activate it.', 'my-plugin' ), + 'error' + ); + } ); + return; +} +``` + +You can also check for specific versions of the Abilities API using the `WP_ABILITIES_API_VERSION` constant: + +```php +if ( ! defined( 'WP_ABILITIES_API_VERSION' ) || version_compare( WP_ABILITIES_API_VERSION, '0.1.0', '<' ) ) { + // E.g. add an admin notice about the required version. + add_action( 'admin_notices', static function() { + wp_admin_notice( + esc_html__( 'This plugin requires Abilities API version 0.1.0 or higher. Please update the plugin dependency.', 'my-plugin' ), + 'error' + ); + } ); + return; +} ``` ## Basic Usage Example diff --git a/includes/bootstrap.php b/includes/bootstrap.php new file mode 100644 index 00000000..b6b3459f --- /dev/null +++ b/includes/bootstrap.php @@ -0,0 +1,41 @@ +register_routes(); } } - -add_action( 'rest_api_init', array( 'WP_REST_Abilities_Init', 'register_routes' ) );