Feature: Add support for running migration in batches

src/Campaigns/Migrations/Donations/AddCampaignId.php

@@ -5,13 +5,14 @@
 use Give\Donations\ValueObjects\DonationMetaKeys;
 use Give\Framework\Database\DB;
 use Give\Framework\Database\Exceptions\DatabaseQueryException;
+use Give\Framework\Migrations\Contracts\BatchMigration;
 use Give\Framework\Migrations\Contracts\Migration;
 use Give\Framework\Migrations\Exceptions\DatabaseMigrationException;
 
 /**
  * @unreleased
  */
-class AddCampaignId extends Migration
+class AddCampaignId extends Migration implements BatchMigration
 {
     /**
      * @inheritDoc
@@ -41,7 +42,7 @@ public static function timestamp(): string
      * @inheritDoc
      * @throws DatabaseMigrationException
      */
-    public function run()
+    public function runBatch($batchNumber)
     {
         $relationships = [];
 
@@ -63,6 +64,8 @@ public function run()
                     [DonationMetaKeys::FORM_ID(), 'formId']
                 )
                 ->where('post_type', 'give_payment')
+                ->offset($batchNumber)
+                ->limit($this->getBatchSize())
                 ->getAll();
 
             $donationMeta = [];
@@ -86,7 +89,26 @@ public function run()
                     ->insert($donationMeta, ['%d', '%s', '%d']);
             }
         } catch (DatabaseQueryException $exception) {
-            throw new DatabaseMigrationException("An error occurred while adding campaign ID to the donation meta table", 0, $exception);
+            throw new DatabaseMigrationException("An error occurred while adding campaign ID to the donation meta table",
+                0, $exception);
         }
     }
+
+    /**
+     * @inheritDoc
+     */
+    public function getItemsCount(): int
+    {
+        return DB::table('posts')
+            ->where('post_type', 'give_payment')
+            ->count();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBatchSize(): int
+    {
+        return 50;
+    }
 }

src/Framework/Migrations/Contracts/BatchMigration.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Give\Framework\Migrations\Contracts;
+
+/**
+ * @unreleased
+ */
+interface BatchMigration
+{
+    /**
+     * @unreleased
+     *
+     * Get the number of items per batch
+     */
+    public function getBatchSize(): int;
+
+    /**
+     * @unreleased
+     *
+     * Get the total items count
+     */
+    public function getItemsCount(): int;
+
+    /**
+     * @unreleased
+     *
+     * Run batch
+     */
+    public function runBatch($batchNumber);
+}

src/Framework/Migrations/Contracts/Migration.php

@@ -16,9 +16,15 @@ abstract class Migration
     /**
      * Bootstrap migration logic.
      *
+     * @unreleased this method is now optional if migration class implements BatchMigration interface
      * @since 2.9.0
      */
-    abstract public function run();
+    public function run()
+    {
+        if ( ! is_subclass_of($this, BatchMigration::class)) {
+            throw new RuntimeException('run method is not defined.');
+        }
+    }
 
     /**
      * Return a unique identifier for the migration

src/Framework/Migrations/MigrationsRunner.php

@@ -3,8 +3,11 @@
 namespace Give\Framework\Migrations;
 
 use Exception;
+use Give\Framework\Database\DB;
 use Give\Framework\Database\Exceptions\DatabaseQueryException;
+use Give\Framework\Migrations\Contracts\BatchMigration;
 use Give\Framework\Migrations\Contracts\Migration;
+use Give\Framework\Support\Facades\ActionScheduler\AsBackgroundJobs;
 use Give\Log\Log;
 use Give\MigrationLog\MigrationLogFactory;
 use Give\MigrationLog\MigrationLogRepository;
@@ -67,12 +70,11 @@ public function __construct(
     /**
      * Run database migrations.
      *
-     * @since 2.9.0
+     * @unreleased add support for batch processing
+     * @since      2.9.0
      */
     public function run()
     {
-        global $wpdb;
-
         if ( ! $this->hasMigrationToRun()) {
             return;
         }
@@ -94,7 +96,7 @@ public function run()
 
         ksort($migrations);
 
-        foreach ($migrations as $key => $migrationClass) {
+        foreach ($migrations as $migrationClass) {
             $migrationId = $migrationClass::id();
 
             if (in_array($migrationId, $this->completedMigrations, true)) {
@@ -103,19 +105,30 @@ public function run()
 
             $migrationLog = $this->migrationLogFactory->make($migrationId);
 
-            // Begin transaction
-            $wpdb->query('START TRANSACTION');
-
             try {
                 /** @var Migration $migration */
                 $migration = give($migrationClass);
 
-                $migration->run();
-
-                // Save migration status
-                $migrationLog->setStatus(MigrationLogStatus::SUCCESS);
+                if (is_subclass_of($migration, BatchMigration::class)) {
+                    $status = $this->runBatch($migration);
+
+                    if ($status === MigrationLogStatus::RUNNING) {
+                        give()->notices->register_notice(
+                            [
+                                'id' => $migrationId,
+                                'description' => esc_html__('Running DB migration: ' . $migration::title(), 'give'),
+                            ]
+                        );
+                        break;
+                    }
+
+                    $migrationLog->setStatus($status);
+                } else {
+                    $migration->run();
+                    $migrationLog->setStatus(MigrationLogStatus::SUCCESS);
+                }
             } catch (Exception $exception) {
-                $wpdb->query('ROLLBACK');
+                DB::rollback();
 
                 $migrationLog->setStatus(MigrationLogStatus::FAILED);
                 $migrationLog->setError($exception);
@@ -152,7 +165,7 @@ public function run()
             }
 
             // Commit transaction if successful
-            $wpdb->query('COMMIT');
+            DB::commit();
         }
     }
 
@@ -167,4 +180,59 @@ public function hasMigrationToRun()
     {
         return (bool)array_diff($this->migrationRegister->getRegisteredIds(), $this->completedMigrations);
     }
+
+    /**
+     * Run migration batch
+     *
+     * @unreleased
+     * @throws Exception
+     */
+    public function runBatch(BatchMigration $migration): string
+    {
+        $group = $migration::id();
+        $actionHook = 'givewp-batch-' . $group;
+
+        add_action($actionHook, function ($batchNumber) use ($migration) {
+            DB::beginTransaction();
+
+            try {
+                $migration->runBatch($batchNumber);
+
+                DB::commit();
+            } catch (Exception $e) {
+                DB::rollback();
+                throw new Exception($e->getMessage(), 0, $e);
+            }
+        });
+
+        $actions = AsBackgroundJobs::getActionsByGroup($group);
+
+        // register actions - initial run
+        if (empty($actions)) {
+            $batches = ceil($migration->getItemsCount() / $migration->getBatchSize());
+
+            for ($i = 0; $i < $batches; $i++) {
+                AsBackgroundJobs::enqueueAsyncAction($actionHook, [$i], $group);
+            }
+
+            return MigrationLogStatus::RUNNING;
+        }
+
+        $pendingActions = AsBackgroundJobs::getActionsByGroup($group, 'pending');
+
+        if ( ! empty($pendingActions)) {
+            return MigrationLogStatus::RUNNING;
+        }
+
+        $failedActions = AsBackgroundJobs::getActionsByGroup($group, 'failed');
+
+        if ( ! empty($failedActions)) {
+            return MigrationLogStatus::FAILED;
+        }
+
+        // todo: discuss deleting actions
+        // AsBackgroundJobs::deleteActionsByGroup($group);
+
+        return MigrationLogStatus::SUCCESS;
+    }
 }

src/Framework/Migrations/MigrationsServiceProvider.php

@@ -30,6 +30,8 @@ public function boot()
     {
         Hooks::addAction('admin_init', ManualMigration::class, '__invoke', 0);
         Hooks::addAction('admin_init', MigrationsRunner::class, 'run', 0);
-        Hooks::addAction('give_upgrades', MigrationsRunner::class, 'run', 0);
+        //Hooks::addAction('give_upgrades', MigrationsRunner::class, 'run', 0);
+        // running batch actions via cron doesn't trigger give_upgrades and all registered actions fail
+        Hooks::addAction('action_scheduler_init', MigrationsRunner::class, 'run');
     }
 }

src/Framework/Support/Facades/ActionScheduler/AsBackgroundJobs.php

@@ -7,9 +7,14 @@
 /**
  * @since 3.6.0
  *
+ * @unreleased
+ *  - added enqueueAction method
+ *  - switch parameter $status position with $returnFormat position
+ *
  * @method static int enqueueAsyncAction(string $hook, array $args, string $group, bool $unique = false, int $priority = 10)
+ * @method static int enqueueAction(int $timestamp, string $hook, array $args, string $group, bool $unique = false, int $priority = 10)
  * @method static array getActionByHookArgsGroup(string $hook, array $args, string $group, string $returnFormat = OBJECT, string $status = '')
- * @method static array getActionsByGroup(string $group, string $returnFormat = OBJECT, string $status = '')
+ * @method static array getActionsByGroup(string $group, string $status = '', string $returnFormat = OBJECT)
  * @method static int deleteActionsByGroup(string $group, string $status = '')
  */
 class AsBackgroundJobs extends Facade

src/Framework/Support/Facades/ActionScheduler/AsBackgroundJobsFacade.php

@@ -42,6 +42,25 @@ public function enqueueAsyncAction(
         }
     }
 
+    /**
+     * @unreleased
+     */
+    public function enqueueAction(
+        int $timestamp,
+        string $hook,
+        array $args,
+        string $group,
+        bool $unique = false,
+        int $priority = 10
+    ): int {
+        $enqueuedAction = $this->getActionByHookArgsGroup($hook, $args, $group, 'ids');
+        if (empty($enqueuedAction)) {
+            return as_schedule_single_action($timestamp, $hook, $args, $group, $unique, $priority);
+        }
+
+        return $enqueuedAction[0];
+    }
+
     /**
      * @since 3.6.0
      *
@@ -76,14 +95,15 @@ public function getActionByHookArgsGroup(
 
     /**
      * @since 3.6.0
+     * @unreleased - switch parameter $status position with $returnFormat position
      *
      * @param string $group        The group to assign this job to.
      * @param string $returnFormat OBJECT, ARRAY_A, or ids.
      * @param string $status ActionScheduler_Store::STATUS_COMPLETE or ActionScheduler_Store::STATUS_PENDING
      *
      * @return array
      */
-    public function getActionsByGroup(string $group, string $returnFormat = OBJECT, string $status = ''): array
+    public function getActionsByGroup(string $group, string $status = '', string $returnFormat = OBJECT): array
     {
         $args = [
             'group' => $group,

src/MigrationLog/MigrationLogStatus.php

@@ -6,13 +6,15 @@
  * Class MigrationLogStatus
  * @package Give\MigrationLog
  *
+ * @unreleased add running status
  * @since 2.10.0
  */
 class MigrationLogStatus
 {
     const SUCCESS = 'success';
     const FAILED = 'failed';
     const PENDING = 'pending';
+    const RUNNING = 'running';
 
     /**
      * Get default migration status
@@ -35,6 +37,7 @@ public static function getAll()
             MigrationLogStatus::SUCCESS => esc_html__('Success', 'give'),
             MigrationLogStatus::FAILED => esc_html__('Failed', 'give'),
             MigrationLogStatus::PENDING => esc_html__('Pending', 'give'),
+            MigrationLogStatus::RUNNING => esc_html__('Running', 'give'),
         ];
     }