suredonation_import_phase_mappers Filter Hook

Overview

The suredonation_import_phase_mappers filter allows developers to register custom mapper classes for SureDonation’s CSV import phases.

A SureDonation import runs through different phases. Each phase is mapped to a specific mapper class that processes the imported data.

Use this filter to add a custom import phase and connect it to your own mapper class.

SureDonation Pro uses this filter to add its subscriptions import phase.

When to Use This Filter

Use this filter when you need to:

• Add a custom CSV import phase.
• Register a custom mapper class.
• Extend SureDonation’s import process.
• Process custom data during an import.
• Add import support through a plugin or extension.

Filter Signature

apply_filters( 'suredonation_import_phase_mappers', $mappers);

apply_filters( 'suredonation_import_phase_mappers', $mappers);

Parameters

Default Mappers

SureDonation provides the following built-in phase mappers:

Return Value

Return the modified phase-to-class map.

return $mappers;

If a requested phase is not present in the returned map, its mapper resolves to null and that phase is skipped.

Basic Usage

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

function your_custom_function( $mappers ) {

    // Add custom phase mappers here.

    return $mappers;

}

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

function your_custom_function( $mappers ) {

    // Add custom phase mappers here.

    return $mappers;

}

Example: Register a Custom Import Phase

The following example registers a pledges phase with a custom mapper class.

add_filter(  'suredonation_import_phase_mappers',  'mysite_register_pledges_phase', 10, 1);

function mysite_register_pledges_phase( $mappers ) {

    $mappers['pledges'] = \MySite\Import\Pledges_Import_Mapper::class;

    return $mappers;

}

add_filter(  'suredonation_import_phase_mappers',  'mysite_register_pledges_phase', 10, 1);

function mysite_register_pledges_phase( $mappers ) {

    $mappers['pledges'] = \MySite\Import\Pledges_Import_Mapper::class;

    return $mappers;

}

How the Example Works

1. SureDonation provides the existing import phase mapper map.
2. The filter adds a new pledges phase.
3. The fully qualified mapper class name is assigned to the phase.
4. The modified map is returned.
5. When the import runner reaches the pledges phase, it resolves and uses the registered mapper.

Mapper Class Requirements

The filter expects a class name, not a class instance.

Correct: $mappers[‘pledges’] = \MySite\Import\Pledges_Import_Mapper::class;

Do not pass an instantiated object: $mappers[‘pledges’] = new \MySite\Import\Pledges_Import_Mapper();

The import runner resolves the registered class to its singleton instance.

Your custom mapper should provide the same interface and behavior expected by the built-in import mappers.

The mapper receives:

• The mapped row.
• The progress payload.
• The dry-run flag.

It is also responsible for updating the appropriate phase result counters.

For a minimal implementation, refer to the Donors_Import_Mapper class.

Import Phase Flow

The filter is part of the import phase resolution process:

1. A CSV import session is created.
2. SureDonation determines the phases included in the import.
3. The import runner requests the mapper for the current phase.
4. The suredonation_import_phase_mappers filter is applied.
5. SureDonation looks up the mapper class for the requested phase.
6. The runner resolves the class to its singleton.
7. The mapper processes the imported rows.
8. The phase result counters are updated.

Important: Registering the Phase Is Not Enough

Adding a mapper to this filter does not automatically cause the import runner to execute the phase.

The custom phase must also be included in the import session’s phase list.

For example: pledges

must be present in the phases being processed before the runner can reach the registered mapper.

Extending Existing Import Phases

Be careful when replacing an existing mapper.

For example:

$mappers['donations'] = \MySite\Import\Custom_Donations_Mapper::class;

$mappers['donations'] = \MySite\Import\Custom_Donations_Mapper::class;

This changes how SureDonation’s core donation import is processed.

If you only need to modify or extend imported donation rows, prefer using: suredonation_import_donation_row

instead of replacing the built-in donation mapper.

Example: Add a Custom Mapper Without Replacing Core Mappers

add_filter( 'suredonation_import_phase_mappers', 'mysite_add_custom_import_phase',   10, 1);

function mysite_add_custom_import_phase( $mappers ) {

    // Keep all existing SureDonation mappers.

    $mappers['pledges'] = \MySite\Import\Pledges_Import_Mapper::class;

    return $mappers;

}

add_filter( 'suredonation_import_phase_mappers', 'mysite_add_custom_import_phase',   10, 1);

function mysite_add_custom_import_phase( $mappers ) {

    // Keep all existing SureDonation mappers.

    $mappers['pledges'] = \MySite\Import\Pledges_Import_Mapper::class;

    return $mappers;

}

This approach preserves the existing donations and donors import behavior while adding the custom phase.

Related Hooks

• suredonation_import_donation_row:Allows developers to modify or extend imported donation rows.
• Suredonation_import_givewp_phase_mappers: Filters mapper classes used for GiveWP import phases.
• Suredonation_import_givewp_phases: Filters the phases used during GiveWP imports.
• Suredonation_import_session_created: Runs when a SureDonation import session is created.