Hooks migration, import et export

Ces hooks servent à proposer un import depuis une extension d’événements que HappenBoard ne gère pas. Ils permettent aussi de copier des données supplémentaires pendant un import The Events Calendar et d’ajouter vos propres réglages au fichier de sauvegarde JSON. Les cinq sont fournis par l’extension gratuite.

Le côté administrateur est décrit dans Migrer depuis une autre extension. Le fichier de sauvegarde est présenté dans Import/export CSV et sauvegarde des réglages. Si vous n’avez jamais utilisé les hooks de HappenBoard, commencez par Étendre HappenBoard avec les hooks.

Les imports et exports sans hook

L’import de fichier .ics, l’import et l’export CSV des événements, ainsi que l’import CSV des participants et l’export CSV des commandes de Pro n’ont pas de hook. Le téléchargement du CSV des commandes dépend d’une permission : la capacité Pro happenboard_export_orders, donnée aux administrateurs par défaut. Pour l’accorder à d’autres rôles, utilisez les filtres décrits dans Hooks administration, rôles et permissions.

Écrire un adaptateur de migration

Une source de migration est une classe PHP qui implémente HappenBoard\Service\Migration\MigratorAdapter. Vous l’enregistrez avec happenboard_migration_adapters. Elle apparaît ensuite dans HappenBoard → Settings → Migration dès que sa méthode detect() trouve les données de la source.

L’écran propose Preview (dry run), puis Migrate for real. Chaque passage appelle migrate() en boucle avec dry_run, batch_size (50), offset et include (vide pour tout importer). Remplissez un HappenBoard\Service\Migration\Result avec count_created(), count_skipped(), count_failed() et add_error(), puis renseignez next_offset et done. L’écran s’arrête quand done vaut true. Si next_offset n’avance plus sans que done soit true, il affiche le passage comme interrompu, avec un bouton Continue qui reprend au dernier offset.

Pour un élément importé qui a perdu quelque chose en route, appelez add_warning( $resource, $source_id, $reason ) : il ne compte pas comme un échec et s’affiche sous View N warnings.

Le trait HappenBoard\Service\Migration\MigrationHelpers regroupe les outils des adaptateurs fournis. find_migrated() et mark_migrated() permettent à un second passage d’ignorer ce que le premier a importé (un contenu importé mis à la corbeille compte comme non importé). local_to_utc_iso() convertit une date locale au format UTC que stocke HappenBoard. Pour une source qui enregistre ses événements comme des articles, migrate() peut ressembler à ceci :

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' ); // Déjà importé par un passage précédent.
            continue;
        }
        if ( ! empty( $options['dry_run'] ) ) {
            $result->count_created( 'events' ); // Aperçu : on compte, on n'écrit rien.
            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 );
        // Les dates n'existaient pas pendant wp_insert_post() : on les construit maintenant.
        ( 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 implémente
        // \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;
        }
        // Lire ce dont le lot aura besoin.
        $map = my_build_field_map();

        // N'enregistrer que lors d'un vrai passage.
        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' ); // Ajoute une ligne « prices » aux résultats.
    },
    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() );

        // Le fichier est téléchargé et circule : pas de secrets dedans.
        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 {
        // Le fichier peut venir d'un site sans votre extension.
        if ( empty( $payload['my_plugin'] ) || ! is_array( $payload['my_plugin'] ) ) {
            $applied['my_plugin'] = false;
            return $applied;
        }
        // Mise à jour partielle : les clés absentes du fichier gardent leur valeur.
        $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
);

Pour aller plus loin

• Migrer depuis une autre extension : ce que voit l’administrateur sur l’écran Migration.
• Hooks événements, récurrence et séries : les hooks qui s’exécutent à l’enregistrement des événements importés et de leurs dates.