Download the PHP package zotenme/hyperf-ajax without Composer

Hyperf Ajax

[]() []()

Hyperf Ajax is a Hyperf backend package compatible with the Larajax browser protocol. It lets a normal Hyperf page controller answer HTML-driven AJAX handlers such as data-request="onSave" without creating a separate JSON API route for every UI interaction.

This repository currently contains the first MVP implementation:

• Hyperf package skeleton with ConfigProvider;
• Larajax-compatible __ajax response envelope;
• DOM patch, partial, redirect, reload, flash, browser event and asset operations;
• explicit controller trait and base controller for onXxx handler dispatch;
• component container with component::onHandler support;
• validation/error mapper;
• publishable frontend assets copied from Larajax dist.

Installation

For local development:

Publish the frontend assets in a Hyperf application using Hyperf's vendor publish flow. The package exposes resources/dist as public/vendor/hyperfajax.

Frontend

Use either the existing npm package:

Or serve the published bundle:

framework-bundle.min.js starts the framework automatically. Do not call window.jax.start() with this bundle.

The published bundles are redistributed from Larajax 2.2.3. See Third-Party Notices for the upstream copyright and MIT license notice.

Controller Usage

The recommended low-friction entry point is HyperfAjaxController with ajaxPage(). The method renders a normal page for regular requests and dispatches onXxx handlers for AJAX requests.

ajaxPage() is the intentional public integration boundary. Call it explicitly from each page action that supports AJAX. The package does not install automatic middleware, attributes or AOP interception: Hyperf controllers may be long-lived, and keeping the concrete controller instance and request lifecycle explicit avoids hidden coroutine state. The render callback is lazy and is never called for an AJAX request.

Route:

View:

Minimal Browser Test

This example returns a tiny HTML page and a working onPing handler. It is the quickest way to verify a local path install inside a real Hyperf application.

See the copyable source in examples/HyperfAjaxTestController.php.

Route:

Request Input

Controllers using InteractsWithAjax do not need a $this->request property. The trait exposes request data from the active AJAX request:

Available helpers:

• ajaxAll() returns query and parsed body data, with body values taking priority.
• ajaxPost() returns parsed body data.
• ajaxPost('field', 'default') returns one parsed body value.
• ajaxInput('field', 'default') returns one merged query/body value.

AJAX handler names follow one backend protocol grammar. Controller handlers use onEvent; component handlers use ComponentAlias::onEvent. Event must start with an uppercase ASCII letter, and names may otherwise contain ASCII letters, digits and underscores. Invalid handler names return an AJAX HTTP 400 response.

Handler signatures

Values passed in the ajaxPage(..., parameters: [...]) array may be positional or keyed by parameter name. Named values take priority over positional values and container injection. A single class or interface type can be resolved from the container; default values, nullable parameters and variadic parameters are supported. Pass a named variadic value as an array.

Union, intersection and enum parameters are supported when an explicit value of the correct PHP type is supplied. They are not guessed from the container or coerced from strings. A missing required parameter produces a diagnostic InvalidArgumentException instead of receiving an implicit null.

Request body and query values are deliberately not bound to method parameters. Read them through ajaxPost(), ajaxInput() or ajaxAll() so route/action parameters cannot silently conflict with submitted input.

To customize handler invocation, bind the typed invoker contract in config/autoload/dependencies.php:

The implementation receives the resolved controller/component callable and the explicit action parameters:

This contract replaces the former undocumented makeCallForAjax() method-name convention.

Validation

For inline, October-style validation, throw Hyperf Ajax's own validation exception. It accepts either a field error array or a validator/message-bag-like object.

Add data-request-validate to the form and place data-validate-for="field" where a field-level error should appear:

You can also throw field errors directly:

Components

HyperfAjaxController already implements AjaxControllerInterface, so a controller using components only needs to declare its component list:

Component aliases must be unique within one AJAX request. Duplicate aliases are rejected during registration instead of silently replacing an earlier component.

When applying InteractsWithAjax directly, the class must implement AjaxControllerInterface and provide the container accessor required by the trait:

Component:

HTML:

Flash messages

Flash messages are explicit response operations and do not depend on a Hyperf session integration:

Enable flash handling for the frontend request with data-request-flash (or the equivalent JavaScript flash: true option):

For Larajax 2.2.3 compatibility the frontend sends X-AJAX-FLASH, but the backend does not interpret that header or capture messages from session storage. It only returns flash operations explicitly added through AjaxResponse::flash(). Applications that need session-backed flash capture can implement it in their own handler or response adapter without making a session package mandatory.

Partials

The frontend distinguishes the current partial from the partials requested for rendering. A request originating inside data-ajax-partial sends its name in X-AJAX-PARTIAL. The backend exposes that context as $this->getAjaxRequest()?->partial, including to PartialRendererInterface. It does not render the current partial automatically.

Use _self when the originating partial should be refreshed:

As in Larajax 2.2.3, the frontend resolves _self to profile/card and includes that resolved name in X-AJAX-PARTIALS. The backend renders only this resolved list, keeping X-AJAX-PARTIAL as request context.

You can always return ready HTML without a renderer:

For automatic rendering of names sent in X-AJAX-PARTIALS, bind a PartialRendererInterface implementation in config/autoload/dependencies.php:

The renderer is framework-neutral and receives the controller, current AJAX request and explicit template data:

Set data during the AJAX handler. It is stored only in the current coroutine execution context:

Using hyperf/view

Install and configure hyperf/view and your chosen view engine, then implement the same contract with Hyperf\View\RenderInterface::getContents():

Complete examples for direct strings, plain PHP templates and hyperf/view are available in examples/PartialRendering.

A larger Blade example with a product catalog, category/minimum-price filters and “Show more” AJAX pagination is available in examples/ProductCatalog.

Tests

Run the PHPUnit suite:

The suite checks framework-neutral behavior. Full Hyperf integration tests remain in the local, ignored hyperf-app smoke environment.