APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

Ajax

Annotation-driven asynchronous communication with minimal application code, context-aware authentication, and an integrated JavaScript client.

APPNETOS exposes individual controller methods through a PHP attribute. The AJAX runtime resolves the requested controller and method, checks the security token and authentication policy, creates only the requested controller instance, and sends the response. There is no need to initialize every application or build a separate AJAX endpoint for each interaction.

How it works

APPNETOS AJAX request lifecycle, from JavaScript to token and annotation checks, controller execution, and response
  1. appnetos.js submits a POST to the current page with the requested class and method.
  2. The request includes X-Appnetos-Ajax: 1 and a session-bound AJAX token.
  3. The AJAX runtime validates the request, token, target method, and its context-specific #[Ajax] annotation.
  4. The runtime checks whether authentication is required and instantiates the selected controller via Registry::getNew().
  5. The method executes and the response is returned as JSON, HTML/text, or an empty 204 response.

Only the requested controller is instantiated by the AJAX dispatcher. Its own dependencies may still be initialized as required; this does not mean that all applications are loaded.

Context-specific authentication

The user argument controls whether an authenticated user is required. Its default is deliberately different between the public app and administrative admin contexts.

Context Annotation Authentication
app #[Ajax] Not required (default user: false)
app #[Ajax(user: true)] Required
admin #[Ajax] Required (default user: true)
admin #[Ajax(user: false)] Not required by the annotation; use only when explicitly intended
Security

An AJAX token is not an authorization policy. Publicly callable methods must validate their inputs and enforce any necessary object-level permissions. Administrative methods should normally retain the authenticated default.

PHP: expose a method

Apply the attribute to a public controller method. No additional route declaration is needed for the APPNETOS AJAX dispatcher.

use Core\Annotation\Ajax;
use Core\Annotation\NoReturn;

#[Ajax]
#[NoReturn]
public function isDeploymentRequired(): void
{
    $this->_deploymentState->init();

    $this->json([
        'isDeploymentRequired' => $this->_deploymentState->isDeploymentRequired(),
    ]);
}

This example returns the current DNS deployment state for a live UI update. The #[NoReturn] annotation reflects the explicit response-and-exit pattern used by the controller. For methods that return values directly, the AJAX response controller serializes arrays/objects to JSON, strings to HTML, and null to HTTP 204.

JavaScript: built-in AJAX helpers

The global appnetos instance provides ready-to-use methods. Supply the fully qualified controller class name, method name, and optional request data.

Method Description
appnetos.ajaxElement(className, method, elementId, data = {}) Insert the returned HTML into an element.
appnetos.ajaxFunction(className, method, callback, data = {}) Pass the text response to a callback.
appnetos.ajaxJson(className, method, callback, data = {}) Parse JSON and pass it to a callback.
appnetos.ajaxForm(className, method, callback, form) Serialize a form and submit it asynchronously.
appnetos.ajaxRequest(className, method, data = {}, responseType = 'text', source = 'ajaxRequest') Low-level helper used by the other methods.

JSON example

appnetos.ajaxJson(
    'AppnetosDnsControl\\Admin\\Apps\\Example',
    'isDeploymentRequired',
    (result) => {
        console.log(result.isDeploymentRequired);
    }
);

Replace the illustrative class name with the actual controller FQCN. The dispatcher invokes the method without positional arguments; access submitted values through the application's request facilities.

HTML example

appnetos.ajaxElement(
    'Vendor\\Application\\App\\Example',
    'renderList',
    'results',
    { page: 2 }
);

ajaxForm() supports normal named form fields, checked checkboxes/radios, multi-select fields, and file inputs. Its serializer uses the first file for a file field.

Request security and token rotation

APPNETOS AJAX tokens are bound to the current session, application and base context. The shared token controller can create, validate, rotate and destroy them. The JavaScript client sends X-Appnetos-Ajax-Token, then reads the updated token from the response header after execution.

The request is posted to window.location.href, not to a separate application-wide AJAX URL. Errors are reported through ajaxError(); with debug enabled, additional diagnostics are logged to the browser console.

Concurrency

Because the token rotates with responses, coordinate overlapping requests when necessary. The shared JavaScript client updates its stored token from each response, but concurrent requests may have been sent with the same earlier token.

Core API Reference

Core\Ajax

Class & Registry

Class: Core\Ajax

Extends: Core\Ajax\Base

use Core\Ajax;
use Core\Registry;

$ajax = Registry::get(Ajax::class);
Method Description
__construct() Constructs the component.
init() Initializes the AJAX component.
isAjax() Checks whether the request is an AJAX request.
getAjax() Returns the AJAX request information.
getToken() Returns the AJAX token.
dispatch() Dispatches the AJAX request.
Core\Ajax\Request

Class & Registry

Class: Core\Ajax\Request

Extends: Core\Ajax\Request\Base

use Core\Ajax\Request;
use Core\Registry;

$request = Registry::get(Request::class);
Method Description
__construct() Constructs the component.
init() Initializes the AJAX request.
isAjax() Checks whether the request is an AJAX request.
getToken() Returns the request token.
getClass() Returns the requested class.
getMethod() Returns the requested method.
getData() Returns the request data.
validateAjax() Validates the AJAX request.
validateToken() Validates the request token.
validateClass() Validates the requested class.
validateMethod() Validates the requested method.
Core\Ajax\Response

Class & Registry

Class: Core\Ajax\Response

Extends: Core\Ajax\Response\Base

use Core\Ajax\Response;
use Core\Registry;

$response = Registry::get(Response::class);
Method Description
__construct() Constructs the component.
init() Initializes the AJAX response.
send(mixed $result) Sends the AJAX response.
Core\Ajax\Token

Class & Registry

Class: Core\Ajax\Token

Extends: Core\Ajax\Token\Base

use Core\Ajax\Token;
use Core\Registry;

$token = Registry::get(Token::class);
Method Description
__construct() Constructs the component.
get() Returns the current token.
create() Creates a token.
validate(string $token) Validates a token.
rotate() Rotates the token.
destroy() Destroys the token.
Core\Annotation\Ajax

Class & Usage

Class: Core\Annotation\Ajax

Type: PHP attribute (not a Registry service)

use Core\Annotation\Ajax;

#[Ajax(user: false)]
Method Description
__construct(bool $user = false) Configures whether an authenticated user is required.

The administrative annotation uses user: true by default. The public API list reflects the supplied shared AJAX classes and the app annotation; context-specific subclasses are not enumerated here.

Troubleshooting

Symptom Check
Method cannot be called Confirm the method is public, exists, and has the context-appropriate #[Ajax] annotation.
Authentication required Check the context default, the user attribute, and the active session.
Invalid or expired token Ensure the initial page supplies APPNETOS_AJAX_TOKEN and requests use the built-in client headers.
Unexpected JSON parsing error Use ajaxJson() only when the PHP method returns JSON.
Missing HTML update Check the target element ID and the returned HTML.

Next Steps

Previous

Mailer

Explore Mailer

Next

Diagnostics & Lifecycle

Explore Diagnostics & Lifecycle