feat(storagecontrol): add Rapid Cache samples

storagecontrol/composer.json

@@ -1,6 +1,6 @@
 {
     "require": {
-        "google/cloud-storage-control": "^1.9"
+        "google/cloud-storage-control": "^1.12"
     },
     "require-dev": {
         "google/cloud-storage": "^1.48.1"

storagecontrol/src/create_rapid_cache.php

@@ -0,0 +1,86 @@
+<?php
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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/storagecontrol/README.md
+ */
+
+namespace Google\Cloud\Samples\StorageControl;
+
+# [START storage_control_create_rapid_cache]
+use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
+use Google\Cloud\Storage\Control\V2\CreateRapidCacheRequest;
+use Google\Cloud\Storage\Control\V2\RapidCache;
+use Google\Protobuf\Duration;
+
+/**
+ * Creates a Rapid Cache instance.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $zone The zone in which to create the Rapid Cache. The zone
+ *        must be in the same region as the bucket.
+ *        (e.g. 'us-central1-a')
+ */
+function create_rapid_cache(string $bucketName, string $zone): void
+{
+    $storageControlClient = new StorageControlClient();
+
+    // Set project to "_" to signify global bucket
+    $formattedParent = $storageControlClient->bucketName('_', $bucketName);
+
+    // The Rapid Cache ID must be the same as the zone.
+    $formattedName = $storageControlClient->rapidCacheName('_', $bucketName, $zone);
+
+    // Rapid Cache Ultra requires a bucket with hierarchical namespace enabled.
+    $rapidCache = new RapidCache([
+        'name' => $formattedName,
+        'zone' => $zone,
+        'cache_type' => 'rapid-cache-ultra',
+        // Time to live (TTL) for cache entries: 86400 seconds (24 hours).
+        'ttl' => new Duration(['seconds' => 86400]),
+    ]);
+
+    $request = new CreateRapidCacheRequest([
+        'parent' => $formattedParent,
+        'rapid_cache' => $rapidCache,
+    ]);
+
+    // Creating a Rapid Cache is a long-running operation. This sample blocks
+    // until it completes. A totalPollTimeoutMillis of 0 waits with no time
+    // limit, instead of the client library default of 5 minutes.
+    $operation = $storageControlClient->createRapidCache($request);
+    $operation->pollUntilComplete(['totalPollTimeoutMillis' => 0]);
+
+    if (!$operation->operationSucceeded()) {
+        printf('Error: %s' . PHP_EOL, $operation->getError()->getMessage());
+        return;
+    }
+
+    /** @var RapidCache $rapidCacheResult */
+    $rapidCacheResult = $operation->getResult();
+    printf('Created Rapid Cache: %s' . PHP_EOL, $rapidCacheResult->getName());
+    printf('State: %s' . PHP_EOL, $rapidCacheResult->getState());
+}
+# [END storage_control_create_rapid_cache]
+
+// 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);

storagecontrol/src/disable_rapid_cache.php

@@ -0,0 +1,80 @@
+<?php
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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/storagecontrol/README.md
+ */
+
+namespace Google\Cloud\Samples\StorageControl;
+
+# [START storage_control_disable_rapid_cache]
+use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
+use Google\Cloud\Storage\Control\V2\DisableRapidCacheRequest;
+use Google\Cloud\Storage\Control\V2\RapidCache;
+
+/**
+ * Disables a Rapid Cache instance.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $rapidCacheId The ID of the Rapid Cache.
+ *        (e.g. 'us-central1-a')
+ * @param int $timeoutMillis Optional. The maximum time to wait for the
+ *        operation to complete, in milliseconds. 0 waits until it completes.
+ *        (e.g. 600000 for 10 minutes)
+ */
+function disable_rapid_cache(string $bucketName, string $rapidCacheId, int $timeoutMillis = 0): void
+{
+    $storageControlClient = new StorageControlClient();
+
+    // Set project to "_" to signify global bucket
+    $formattedName = $storageControlClient->rapidCacheName('_', $bucketName, $rapidCacheId);
+
+    $request = new DisableRapidCacheRequest([
+        'name' => $formattedName,
+    ]);
+
+    // Disabling a Rapid Cache is a long-running operation. This sample waits
+    // for the long-running operation to complete. A totalPollTimeoutMillis of
+    // 0 waits with no time limit.
+    $operation = $storageControlClient->disableRapidCache($request);
+    $completed = $operation->pollUntilComplete([
+        'totalPollTimeoutMillis' => $timeoutMillis,
+    ]);
+
+    if (!$completed) {
+        printf('Disable operation is still running: %s' . PHP_EOL, $operation->getName());
+        return;
+    }
+
+    if (!$operation->operationSucceeded()) {
+        printf('Error: %s' . PHP_EOL, $operation->getError()->getMessage());
+        return;
+    }
+
+    /** @var RapidCache $rapidCacheResult */
+    $rapidCacheResult = $operation->getResult();
+    printf('Disabled Rapid Cache: %s' . PHP_EOL, $rapidCacheResult->getName());
+}
+# [END storage_control_disable_rapid_cache]
+
+// 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);

storagecontrol/src/get_rapid_cache.php

@@ -0,0 +1,61 @@
+<?php
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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/storagecontrol/README.md
+ */
+
+namespace Google\Cloud\Samples\StorageControl;
+
+# [START storage_control_get_rapid_cache]
+use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
+use Google\Cloud\Storage\Control\V2\GetRapidCacheRequest;
+
+/**
+ * Gets a Rapid Cache instance.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $rapidCacheId The ID of the Rapid Cache.
+ *        (e.g. 'us-central1-a')
+ */
+function get_rapid_cache(string $bucketName, string $rapidCacheId): void
+{
+    $storageControlClient = new StorageControlClient();
+
+    // Set project to "_" to signify global bucket
+    $formattedName = $storageControlClient->rapidCacheName('_', $bucketName, $rapidCacheId);
+
+    $request = new GetRapidCacheRequest([
+        'name' => $formattedName,
+    ]);
+
+    $response = $storageControlClient->getRapidCache($request);
+
+    printf('Got Rapid Cache: %s' . PHP_EOL, $response->getName());
+    printf('Zone: %s' . PHP_EOL, $response->getZone());
+    printf('Cache type: %s' . PHP_EOL, $response->getCacheType());
+    printf('State: %s' . PHP_EOL, $response->getState());
+}
+# [END storage_control_get_rapid_cache]
+
+// 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);

storagecontrol/src/list_rapid_caches.php

@@ -0,0 +1,59 @@
+<?php
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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/storagecontrol/README.md
+ */
+
+namespace Google\Cloud\Samples\StorageControl;
+
+# [START storage_control_list_rapid_caches]
+use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
+use Google\Cloud\Storage\Control\V2\ListRapidCachesRequest;
+
+/**
+ * Lists Rapid Cache instances for a given bucket.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function list_rapid_caches(string $bucketName): void
+{
+    $storageControlClient = new StorageControlClient();
+
+    // Set project to "_" to signify global bucket
+    $formattedName = $storageControlClient->bucketName('_', $bucketName);
+
+    $request = new ListRapidCachesRequest([
+        'parent' => $formattedName,
+    ]);
+
+    $response = $storageControlClient->listRapidCaches($request);
+
+    // The iterator handles pagination automatically.
+    foreach ($response as $rapidCache) {
+        printf('Rapid Cache name: %s' . PHP_EOL, $rapidCache->getName());
+    }
+}
+# [END storage_control_list_rapid_caches]
+
+// 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);

storagecontrol/src/update_rapid_cache.php

@@ -0,0 +1,87 @@
+<?php
+
+/**
+ * Copyright 2026 Google LLC
+ *
+ * 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/storagecontrol/README.md
+ */
+
+namespace Google\Cloud\Samples\StorageControl;
+
+# [START storage_control_update_rapid_cache]
+use Google\Cloud\Storage\Control\V2\Client\StorageControlClient;
+use Google\Cloud\Storage\Control\V2\RapidCache;
+use Google\Cloud\Storage\Control\V2\UpdateRapidCacheRequest;
+use Google\Protobuf\Duration;
+use Google\Protobuf\FieldMask;
+
+/**
+ * Updates the time to live (TTL) of a Rapid Cache instance.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ * @param string $rapidCacheId The ID of the Rapid Cache.
+ *        (e.g. 'us-central1-a')
+ * @param int $ttlSeconds The new TTL for cache entries, in seconds. The TTL
+ *        must be between 1 hour and 7 days.
+ *        (e.g. 172800 for 2 days)
+ */
+function update_rapid_cache(string $bucketName, string $rapidCacheId, int $ttlSeconds): void
+{
+    $storageControlClient = new StorageControlClient();
+
+    // Set project to "_" to signify global bucket
+    $formattedName = $storageControlClient->rapidCacheName('_', $bucketName, $rapidCacheId);
+
+    $rapidCache = new RapidCache([
+        'name' => $formattedName,
+        'ttl' => new Duration(['seconds' => $ttlSeconds]),
+    ]);
+
+    // Only the fields listed in the update mask are changed.
+    $updateMask = new FieldMask([
+        'paths' => ['ttl'],
+    ]);
+
+    $request = new UpdateRapidCacheRequest([
+        'rapid_cache' => $rapidCache,
+        'update_mask' => $updateMask,
+    ]);
+
+    // Updating a Rapid Cache is a long-running operation. This sample blocks
+    // until it completes. A totalPollTimeoutMillis of 0 waits with no time
+    // limit, instead of the client library default of 5 minutes.
+    $operation = $storageControlClient->updateRapidCache($request);
+    $operation->pollUntilComplete(['totalPollTimeoutMillis' => 0]);
+
+    if (!$operation->operationSucceeded()) {
+        printf('Error: %s' . PHP_EOL, $operation->getError()->getMessage());
+        return;
+    }
+
+    /** @var RapidCache $rapidCacheResult */
+    $rapidCacheResult = $operation->getResult();
+    printf('Updated Rapid Cache: %s' . PHP_EOL, $rapidCacheResult->getName());
+    printf('TTL: %d seconds' . PHP_EOL, $rapidCacheResult->getTtl()->getSeconds());
+}
+# [END storage_control_update_rapid_cache]
+
+// 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);