feat(php): implement BGSAVE, BGSAVE SCHEDULE, and BGSAVE CANCEL commands

CHANGELOG.md

@@ -4,7 +4,9 @@
 
 ### Changes
 
+* PHP: Add `BGSAVE`, `BGSAVE SCHEDULE`, and `BGSAVE CANCEL` commands for standalone and cluster clients ([#236](https://github.com/valkey-io/valkey-glide-php/issues/236))
 * PHP: Fix pie install from Packagist using PIE pre-packaged-source download method ([#233](https://github.com/valkey-io/valkey-glide-php/pull/233))
+* PHP: Fix pie install from Packagist by setting preferred-install to source for submodule resolution ([#232](https://github.com/valkey-io/valkey-glide-php/pull/232))
 * PHP: Fix pie install ([#229](https://github.com/valkey-io/valkey-glide-php/pull/229))
 * PHP: Set CLIENT SETINFO lib-name=GlidePHP and lib-ver to extension version for proper client identification
 * PHP: Add address resolver support for standalone and cluster clients, allowing custom host/port remapping at connection time ([#196](https://github.com/valkey-io/valkey-glide-php/pull/196))

tests/ValkeyGlideBaseTest.php

@@ -323,4 +323,23 @@ protected function skipIfDnsNotEnabled(): void
             $this->markTestSkipped('DNS tests are disabled. Set VALKEY_GLIDE_DNS_TESTS_ENABLED=1 to enable.');
         }
     }
+
+    /**
+     * Waits until the given condition callback returns true, polling every 100ms.
+     *
+     * @param callable $condition  A callback that returns true when the condition is met.
+     * @param int      $timeoutSeconds  Maximum time to wait in seconds.
+     * @param string   $message  Failure message if timeout is reached.
+     */
+    protected function waitFor(callable $condition, int $timeoutSeconds = 10, string $message = 'waitFor timed out'): void
+    {
+        $start = time();
+        while (time() - $start < $timeoutSeconds) {
+            if ($condition()) {
+                return;
+            }
+            usleep(100000); // 100ms
+        }
+        $this->fail($message);
+    }
 }

tests/ValkeyGlideClusterTest.php

@@ -406,6 +406,178 @@ public function testFlushAll()
         }
     }
 
+    /**
+     * Override for cluster - info() requires a route parameter and checks all primaries.
+     */
+    protected function isSaveInProgress(): bool
+    {
+        $info = $this->valkey_glide->info('allPrimaries', 'persistence');
+        foreach ($info as $nodeInfo) {
+            if (
+                $nodeInfo['rdb_bgsave_in_progress'] == '1'
+                || $nodeInfo['aof_rewrite_in_progress'] == '1'
+            ) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    public function testBgSave()
+    {
+        $this->waitForSaveNotInProgress();
+
+        // Test with allPrimaries route - returns array of node => bool
+        $result = $this->valkey_glide->bgSave('allPrimaries');
+        $this->assertIsArray($result);
+        $this->assertGT(0, count($result));
+        foreach ($result as $nodeAddress => $nodeResult) {
+            $this->assertIsString($nodeAddress);
+            $this->assertStringContains(':', $nodeAddress);
+            $this->assertTrue($nodeResult);
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        // Test with randomNode route - returns scalar bool
+        $result = $this->valkey_glide->bgSave('randomNode');
+        $this->assertTrue($result);
+    }
+
+    public function testBgSaveSchedule()
+    {
+        $this->waitForSaveNotInProgress();
+
+        // Test with allPrimaries route - returns array of node => bool
+        $result = $this->valkey_glide->bgSave('allPrimaries', 'SCHEDULE');
+        $this->assertIsArray($result);
+        $this->assertGT(0, count($result));
+        foreach ($result as $nodeAddress => $nodeResult) {
+            $this->assertIsString($nodeAddress);
+            $this->assertStringContains(':', $nodeAddress);
+            $this->assertTrue($nodeResult);
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        // Test with randomNode route - returns scalar bool
+        $result = $this->valkey_glide->bgSave('randomNode', 'SCHEDULE');
+        $this->assertTrue($result);
+    }
+
+    public function testBgSaveCancel()
+    {
+        if (!$this->minVersionCheck('8.1.0')) {
+            $this->markTestSkipped('BGSAVE CANCEL requires Valkey 8.1.0+');
+            return;
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        // When no save is in progress, CANCEL returns false (not an array) even for
+        // multi-node routes. This is because the glide-core's response aggregation
+        // checks all node responses for errors before building the Map result. When
+        // ALL nodes return a ServerError (no save in progress), the core collapses
+        // them into a single command_error rather than returning a per-node Map.
+        // This matches PHPRedis semantics where bgSave() returns false on failure.
+        // A successful CANCEL (when a save IS in progress) would return an array
+        // for multi-node routes since at least one node returns a success response.
+        $result = $this->valkey_glide->bgSave('allPrimaries', 'CANCEL');
+        $this->assertFalse($result);
+
+        $result = $this->valkey_glide->bgSave('randomNode', 'CANCEL');
+        $this->assertFalse($result);
+    }
+
+    public function testBgSaveWithReplyLiteral()
+    {
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->setOption(ValkeyGlide::OPT_REPLY_LITERAL, true);
+
+        // Test with allPrimaries route - returns array of node => string
+        $result = $this->valkey_glide->bgSave('allPrimaries');
+        $this->assertIsArray($result);
+        foreach ($result as $nodeResult) {
+            $this->assertIsString($nodeResult);
+            $this->assertContains($nodeResult, $this->bgsaveResponses());
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        // Test with randomNode route - returns scalar string
+        $result = $this->valkey_glide->bgSave('randomNode');
+        $this->assertIsString($result);
+        $this->assertContains($result, $this->bgsaveResponses());
+
+        $this->waitForSaveNotInProgress();
+
+        // Test SCHEDULE with allPrimaries route - returns array of node => string
+        $result = $this->valkey_glide->bgSave('allPrimaries', 'SCHEDULE');
+        $this->assertIsArray($result);
+        foreach ($result as $nodeResult) {
+            $this->assertIsString($nodeResult);
+            $this->assertContains($nodeResult, $this->bgsaveResponses());
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        // Test SCHEDULE with randomNode route - returns scalar string
+        $result = $this->valkey_glide->bgSave('randomNode', 'SCHEDULE');
+        $this->assertIsString($result);
+        $this->assertContains($result, $this->bgsaveResponses());
+
+        if ($this->minVersionCheck('8.1.0')) {
+            $this->waitForSaveNotInProgress();
+
+            // CANCEL with no save in progress returns false (see testBgSaveCancel comment)
+            $result = $this->valkey_glide->bgSave('allPrimaries', 'CANCEL');
+            $this->assertFalse($result);
+
+            $result = $this->valkey_glide->bgSave('randomNode', 'CANCEL');
+            $this->assertFalse($result);
+        }
+
+        $this->valkey_glide->setOption(ValkeyGlide::OPT_REPLY_LITERAL, false);
+    }
+
+    public function testBgSaveBatch()
+    {
+        if (!$this->havePipeline()) {
+            $this->markTestSkipped('Pipeline not supported');
+            return;
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->pipeline();
+        $this->valkey_glide->bgSave('allPrimaries');
+        $result = $this->valkey_glide->exec();
+        $this->assertIsArray($result[0]);
+        foreach ($result[0] as $nodeResult) {
+            $this->assertTrue($nodeResult);
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->pipeline();
+        $this->valkey_glide->bgSave('allPrimaries', 'SCHEDULE');
+        $result = $this->valkey_glide->exec();
+        $this->assertIsArray($result[0]);
+        foreach ($result[0] as $nodeResult) {
+            $this->assertTrue($nodeResult);
+        }
+
+        if ($this->minVersionCheck('8.1.0')) {
+            $this->waitForSaveNotInProgress();
+
+            $this->valkey_glide->pipeline();
+            $this->valkey_glide->bgSave('allPrimaries', 'CANCEL');
+            $result = $this->valkey_glide->exec();
+            $this->assertFalse($result[0]);
+        }
+    }
+
     public function testInfo()
     {
         $fields = [

tests/ValkeyGlideTest.php

@@ -2585,6 +2585,125 @@ public function testFlushAll()
         $this->assertEquals(0, $this->valkey_glide->dbSize());
     }
 
+    public function testBgSave()
+    {
+        $this->waitForSaveNotInProgress();
+
+        $result = $this->valkey_glide->bgSave();
+        $this->assertTrue($result);
+    }
+
+    public function testBgSaveSchedule()
+    {
+        $this->waitForSaveNotInProgress();
+
+        $result = $this->valkey_glide->bgSave('SCHEDULE');
+        $this->assertTrue($result);
+    }
+
+    public function testBgSaveCancel()
+    {
+        if (!$this->minVersionCheck('8.1.0')) {
+            $this->markTestSkipped('BGSAVE CANCEL requires Valkey 8.1.0+');
+            return;
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        $result = $this->valkey_glide->bgSave('CANCEL');
+        $this->assertFalse($result);
+    }
+
+    public function testBgSaveWithReplyLiteral()
+    {
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->setOption(ValkeyGlide::OPT_REPLY_LITERAL, true);
+
+        $result = $this->valkey_glide->bgSave();
+        $this->assertIsString($result);
+        $this->assertContains($result, $this->bgsaveResponses());
+
+        $this->waitForSaveNotInProgress();
+
+        $result = $this->valkey_glide->bgSave('SCHEDULE');
+        $this->assertIsString($result);
+        $this->assertContains($result, $this->bgsaveResponses());
+
+        if ($this->minVersionCheck('8.1.0')) {
+            $this->waitForSaveNotInProgress();
+
+            $result = $this->valkey_glide->bgSave('CANCEL');
+            $this->assertFalse($result);
+        }
+
+        $this->valkey_glide->setOption(ValkeyGlide::OPT_REPLY_LITERAL, false);
+    }
+
+    public function testBgSaveBatch()
+    {
+        if (!$this->havePipeline()) {
+            $this->markTestSkipped('Pipeline not supported');
+            return;
+        }
+
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->pipeline();
+        $this->valkey_glide->bgSave();
+        $result = $this->valkey_glide->exec();
+        $this->assertTrue($result[0]);
+
+        $this->waitForSaveNotInProgress();
+
+        $this->valkey_glide->pipeline();
+        $this->valkey_glide->bgSave('SCHEDULE');
+        $result = $this->valkey_glide->exec();
+        $this->assertTrue($result[0]);
+
+        if ($this->minVersionCheck('8.1.0')) {
+            $this->waitForSaveNotInProgress();
+
+            $this->valkey_glide->pipeline();
+            $this->valkey_glide->bgSave('CANCEL');
+            $result = $this->valkey_glide->exec();
+            $this->assertFalse($result[0]);
+        }
+    }
+
+    /**
+     * Valid BGSAVE response strings (used when OPT_REPLY_LITERAL is enabled).
+     */
+    protected function bgsaveResponses(): array
+    {
+        return [
+            'Background saving started',
+            'Background saving scheduled',
+        ];
+    }
+
+    /**
+     * Returns true if a background save (RDB or AOF) is currently in progress.
+     */
+    protected function isSaveInProgress(): bool
+    {
+        $info = $this->valkey_glide->info('persistence');
+        return $info['rdb_bgsave_in_progress'] == '1'
+            || $info['aof_rewrite_in_progress'] == '1';
+    }
+
+    /**
+     * Helper method to wait for any background save operations to complete.
+     */
+    protected function waitForSaveNotInProgress()
+    {
+        $this->waitFor(
+            fn() => !$this->isSaveInProgress(),
+            10,
+            'Timed out waiting for background save to complete'
+        );
+    }
+
     public function testTTL()
     {
         $this->valkey_glide->set('x', 'y');

valkey_glide.stub.php

@@ -1153,6 +1153,22 @@ public function flushAll(?bool $sync = null): ValkeyGlide|bool;
      */
     public function flushDB(?bool $sync = null): ValkeyGlide|bool;
 
+    /**
+     * Asynchronously saves the dataset to disk in the background.
+     *
+     * When called without a mode argument, initiates a background save immediately.
+     * When called with "SCHEDULE", schedules a background save to run when possible.
+     * When called with "CANCEL", aborts all in-progress and scheduled background saves (Valkey 8.1+).
+     *
+     * @param  string|null  $mode  Optional mode: null for default, "SCHEDULE" to schedule,
+     *                             or "CANCEL" to abort (requires Valkey 8.1+).
+     * @return ValkeyGlide|bool|string  Returns true on success, false on failure.
+     *                                  With OPT_REPLY_LITERAL enabled, returns the status string instead.
+     *
+     * @see https://valkey.io/commands/bgsave
+     */
+    public function bgSave(?string $mode = null): ValkeyGlide|bool|string;
+
     /**
      * Functions is an API for managing code to be executed on the server.
      *

valkey_glide_cluster.c

@@ -977,6 +977,11 @@ FLUSHDB_METHOD_IMPL(ValkeyGlideCluster)
 FLUSHALL_METHOD_IMPL(ValkeyGlideCluster)
 /* }}} */
 
+/* {{{ proto ValkeyGlideCluster::bgSave(mixed route, [string mode])
+ *     Asynchronously saves the dataset to disk in the background. */
+BGSAVE_METHOD_IMPL(ValkeyGlideCluster)
+/* }}} */
+
 /* {{{ proto ValkeyGlideCluster::dbsize(string key)
  *     proto ValkeyGlideCluster::dbsize(array host_port) */
 DBSIZE_METHOD_IMPL(ValkeyGlideCluster)