WordPress.org
Get WordPress
WordPress.org

WordPress Developer Resources

WP_Ajax_Response::add()

WP_Ajax_Response::add( string|array $args = ” ): string

In this article

Back to top

Appends data to an XML response based on given arguments.

Description

With $args defaults, extra data output would be:

<response action='{$action}_$id'>
 <$what id='$id' position='$position'>
     <response_data><![CDATA[$data]]></response_data>
 </$what>
</response>

Parameters

$argsstring|arrayoptional
An array or string of XML response arguments.
  • what string
    XML-RPC response type. Used as a child element of <response>.
    Default 'object' (<object>).
  • action string|false
    Value to use for the action attribute in <response>. Will be appended with _$id on output. If false, $action will default to the value of $_POST['action']. Default false.
  • id int|WP_Error
    The response ID, used as the response type id attribute. Also accepts a WP_Error object if the ID does not exist. Default 0.
  • old_id int|false
    The previous response ID. Used as the value for the response type old_id attribute. False hides the attribute. Default false.
  • position string
    Value of the response type position attribute. Accepts 1 (bottom), -1 (top), HTML ID (after), or -HTML ID (before). Default 1 (bottom).
  • data string|WP_Error
    The response content/message. Also accepts a WP_Error object if the ID does not exist.
  • supplemental array
    An array of extra strings that will be output within a <supplemental> element as CDATA. Default empty array.

Default:''

Return

string XML response.

Source

public function add( $args = '' ) {
	$defaults = array(
		'what'         => 'object',
		'action'       => false,
		'id'           => '0',
		'old_id'       => false,
		'position'     => 1,
		'data'         => '',
		'supplemental' => array(),
	);

	$parsed_args = wp_parse_args( $args, $defaults );

	$position = preg_replace( '/[^a-z0-9:_-]/i', '', $parsed_args['position'] );
	$id       = $parsed_args['id'];
	$what     = $parsed_args['what'];
	$action   = $parsed_args['action'];
	$old_id   = $parsed_args['old_id'];
	$data     = $parsed_args['data'];

	if ( is_wp_error( $id ) ) {
		$data = $id;
		$id   = 0;
	}

	$response = '';
	if ( is_wp_error( $data ) ) {
		foreach ( (array) $data->get_error_codes() as $code ) {
			$response  .= "<wp_error code='$code'><![CDATA[" . $data->get_error_message( $code ) . ']]></wp_error>';
			$error_data = $data->get_error_data( $code );
			if ( ! $error_data ) {
				continue;
			}
			$class = '';
			if ( is_object( $error_data ) ) {
				$class      = ' class="' . get_class( $error_data ) . '"';
				$error_data = get_object_vars( $error_data );
			}

			$response .= "<wp_error_data code='$code'$class>";

			if ( is_scalar( $error_data ) ) {
				$response .= "<![CDATA[$error_data]]>";
			} elseif ( is_array( $error_data ) ) {
				foreach ( $error_data as $k => $v ) {
					$response .= "<$k><![CDATA[$v]]></$k>";
				}
			}

			$response .= '</wp_error_data>';
		}
	} else {
		$response = "<response_data><![CDATA[$data]]></response_data>";
	}

	$s = '';
	if ( is_array( $parsed_args['supplemental'] ) ) {
		foreach ( $parsed_args['supplemental'] as $k => $v ) {
			$s .= "<$k><![CDATA[$v]]></$k>";
		}
		$s = "<supplemental>$s</supplemental>";
	}

	if ( false === $action ) {
		$action = $_POST['action'];
	}
	$x  = '';
	$x .= "<response action='{$action}_$id'>"; // The action attribute in the xml output is formatted like a nonce action.
	$x .= "<$what id='$id' " . ( false === $old_id ? '' : "old_id='$old_id' " ) . "position='$position'>";
	$x .= $response;
	$x .= $s;
	$x .= "</$what>";
	$x .= '</response>';

	$this->responses[] = $x;
	return $x;
}

View all references View on Trac View on GitHub

UsesDescription
wp_parse_args()wp-includes/functions.php

Merges user defined arguments into defaults array.

is_wp_error()wp-includes/load.php

Checks whether the given variable is a WordPress Error.

Used byDescription
WP_Ajax_Response::__construct()wp-includes/class-wp-ajax-response.php

Constructor – Passes args to WP_Ajax_Response::add().

Changelog

VersionDescription
2.1.0Introduced.

User Contributed Notes

You must log in before being able to contribute a note or feedback.