W3cubDocs

/WordPress

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

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

$args

(string|array) (Optional) 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 value: ''

Return

(string) XML response.

Source

File: wp-includes/class-wp-ajax-response.php

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;
	}

Changelog

Version Description
2.1.0 Introduced.

© 2003–2019 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/classes/wp_ajax_response/add