Skip to content

YahnisElsts/ajax-wrapper

Repository files navigation

AJAX Action Wrapper

This helper library makes it easier to handle AJAX requests in WordPress plugins. Mainly for personal use.

Example

Define action:

$exampleAction = ajaw_v1_CreateAction('ws_do_something')
	->handler(array($this, 'myAjaxCallback'))
	->requiredCap('manage_options')
	->method('post')
	->requiredParam('foo')
	->optionalParam('bar', 'default value')
	->register();

Call from JavaScript:

AjawV1.getAction('ws_do_something').post(
	{
		'foo': '...'
	},
	function(response) {
		console.log(response);
	}
);

Features

  • Automate common, boring stuff.
    • Automatically pass the admin-ajax.php URL and nonce to JS.
    • Define required parameters.
       $builder->requiredParam('foo', 'int')
    • Define optional parameters with default values.
       $builder->optionalParam('meaningOfLife', 42, 'int')
    • Automatically remove "magic quotes" that WordPress adds to $_GET, $_POST and $_REQUEST.
    • Encode return values as JSON.
  • Security should be the default.
    • Generate and verify nonces. Nonce verification is on by default, but can be disabled.
       $builder->withoutNonce()
    • Check capabilities.
       $builder->requiredCap('manage_options');
    • Verify that all required parameters are set.
    • Validate parameter values.
       $builder->optionalParam('things', 1, 'int', function($value) {
       	if ($value > 10) {
       		return new WP_Error(
       			'excessive_things',
       			'Too many things!',
       			400 //HTTP status code.
       		);
       	}
       })
    • Set the required HTTP method.
       $builder->method('post')
  • Resilience.
    • Lenient response parsing to work around bugs in other plugins. For example, deal with extraneous whitespace and PHP notices in AJAX responses.
    • Multiple versions of the library can coexist on the same site.

Why not use the REST API instead?

Backwards compatibility. In theory, this library should be compatible with WP 4.1+.

About

AJAX action wrapper for WordPress

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published