suredonation_import_givewp_phases Filter Hook

Overview

The suredonation_import_givewp_phases filter allows developers to modify the list of phases that SureDonation runs during a GiveWP migration.

You can use this filter to:

• Add custom migration phases.
• Remove existing phases.
• Reorder migration phases.
• Add additional processing to a GiveWP migration.

SureDonation Pro uses this filter to add a subscriptions phase and, when enabled, a standalone_donors phase.

When to Use This Filter

Use this filter when your extension needs to add custom processing to the GiveWP migration workflow.

For example, you can add a custom phase after the standard donations phase:

campaigns → donations → my_custom_phase

Filter Signature

apply_filters( 'suredonation_import_givewp_phases', $phases,  $options);

apply_filters( 'suredonation_import_givewp_phases', $phases,  $options);

Parameters

Default Phases

The free version of SureDonation uses:

[
 'campaigns',
 'donations',
]

[
 'campaigns',
 'donations',
]

$options

The $options array contains the resolved settings for the migration session.

It can include values such as:

• include_standalone_donors
• campaign_ids
• Other GiveWP migration options

Return Value

Return an array containing the phase names that should be executed.

return $phases;

SureDonation normalizes the returned value by:

• Converting phase names to strings.
• Removing duplicate phase names.
• Reindexing the array.

If a non-array value is returned, SureDonation converts it to an empty list, which prevents the migration session from being created.

Basic Usage

add_filter('suredonation_import_givewp_phases', 'your_custom_function', 10, 2);

function your_custom_function( $phases, $options ) {

    // Modify the migration phases here.

    return $phases;

}

add_filter('suredonation_import_givewp_phases', 'your_custom_function', 10, 2);

function your_custom_function( $phases, $options ) {

    // Modify the migration phases here.

    return $phases;

}

Example: Add a Custom Phase

The following example adds a my_custom_phase after the existing migration phases.

add_filter('suredonation_import_givewp_phases','mysite_add_phase', 10, 2);

function mysite_add_phase( $phases, $options ) {

    // Run a custom phase after donations.

    $phases[] = 'my_custom_phase';

    return $phases;

}

add_filter('suredonation_import_givewp_phases','mysite_add_phase', 10, 2);

function mysite_add_phase( $phases, $options ) {

    // Run a custom phase after donations.

    $phases[] = 'my_custom_phase';

    return $phases;

}

The resulting phase list will be:

[
    'campaigns',
    'donations',
    'my_custom_phase',
]

[
    'campaigns',
    'donations',
    'my_custom_phase',
]

Example: Add a Phase at a Specific Position

You can also control where your custom phase runs.

add_filter(  'suredonation_import_givewp_phases','mysite_insert_custom_phase',  10, 2);

function mysite_insert_custom_phase( $phases, $options ) {

    $position = array_search( 'donations', $phases, true );

    if ( false !== $position ) {

        array_splice( $phases, $position + 1, 0, 'my_custom_phase' );

    }

    return $phases;

}

add_filter(  'suredonation_import_givewp_phases','mysite_insert_custom_phase',  10, 2);

function mysite_insert_custom_phase( $phases, $options ) {

    $position = array_search( 'donations', $phases, true );

    if ( false !== $position ) {

        array_splice( $phases, $position + 1, 0, 'my_custom_phase' );

    }

    return $phases;

}

This places the custom phase immediately after donations.

Example: Conditionally Add a Phase

You can use $options to add a phase only when a specific migration option is enabled.

add_filter( 'suredonation_import_givewp_phases', 'mysite_add_standalone_phase',10, 2);

function mysite_add_standalone_phase( $phases, $options ) {

    if ( ! empty( $options['include_standalone_donors'] ) ) {

        $phases[] = 'standalone_donors';

    }

    return $phases;

}

add_filter( 'suredonation_import_givewp_phases', 'mysite_add_standalone_phase',10, 2);

function mysite_add_standalone_phase( $phases, $options ) {

    if ( ! empty( $options['include_standalone_donors'] ) ) {

        $phases[] = 'standalone_donors';

    }

    return $phases;

}

Important: Register a Mapper for Custom Phases

Adding a phase to this filter does not automatically tell SureDonation how to process it.

Every custom phase must have a corresponding mapper registered using:

suredonation_import_givewp_phase_mappers

For example: $phases[] = ‘my_custom_phase’;

must have a matching mapper for: my_custom_phase

Otherwise, the migration runner will not have a mapper available to process the phase.

GiveWP Migration Flow

The filter is part of the GiveWP migration session creation process:

1. SureDonation prepares the GiveWP migration options.
2. SureDonation determines the campaign IDs to migrate.
3. The default migration phases are prepared.
4. The suredonation_import_givewp_phases filter is applied.
5. Your callback can add, remove, or reorder phases.
6. SureDonation normalizes the returned phase list.
7. The migration session is created with the resulting phases.
8. Each phase is processed using its registered mapper.

Related Hooks

• Suredonation_import_givewp_phase_mappers: Registers the mapper classes used to process GiveWP migration phases.
• Suredonation_import_givewp_session_created: Runs after a GiveWP migration session has been created.