suredonation_import_givewp_phase_mappers Filter Hook

Overview

The suredonation_import_givewp_phase_mappers filter allows developers to register or modify the mapper classes used during a GiveWP migration.

Each migration phase is assigned to a mapper class. The mapper is responsible for processing the records associated with that phase.

Use this filter when you add a custom migration phase with suredonation_import_givewp_phases and need to define how that phase should be processed.

When to Use This Filter

Use this filter to:

• Register a mapper for a custom GiveWP migration phase.
• Extend the existing phase-to-mapper configuration.
• Replace a built-in mapper when custom processing is required.
• Connect a migration phase with your custom mapper class.

Filter Signature

apply_filters( 'suredonation_import_givewp_phase_mappers',  $mappers );

apply_filters( 'suredonation_import_givewp_phase_mappers',  $mappers );

Parameters

Default Mappers

SureDonation provides the following default mappings:

[
    'campaigns' => Campaign_Mapper::class,
    'donations' => Donation_Mapper::class,
]

[
    'campaigns' => Campaign_Mapper::class,
    'donations' => Donation_Mapper::class,
]

Return Value

Return the phase-to-mapper class map.

return $mappers;

Each registered mapper class must provide:

• A public process_batch( &$progress, $offset ) method.
• A static get_instance() method.

The process_batch() method should return the number of source records processed.

Basic Usage

add_filter( 'suredonation_import_givewp_phase_mappers', 'your_custom_function',   10,  1);

function your_custom_function( $mappers ) {

    // Add or modify mapper registrations here.

    return $mappers;

}

add_filter( 'suredonation_import_givewp_phase_mappers', 'your_custom_function',   10,  1);

function your_custom_function( $mappers ) {

    // Add or modify mapper registrations here.

    return $mappers;

}

Example: Register a Custom Mapper

The following example registers a mapper for a custom migration phase.

add_filter( 'suredonation_import_givewp_phase_mappers',  'mysite_register_mapper', 10,  1);

function mysite_register_mapper( $mappers ) {

    $mappers['my_custom_phase'] = \MyPlugin\Import\My_Custom_Mapper::class;

    return $mappers;

}

add_filter( 'suredonation_import_givewp_phase_mappers',  'mysite_register_mapper', 10,  1);

function mysite_register_mapper( $mappers ) {

    $mappers['my_custom_phase'] = \MyPlugin\Import\My_Custom_Mapper::class;

    return $mappers;

}

The resulting map contains:

[
    'campaigns'       => Campaign_Mapper::class,
    'donations'       => Donation_Mapper::class,
    'my_custom_phase' => \MyPlugin\Import\My_Custom_Mapper::class,
]

[
    'campaigns'       => Campaign_Mapper::class,
    'donations'       => Donation_Mapper::class,
    'my_custom_phase' => \MyPlugin\Import\My_Custom_Mapper::class,
]

Creating a Custom Mapper

Your custom mapper must provide the methods expected by the GiveWP migration runner.

A simplified structure looks like this: namespace MyPlugin\Import;

class My_Custom_Mapper {

    public static function get_instance() {

        // Return the mapper instance.

    }

    public function process_batch( &$progress, $offset ) {

        // Process records for this phase.

        return $processed;

    }

}

class My_Custom_Mapper {

    public static function get_instance() {

        // Return the mapper instance.

    }

    public function process_batch( &$progress, $offset ) {

        // Process records for this phase.

        return $processed;

    }

}

The process_batch() method should return the number of source records processed during the batch.

Migration Flow

The mapper filter is part of the GiveWP migration process:

1. SureDonation determines the phases that need to run.
2. The migration runner requests the mapper for the current phase.
3. The suredonation_import_givewp_phase_mappers filter is applied.
4. SureDonation looks for the mapper class associated with the phase.
5. The mapper’s get_instance() method is used to resolve the mapper.
6. The migration runner calls process_batch().
7. The mapper processes the records for that phase.
8. The migration continues with the next phase.

Important: Register the Phase Separately

Registering a mapper does not automatically add the phase to the migration.

For example, registering:

$mappers['my_custom_phase'] = \MyPlugin\Import\My_Custom_Mapper::class;

$mappers['my_custom_phase'] = \MyPlugin\Import\My_Custom_Mapper::class;

does not cause my_custom_phase to run automatically.

The phase must also be added using:

suredonation_import_givewp_phases

For example:

add_filter(

    'suredonation_import_givewp_phases',

    function ( $phases ) {

        $phases[] = 'my_custom_phase';

        return $phases;

    }

);

add_filter(

    'suredonation_import_givewp_phases',

    function ( $phases ) {

        $phases[] = 'my_custom_phase';

        return $phases;

    }

);

Handling Invalid Mappers

If the requested phase:

• Does not exist in the mapper map.
• Points to a class that does not exist.
• Points to a class without a callable get_instance() method.

the mapper resolves to null, and the migration phase is skipped.

Make sure your custom mapper class is loaded and provides the required methods before registering it.

Related Hooks

• suredonation_import_givewp_phases: Controls which phases are included in a GiveWP migration.
• suredonation_import_givewp_batch_complete: Runs when a GiveWP migration batch is completed.