x-wp / ajax-router
Simplifies the use of WordPress AJAX by providing NestJS inspired Controller design.
Requires
- php: >= 8.1
- automattic/jetpack-constants: ^2.0
- oblak/wp-polyfills: ^1.0
- sunrise/http-message: ^3
- sunrise/http-router: ^2.16
- x-wp/hook-invoker: ^1.0@alpha
Requires (Dev)
Suggests
- automattic/jetpack-autoloader: Allow for better interoperability with other plugins that use this package.
This package is auto-updated.
Last update: 2024-10-30 20:43:54 UTC
README
WordPress AJAX Router
PSR-7 / PSR-15 compatible AJAX router for WordPress.
Inspired by NestJS and Express - this library provides a simple way to handle AJAX requests in WordPress.
QuickStart
Install the library
composer require x-wp/ajax-server
Define a controller
<?php use Sunrise\Http\Router\Exception\PageNotFoundException; use XWP\Decorator\Core\Controller; use XWP\Decorator\Core\Use_Guards; use XWP\Decorator\HTTP\Argument\Body; use XWP\Decorator\HTTP\Get; use XWP\Decorator\HTTP\Param; use XWP\Decorator\HTTP\Post; use XWP\Guard\Capability_Guard; use XWP\Guard\Nonce_Guard; use XWP\Response\JSON; #[Use_Guards( new Nonce_Guard() )] #[Controller( 'my-endpoint' )] class My_Controller { #[Get( 'get-post/{id}', JSON::class )] public function get_post( #[Param( 'id' )] int $id, ): \WP_Post { return \get_post( $id ); } #[Use_Guards( new Capability_Guard( 'manage_options' ) )] #[Post( 'modify-post/{id}', JSON::class )] public function modify_post( #[Param( 'id' )] int $id, #[Body] array $data ): int { $post = \get_post( $id ); if ( ! $post ) { throw new PageNotFoundException( 'Invalid post', 404 ); } return wp_update_post( array_merge( array( 'ID' => $id ), $data, ), ); } }
Register a controller
xwp_register_routes( My_Controller::class );
This will expose the following endpoints:
GET /wp-ajax/my-endpoint/get-post/{id}
POST /wp-ajax/my-endpoint/modify-post/{id}
Ajax base URL is /wp-ajax
by default, and can be changed in permalink settings.
Getting Endpoint URLs
In PHP
xwp_ajax_url( 'some', 'endpoint' ); // https://example.com/wp-ajax/some/endpoint xwp_ajax_url( 'some/endpoint' ); // https://example.com/wp-ajax/some/endpoint
In JavaScript
Library adds a global object xwp
attached to window
object. Both in the admin and on the frontend.
You can disable this by using xwp_ajax_vars
filter, or calling the xwp_disable_ajax_js_vars
declare type XWP = { /** * URL for the wp-ajax endpoint */ wpAjaxUrl: string; /** * URL for the admin-ajax endpoint */ adminAjaxUrl: string; /** * Get URL for the wp-ajax endpoint * * @param parts - parts of the URL */ forWpAjax: (...parts: string[]): string; /** * Get URL for the admin-ajax endpoint * * @param action - action name * @param nonce - nonce value (optional) * @param data - data to be sent */ forAdminAjax: (action:string , nonce?: string, data: Record<string, any>|FormData): string; }
const baseUrl = window.xwp.wpAjaxUrl; // https://example.com/wp-ajax const endUrl = window.xwp.adminAjaxUrl; // https://example.com/wp-admin/admin-ajax.php const ajaxEp = window.xwp.forWpAjax( 'some', 'endpoint' ); // https://example.com/wp-ajax/some/endpoint const adminEp = window.xwp.forAdminAjax( 'some_action' ); // https://example.com/wp-admin/admin-ajax.php?action=some_action
FAQ
1. Did you just reinvent the wheel?
Yes, we did. We basically took the wheels from NestJS and Express and put it on a WordPress car.
2. Why?
Read this.
3. Can I use this in my project?
Yes, you can. But remember, this is a work in progress and we are still figuring out the best way to do things. API is subject to change.
4. Can I contribute?
Sure 💪💪💪.
If you have an idea, a suggestion, or a bug report - feel free to open an issue.
5. How does it work?
Read this.