Extending the RAMP Deploy Process

RAMP supports the addition of extra batch items being sent during the batch process. There are 5 available callback points available:

Batch Preflight:

• preflight_send_callback: the preflight send callback is used on the staging server to gather and return a dataset that is to be sent to the production server during a preflight operation. There must be a corresponding preflight_check_callback defined as well.
• preflight_check_callback: the preflight check callback is used on the production server to process the dataset built by the preflight_send_callback and return messages to the staging server.
• preflight_display_callback: the preflight display callback can be used to format preflight messages for display or to inject messages in to other parts of the returned preflight messages. ie: if the preflight check callback returned a message about another post in the batch then that message can be appended to the messages for that post. If this method returns data then there will be an additional section in the preflight screen. If nothing is returned then no extra section shows up during preflight.

Batch Send:

• send_callback: the send callback is used on the staging server to gather and return a dataset that is to be sent to the production server during a batch transfer. There must be a corresponding receive_callback defined as well.
• receive_callback: the receive callback is used on the destination server to process the datast that was built by the send_callback. The receive callback should return a success/failure message to the staging server in the form of and array: array('success' => bool, 'message' => string);

Callback Registration

$name = 'My Batch Extras';
$description = 'Verifying and sending some extra data with the batch process';

cfd_register_deploy_callback($name, $description, array(
	'send_callback' => '_send_callback', 
	'receive_callback' => '_receive_callback',
	'preflight_send_callback' => '_preflight_send_callback',
	'preflight_check_callback' => '_preflight_check_callback',
	'preflight_display_callback' => '_merge_batch_messages_callback'
));

Example Code

	function my_cfd_register_callback() {
		cfd_register_deploy_callback('my-callback-id', 'short description about what this is for', array(
			// batch send
			'send_callback' => 'my_send_callback', 
			'receive_callback' => 'my_receive_callback',
			// batch preflight
			'preflight_send_callback' => 'my_preflight_send_callback',
			'preflight_check_callback' => 'my_preflight_check_callback',
			'preflight_display_callback' => 'my_preflight_display_callback'
		));
	}
	add_action('init', 'my_cfd_register_callback');

	// Batch Send

		/**
		 * Inspect the Batch data and return back data to processed at the end of import
		 *
		 * @param array $batch_data 
		 * @return mixed
		 */
		function my_send_callback($batch_data) {
			$ret = array();

			// inspect $batch_data and build a data set to be sent after all items have been imported
			// data will be delivered to the corresponding `receive_callback` method

			return $ret;
		}

		/**
		 * Process data sent by the corresponding `send_callback` method
		 *
		 * @param mixed $callback_generated_data 
		 * @return array
		 */
		function my_receive_callback($callback_generated_data) {
			// perform operations on the received data
			// $callback_generated_data is the raw data generated by the corresponding `send_callback` method

			// REQUIRED: must return a message
			return array(
				'success' => $success, // boolean, wether the callback succeeded or not
				'message' => $message  // a message to go along with the appropriate $success setting
			);
		}

	// Batch Preflight

		/**
		 * Inspect the Batch data and return back data to be preflighted 
		 *
		 * @param string $batch_data 
		 * @return void
		 */
		function my_preflight_send_callback($batch_data) {
			$ret = array();

			// inspect $batch_data and build information to be preflighted on the other end
			// data will be delivered to the corresponding `my_preflight_check_callback` method

			return $ret;
		}

		/**
		 * Return back any notice or error messages to the sending server
		 * Returning errors will not allow the batch to be deployed
		 * Returning notices will simply give informational data to the user
		 *
		 * @param string $callback_generated_data 
		 * @param string $batch_data 
		 * @return void
		 */
		function my_preflight_check_callback($callback_generated_data, $batch_data) {
			$messages = array();

			// inspect data and construct messages to be displayed in the preflight screen
			// it is not required to return any messages, in which case return an empty array

			// To set an error: $messages['error'] = 'foo!';
			// To set a notice: $messages['notice'] = 'bar!';

			return $messages;
		}

		/**
		 * Manipulate the returned messages from the preflight process
		 *
		 * @param array $batch_preflight_data 
		 * @return array
		 */
		function my_preflight_display_callback($batch_preflight_data) {
			if (!empty($batch_preflight_data['extras']['my-callback-id'])) {
				// modify the preflight data if desired
				// ie: if a message needs to be attached to another item in the batch it can be done now
				// $batch_preflight_messages is the ENTIRE preflight messages array, modify carefully and return
			}
			return $batch_preflight_data;
		}	

See also:

[sibling-pages]