Update donation data, Filter Hook

Overview

The suredonation_update_donation_data filter allows developers to modify the donation data before it is saved during a SureDonation REST API update request.

You can use this filter to add, remove, or modify values before the updated donation data is persisted.

The array returned by the filter is the data that SureDonation uses for the update.

When to Use This Filter

Use this filter when you need to customize donation data during a REST API update.

For example, you can use it to:

• Add custom donation fields.
• Modify existing donation values.
• Set a default value.
• Apply custom business rules.
• Add additional data before the donation is updated.

Filter Signature

apply_filters( 'suredonation_update_donation_data', $update_data, $request, $donation_id );

apply_filters( 'suredonation_update_donation_data', $update_data, $request, $donation_id );

Parameters

Available Update Fields

The $update_data array can contain the following fields:

• campaign_id
• donor_name
• donor_email
• donor_phone
• amount
• fees_covered
• donation_type
• is_anonymous
• donor_comment
• payment_status
• gateway
• transaction_id

The $update_data array may be empty if no supported fields were supplied in the REST request.

Return Value

The callback must return an array containing the donation data to be updated.

The returned array can be:

• The original $update_data array.
• A modified version of $update_data.
• An empty array if no update should be performed.

SureDonation only writes the update when the returned array is not empty.

Basic Usage

Use add_filter() to register your callback.

add_filter( 'suredonation_update_donation_data', 'your_custom_function', 10, 3 );

function your_custom_function( $update_data, $request, $donation_id ) {

    // Modify the update data here.

    return $update_data;

}

add_filter( 'suredonation_update_donation_data', 'your_custom_function', 10, 3 );

function your_custom_function( $update_data, $request, $donation_id ) {

    // Modify the update data here.

    return $update_data;

}

Example: Add a Currency Value

The following example adds a currency value to the update data whenever there is data available to update.

add_filter( 'suredonation_update_donation_data', 'mysite_force_currency', 10, 3 );

function mysite_force_currency( $update_data, $request, $donation_id ) {

    if ( ! empty( $update_data ) ) {

        $update_data['currency'] = 'USD';

    }

    return $update_data;

}

add_filter( 'suredonation_update_donation_data', 'mysite_force_currency', 10, 3 );

function mysite_force_currency( $update_data, $request, $donation_id ) {

    if ( ! empty( $update_data ) ) {

        $update_data['currency'] = 'USD';

    }

    return $update_data;

}

In this example, the currency value is added to the data before it is persisted.

Example: Modify an Existing Value

You can also modify an existing value before the donation is updated.

add_filter( 'suredonation_update_donation_data', 'mysite_modify_donor_name', 10, 3 );

function mysite_modify_donor_name( $update_data, $request, $donation_id ) {

    if ( isset( $update_data['donor_name'] ) ) {

        $update_data['donor_name'] = sanitize_text_field(

            $update_data['donor_name']

        );

    }

    return $update_data;

}

add_filter( 'suredonation_update_donation_data', 'mysite_modify_donor_name', 10, 3 );

function mysite_modify_donor_name( $update_data, $request, $donation_id ) {

    if ( isset( $update_data['donor_name'] ) ) {

        $update_data['donor_name'] = sanitize_text_field(

            $update_data['donor_name']

        );

    }

    return $update_data;

}

Update Flow

The filter is applied as part of the REST API donation update process:

1. A REST API update request is received.
2. SureDonation validates the request.
3. SureDonation confirms that the donation exists.
4. Supported request parameters are collected into $update_data.
5. The suredonation_update_donation_data filter is applied.
6. Your callback can modify the update data.
7. SureDonation persists the returned data.
8. If the returned array is empty, no update is performed.

Related Hooks

• suredonation_create_donation_data
  Filters donation data before a new donation is created.
• suredonation_donation_status_changed
  Runs when the status of a donation changes.