Migration, import and export hooks

These hooks let you add an import from an events plugin HappenBoard does not support. They also let you copy extra data during a The Events Calendar import and add your own settings to the JSON backup file. All five come with the free plugin.

The site owner’s side is in Migrating from another plugin. The backup file is covered in CSV import/export and settings backup. If you are new to HappenBoard hooks, start with Extending HappenBoard with hooks.

Imports and exports without hooks

The .ics file import, the events CSV import and export, and Pro’s attendee CSV import and orders CSV export have no hooks of their own. Who may download the orders CSV is a permission: Pro’s happenboard_export_orders capability, given to administrators by default. You can grant it to other roles with the filters on Admin, roles and capability hooks.

Write a migration adapter

A migration source is a PHP class that implements HappenBoard\Service\Migration\MigratorAdapter. You register it with happenboard_migration_adapters. It then appears under HappenBoard → Settings → Migration whenever its detect() method finds the source data.

The screen offers Preview (dry run), then Migrate for real. Each run calls migrate() again and again with dry_run, batch_size (50), offset and include (empty means everything). Fill a HappenBoard\Service\Migration\Result with count_created(), count_skipped(), count_failed() and add_error(), then set next_offset and done. The screen stops when done is true. When next_offset stops moving without done, it shows the run as stopped, with a Continue button that carries on from the last offset.

For a record that was imported but lost something on the way, call add_warning( $resource, $source_id, $reason ): it does not count as a failure and is listed under View N warnings.

The HappenBoard\Service\Migration\MigrationHelpers trait holds the helpers the built-in adapters use. find_migrated() and mark_migrated() let a second run skip what the first one imported (an imported post in the trash counts as not imported). local_to_utc_iso() turns a local date into the UTC format HappenBoard stores. For a source that keeps its events as posts, migrate() can look like this:

public function migrate( array $options ): \HappenBoard\Service\Migration\Result {
    $result = new \HappenBoard\Service\Migration\Result();
    $batch  = max( 1, (int) ( $options['batch_size'] ?? 50 ) );
    $offset = max( 0, (int) ( $options['offset'] ?? 0 ) );
    $ids    = get_posts( array(
        'post_type'      => 'mycal_event',
        'post_status'    => 'any',
        'posts_per_page' => $batch,
        'offset'         => $offset,
        'orderby'        => 'ID',
        'order'          => 'ASC',
        'fields'         => 'ids',
    ) );

    foreach ( $ids as $source_id ) {
        if ( $this->find_migrated( 'my-calendar', 'hboard_event', $source_id ) > 0 ) {
            $result->count_skipped( 'events' ); // Imported by an earlier run.
            continue;
        }
        if ( ! empty( $options['dry_run'] ) ) {
            $result->count_created( 'events' ); // Preview: count, write nothing.
            continue;
        }
        $new_id = wp_insert_post( array(
            'post_type'   => 'hboard_event',
            'post_status' => get_post_status( $source_id ),
            'post_title'  => get_the_title( $source_id ),
        ), true );
        if ( is_wp_error( $new_id ) ) {
            $result->count_failed( 'events' );
            $result->add_error( 'events', $source_id, $new_id->get_error_message() );
            continue;
        }
        $start = $this->local_to_utc_iso( (string) get_post_meta( $source_id, 'mycal_start', true ) );
        update_post_meta( $new_id, '_happenboard_start', $start );
        update_post_meta( $new_id, '_happenboard_end', $start );
        // The dates did not exist when wp_insert_post() ran: build them now.
        ( new \HappenBoard\Service\Events\OccurrenceSyncer() )->sync( (int) $new_id );
        $this->mark_migrated( (int) $new_id, 'my-calendar', $source_id );
        $result->count_created( 'events' );
    }

    $result->next_offset = $offset + count( $ids );
    $result->done        = count( $ids ) < $batch;

    return $result;
}

apply_filters( 'happenboard_migration_adapters', array $adapters )

add_filter(
    'happenboard_migration_adapters',
    function ( array $adapters ): array {
        // My_Calendar_Adapter implements
        // \HappenBoard\Service\Migration\MigratorAdapter.
        require_once __DIR__ . '/class-my-calendar-adapter.php';
        $adapters[] = new My_Calendar_Adapter();

        return $adapters;
    }
);

do_action( 'happenboard_migration_before_events', string $source_id, bool $dry )

add_action(
    'happenboard_migration_before_events',
    function ( string $source_id, bool $dry ): void {
        if ( 'the-events-calendar' !== $source_id ) {
            return;
        }
        // Read what the batch will need.
        $map = my_build_field_map();

        // Save it on a real run only.
        if ( ! $dry ) {
            update_option( 'my_field_map', $map, false );
        }
    },
    10,
    2
);

do_action( 'happenboard_migration_event_imported', int $new_id, int $source_id, string $adapter_id, Result $result )

add_action(
    'happenboard_migration_event_imported',
    function ( $new_id, $source_id, $adapter_id, $result ) {
        if ( 'the-events-calendar' !== $adapter_id ) {
            return;
        }
        $cost = (string) get_post_meta( $source_id, '_EventCost', true );
        if ( '' === $cost ) {
            return;
        }
        if ( ! is_numeric( $cost ) ) {
            $result->add_error( 'prices', $source_id, 'Unreadable cost.' );
            return;
        }
        update_post_meta( $new_id, '_my_price', $cost );
        $result->count_created( 'prices' ); // Adds a "prices" row to the results.
    },
    10,
    4
);

apply_filters( 'happenboard_settings_backup_export', array $payload )

add_filter(
    'happenboard_settings_backup_export',
    function ( array $payload ): array {
        $settings = (array) get_option( 'my_plugin_settings', array() );

        // The file gets downloaded and passed around: keep secrets out.
        unset( $settings['api_secret'] );

        $payload['my_plugin'] = $settings;

        return $payload;
    }
);

apply_filters( 'happenboard_settings_backup_import', array $applied, array $payload )

add_filter(
    'happenboard_settings_backup_import',
    function ( array $applied, array $payload ): array {
        // The file may come from a site without your plugin.
        if ( empty( $payload['my_plugin'] ) || ! is_array( $payload['my_plugin'] ) ) {
            $applied['my_plugin'] = false;
            return $applied;
        }
        // Patch: keys missing from the file keep their value.
        $current = (array) get_option( 'my_plugin_settings', array() );
        $clean   = map_deep( $payload['my_plugin'], 'sanitize_text_field' );
        update_option( 'my_plugin_settings', array_merge( $current, $clean ) );
        $applied['my_plugin'] = true;

        return $applied;
    },
    10,
    2
);

Next steps

• Migrating from another plugin: what the site owner sees on the Migration screen.
• Events, recurrence and series hooks: the hooks that run when imported events and their dates are saved.