feat(storage): add Object Contexts samples and system tests

storage/src/get_object_contexts.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * Copyright 2026 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_object_contexts]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Retrieve contexts for an existing object.
+ *
+ * @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 get_object_contexts(string $bucketName, string $objectName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $object = $bucket->object($objectName);
+
+    $info = $object->info();
+    if (isset($info['contexts']['custom'])) {
+        printf('Contexts for object %s:' . PHP_EOL, $objectName);
+        foreach ($info['contexts']['custom'] as $key => $data) {
+            printf(' - Key: %s, Value: %s' . PHP_EOL, $key, $data['value'] ?? '');
+            printf(' - Created: %s' . PHP_EOL, $data['createTime'] ?? '');
+            printf(' - Updated: %s' . PHP_EOL, $data['updateTime'] ?? '');
+        }
+    }
+}
+# [END storage_get_object_contexts]
+
+// 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_object_contexts.php

@@ -0,0 +1,52 @@
+<?php
+/**
+ * Copyright 2026 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_object_contexts]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ *  List objects with a filter based on contexts.
+ *
+ * @param string $bucketName The name of your Cloud Storage bucket.
+ *        (e.g. 'my-bucket')
+ */
+function list_object_contexts(string $bucketName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+
+    // Example filter: find objects where department is finance
+    $options = [
+        'filter' => 'contexts."department"="finance"'
+    ];
+    foreach ($bucket->objects($options) as $object) {
+        printf('Found object: %s' . PHP_EOL, $object->name());
+    }
+}
+# [END storage_list_object_contexts]
+
+// 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_object_contexts.php

@@ -0,0 +1,64 @@
+<?php
+/**
+ * Copyright 2026 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_object_contexts]
+use Google\Cloud\Storage\StorageClient;
+
+/**
+ * Attach or modify contexts to an existing object.
+ *
+ * @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 set_object_contexts(string $bucketName, string $objectName): void
+{
+    $storage = new StorageClient();
+    $bucket = $storage->bucket($bucketName);
+    $object = $bucket->object($objectName);
+
+    // Contexts are defined under the 'custom' key; keys/values must start with an alphanumeric and avoid quotes/slashes.
+    $object->update([
+        'contexts' => [
+            'custom' => [
+                'department' => ['value' => 'finance'],
+                'priority' => ['value' => 'high']
+            ]
+        ]
+    ]);
+    $info = $object->info();
+    if (isset($info['contexts']['custom'])) {
+        printf('Contexts for object %s were updated:' . PHP_EOL, $objectName);
+        foreach ($info['contexts']['custom'] as $key => $data) {
+            printf(' - Key: %s, Value: %s' . PHP_EOL, $key, $data['value']);
+        }
+    }
+}
+# [END storage_set_object_contexts]
+
+// 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

@@ -42,6 +42,69 @@ public static function setUpBeforeClass(): void
         self::$contents = ' !"#$%&\'()*,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~';
     }
 
+    public function testObjectContexts()
+    {
+        $objectContextsBucket = self::$storage->createBucket(
+            sprintf('%s-test-bucket-%s', self::$projectId, uniqid())
+        );
+        $bucketName = $objectContextsBucket->name();
+        $objectName = 'object-contexts-'.uniqid();
+        $object = $objectContextsBucket->upload('test', [
+            'name' => $objectName,
+        ]);
+        $objectInfo = $object->info()['name'];
+
+        // Set Object Contexts
+        $setOutput = $this->runFunctionSnippet('set_object_contexts', [
+            $bucketName,
+            $objectInfo,
+        ]);
+
+        $this->assertStringContainsString("Contexts for object $objectInfo were updated", $setOutput);
+
+        // Get Object Contexts
+        $getOutput = $this->runFunctionSnippet('get_object_contexts', [
+            $bucketName,
+            $objectInfo
+        ]);
+
+        $this->assertStringContainsString('Key: department, Value: finance', $getOutput);
+        $this->assertStringContainsString('Key: priority, Value: high', $getOutput);
+
+        // List Object Contexts using filter
+        $listOutput = $this->runFunctionSnippet('list_object_contexts', [
+            $bucketName
+        ]);
+        $this->assertStringContainsString("Found object: $objectInfo", $listOutput);
+
+        // Clear all contexts on the object.
+        $object->update([
+            'contexts' => [
+                'custom' => null,
+            ],
+        ]);
+        $object->reload();
+
+        $clearedGetOutput = $this->runFunctionSnippet('get_object_contexts', [
+            $bucketName,
+            $objectName
+        ]);
+
+        $this->assertStringNotContainsString('Key: department, Value: finance', $clearedGetOutput);
+        $this->assertStringNotContainsString('Key: priority, Value: high', $clearedGetOutput);
+
+        $clearedInfo = $object->info();
+        $this->assertTrue(empty($clearedInfo['contexts']['custom'] ?? []));
+
+        // List again with filter after clearing contexts.
+        $clearedListOutput = $this->runFunctionSnippet('list_object_contexts', [
+            $bucketName
+        ]);
+        $this->assertEmpty(trim($clearedListOutput));
+        $object->delete();
+        $objectContextsBucket->delete();
+    }
+
     public function testListObjects()
     {
         $output = self::runFunctionSnippet('list_objects', [