PHPackages                             philipnewcomer/wp-ajax-helper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. philipnewcomer/wp-ajax-helper

ActiveLibrary[Utility & Helpers](/categories/utility)

philipnewcomer/wp-ajax-helper
=============================

A library to simplify AJAX requests in WordPress plugins and themes.

1.0.1(9y ago)64.3k3GPL-2.0+PHPPHP >=5.3

Since Jan 1Pushed 9y ago1 watchersCompare

[ Source](https://github.com/philipnewcomer/wp-ajax-helper)[ Packagist](https://packagist.org/packages/philipnewcomer/wp-ajax-helper)[ Docs](https://github.com/philipnewcomer/wp-ajax-helper)[ RSS](/packages/philipnewcomer-wp-ajax-helper/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (4)Used By (0)

WP Ajax Helper
==============

[](#wp-ajax-helper)

*A library to simplify AJAX requests in WordPress plugins and themes.*

What is This?
-------------

[](#what-is-this)

WP Ajax Helper exists to simplify the process of performing Ajax requests in WordPress.

With a simple, easy-to-understand syntax, it handles nonces and validation automatically, freeing you up to worry about more important things.

It also interprets the Ajax payload, passing it to your callback function as an array or string as appropriate, as well as interpreting the callback's response and returning it to the browser either as a string or as JSON.

With an simple validation component, you can easily restrict the user permissions under which the callback function will run.

Finally, it provides a JavaScript front-end component which interfaces with the backend library.

Getting Started
---------------

[](#getting-started)

### Backend

[](#backend)

Include the package in your project using Composer, or simply include wp-ajax-helper.php from somewhere in your project.

The most basic usage is to call `wp_ajax_helper()` with a handle and a callback function, like this:

`wp_ajax_helper()->handle( 'my-handle' )->with_callback( 'my_callback' );`

The handle is the unique identifier for this instance, and the callback function is the function which should handle the Ajax request.

### Frontend

[](#frontend)

Whenever a handle is registered, the JavaScript function `wpAjaxHelperRequest()` will be available to use in your scripts. Pass in the handle of the callback you want to call, and include an optional payload as the second parameter, which will be passed into your callback function.

`wpAjaxHelperRequest( 'my-handle', 'payload' );`

The payload can be either a string or an object. If an object is sent, it will be converted to a PHP array when passed to your callback function.

You'll probably want to do something with the response to your Ajax request; that is detailed below.

Advanced Usage
--------------

[](#advanced-usage)

### Backend: Callbacks

[](#backend-callbacks)

The callback can be a function name, a class method, or a closure.

Here are several examples illustrating various ways a callback can be registered:

```
wp_ajax_helper->handle( 'my-handle' )->with_callback( 'function_name' );

```

```
$args = array( // Some arguments here. );
wp_ajax_helper->handle( 'my-handle' )->with_callback( 'function_name', $args );

```

```
wp_ajax_helper->handle( 'my-handle' )->with_callback( array( $class, 'method_name' ) );

```

Two parameters will be provided to the callback function when it is executed: `$ajax_payload` and `$args`. The first parameter is the Ajax payload from the request. The second is an array of values which were (optionally) specified as the second parameter when registering the handle.

```
function my_ajax_callback( $ajax_payload, $args ) {

    // Do something with the ajax payload.
    do_something_with( $ajax_payload['my-value-1'] );
    do_something_with( $ajax_payload['my-value-2'] );

    // Return an array, which will be converted to JSON before being sent back to the browser.
    return array(
        'key1' => 'value1',
        'key2' => 'value2',
    );
}

```

If the callback function returns a string, the Ajax response will be a string. If the callback returns an array, the Ajax response will be that array, converted to a JSON object. If the callback function returns anything else, i.e. null, a WP\_Error object, or throws an exception, the response will be an error.

### Backend: Validation

[](#backend-validation)

To specify validations which need to pass before the callback function can run, pass in an array of validations to the `with_validation()` method, with the values to test in the following format.

```
$validations = array(
    'validation_name' => 'value to test'
);
wp_ajax_helper->handle( 'my-handle' )->with_validation( $validations );

```

The following validations are available:

- logged\_in (boolean)
- user\_can (capability name)
- user\_is (role name)

Example usage:

```
$validations = array(
    'logged_in' => true,
    'user_can'  => 'manage_options',
    'user_is'   => 'administrator',
);
wp_ajax_helper->handle( 'my-handle' )->with_validation( $validations );

```

All validations are optional.

### Backend: Filters

[](#backend-filters)

The following filters are available, which will allow you to filter the Ajax payload before being sent to a callback function, as well as filtering the output of the callback function before being sent back to the browser.

- Filter: `WP_Ajax_Helper\ajax_payload`**Parameters:**\* $payload: The Ajax payload. \* $handle: The handle name.
- Filter: `WP_Ajax_Helper\callback_response`**Parameters:**\* $response: The callback response. \* $handle: The handle name. \* $callback\_args: The arguments which were passed to the callback function. \* $ajax\_payload: The Ajax payload which was passed to the callback function.

### Frontend: Handling the Response

[](#frontend-handling-the-response)

The `wpAjaxHelperRequest` function will return a jQuery $.POST response, which you can utilize just like a normal $.POST request to handle the response:

```
wpAjaxHelperRequest( "my-handle", payload )
    .success( function( response ) {
        console.log( "Woohoo!" );
        // 'response' will be the response from the handle's callback function, as either a string or JSON.
        console.log( response );
    })
    .error( function( response ) {
        console.log( "Uh, oh!" );
        console.log( response.statusText );
    });

```

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity27

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~541 days

Total

2

Last Release

3294d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1446874?v=4)[Philip Newcomer](/maintainers/philipnewcomer)[@philipnewcomer](https://github.com/philipnewcomer)

---

Top Contributors

[![philipnewcomer](https://avatars.githubusercontent.com/u/1446874?v=4)](https://github.com/philipnewcomer "philipnewcomer (2 commits)")

---

Tags

wordpressajax

### Embed Badge

![Health badge](/badges/philipnewcomer-wp-ajax-helper/health.svg)

```
[![Health](https://phpackages.com/badges/philipnewcomer-wp-ajax-helper/health.svg)](https://phpackages.com/packages/philipnewcomer-wp-ajax-helper)
```

###  Alternatives

[aristath/kirki

Extending the WordPress customizer

1.3k73.1k4](/packages/aristath-kirki)[afragen/git-updater

A plugin to automatically update GitHub, Bitbucket, GitLab, or Gitea hosted plugins, themes, and language packs.

3.3k1.7k](/packages/afragen-git-updater)[tacowordpress/tacowordpress

WordPress custom post types that feel like CRUD models

232.2k](/packages/tacowordpress-tacowordpress)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)