feat(storage): add samples for soft delete (objects)

storage/src/disable_soft_delete.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_disable_soft_delete]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Disable bucket's soft delete.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function disable_soft_delete(string $bucketName): void
+{
+    try {
+        $storage = new StorageClient();
+        $bucket = $storage->bucket($bucketName);
+        $x = $bucket->update([
+            'softDeletePolicy' => [
+                'retentionDurationSeconds' => 0,
+            ],
+        ]);
+        printf('Bucket %s soft delete policy was disabled' . PHP_EOL, $bucketName);
+    } catch (\Throwable $th) {
+        print_r($th);
+    }
+
+}
+# [END storage_disable_soft_delete]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/get_soft_delete_policy.php

@@ -0,0 +1,56 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_get_soft_delete_policy]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Gets a bucket soft delete policy.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function get_soft_delete_policy(string $bucketName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $bucket->reload();
+
+    if ($bucket->info()['softDeletePolicy']['retentionDurationSeconds'] === '0') {
+        printf('Bucket %s soft delete policy was disabled' . PHP_EOL, $bucketName);
+    } else {
+        printf('Soft delete Policy for ' . $bucketName . PHP_EOL);
+        printf('Soft delete Period: %d seconds' . PHP_EOL, $bucket->info()['softDeletePolicy']['retentionDurationSeconds']);
+        if ($bucket->info()['softDeletePolicy']['effectiveTime']) {
+            printf('Effective Time: ' . $bucket->info()['softDeletePolicy']['effectiveTime'] . PHP_EOL);
+        }
+    }
+
+}
+# [END storage_get_soft_delete_policy]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/list_soft_deleted_object_versions.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_list_soft_deleted_object_versions]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * List Cloud Storage bucket soft deleted objects.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $objectName The name of your Cloud Storage object.
+ *        (e.g. 'my-object')
+ */
+function list_soft_deleted_object_versions(string $bucketName, string $objectName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $options = ['softDeleted' => true, 'matchGlob' => $objectName];
+    foreach ($bucket->objects($options) as $object) {
+        printf('Object: %s' . PHP_EOL, $object->name());
+    }
+}
+# [END storage_list_soft_deleted_object_versions]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/list_soft_deleted_objects.php

@@ -0,0 +1,48 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_list_soft_deleted_objects]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * List Cloud Storage bucket soft deleted object versions.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function list_soft_deleted_objects(string $bucketName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $options = ['softDeleted' => true];
+    foreach ($bucket->objects($options) as $object) {
+        printf('Object: %s' . PHP_EOL, $object->name());
+    }
+}
+# [END storage_list_soft_deleted_objects]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/restore_soft_deleted_object.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_restore_object]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Restore softDeleted objects.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $objectName The name of your Cloud Storage object.
+ *        (e.g. 'my-object')
+ * @param string $generation The generation of the bucket to restore.
+ *        (e.g. '123456789')
+ */
+function restore_soft_deleted_object(string $bucketName, string $objectName, string $generation): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $bucket->restore($objectName, $generation);
+
+    printf('Soft deleted object %s was restored.' . PHP_EOL, $objectName);
+}
+# [END storage_restore_object]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/src/set_soft_delete_policy.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * Copyright 2025 Google Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * For instructions on how to run the full sample:
+ *
+ * @see https://github.com/GoogleCloudPlatform/php-docs-samples/tree/main/storage/README.md
+ */
+
+namespace Google\Cloud\Samples\Storage;
+
+# [START storage_set_soft_delete_policy]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Sets a bucket's soft delete policy.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function set_soft_delete_policy(string $bucketName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $bucket->update([
+        'softDeletePolicy' => [
+            'retentionDurationSeconds' => 864000,
+        ],
+    ]);
+    printf('Bucket %s soft delete policy set to 10 days' . PHP_EOL, $bucketName);
+}
+# [END storage_set_soft_delete_policy]
+
+// The following 2 lines are only needed to run the samples
+require_once __DIR__ . '/../../testing/sample_helpers.php';
+\Google\Cloud\Samples\execute_sample(__FILE__, __NAMESPACE__, $argv);

storage/test/ObjectsTest.php

@@ -410,4 +410,83 @@ public function testGetMetadata()
         $this->assertStringNotContainsString('Custom Time', $output);
         $this->assertStringNotContainsString('Retention Expiration Time', $output);
     }
+
+    public function testListSoftDeletedObjects()
+    {
+        $bucket = self::$storage->bucket(self::$bucketName);
+        $bucket->update([
+            'softDeletePolicy' => [
+                'retentionDuration' => '604800s',
+            ],
+        ]);
+
+        $objectName = uniqid('soft-deleted-object-');
+        $object = $bucket->upload('content', ['name' => $objectName]);
+        $object->delete();
+
+        $output = self::runFunctionSnippet('list_soft_deleted_objects', [
+            self::$bucketName,
+        ]);
+
+        $this->assertStringContainsString('Object:', $output);
+    }
+
+    public function testListSoftDeletedObjectVersions()
+    {
+        $bucket = self::$storage->bucket(self::$bucketName);
+        $bucket->update([
+            'softDeletePolicy' => [
+                'retentionDuration' => '604800s',
+            ],
+        ]);
+
+        $objectName1 = 'soft-deleted-object-1';
+        $object1 = $bucket->upload('content', ['name' => $objectName1]);
+        $object1->delete();
+
+        $objectName2 = 'soft-deleted-object-2';
+        $object2 = $bucket->upload('content', ['name' => $objectName2]);
+        $object2->delete();
+
+        $output = self::runFunctionSnippet('list_soft_deleted_object_versions', [
+            self::$bucketName,
+            $objectName1
+        ]);
+
+        $this->assertStringContainsString($objectName1, $output);
+        $this->assertStringNotContainsString($objectName2, $output);
+    }
+
+    public function testRestoreSoftDeletedObject()
+    {
+        $bucket = self::$storage->bucket(self::$bucketName);
+        $bucket->update([
+            'softDeletePolicy' => [
+                'retentionDuration' => '60s',
+            ],
+        ]);
+
+        $objectName = uniqid('soft-deleted-object-');
+        $object = $bucket->upload('content', ['name' => $objectName]);
+        $info = $object->reload();
+        $object->delete();
+
+        $this->assertFalse($object->exists());
+
+        $output = self::runFunctionSnippet('restore_soft_deleted_object', [
+            self::$bucketName,
+            $objectName,
+            $info['generation']
+        ]);
+
+        $object = $bucket->object($objectName);
+        $this->assertTrue($object->exists());
+        $this->assertEquals(
+            sprintf(
+                'Soft deleted object %s was restored.' . PHP_EOL,
+                $objectName
+            ),
+            $output
+        );
+    }
 }