feat(storage): implement Object Contexts with advanced filtering and validation (#9122)

salilg-eng · nidhiii-27 · web-flow · commit c59cc4dd686c · 2026-05-04T12:47:35.000+05:30
* insert and get contexts perform * Unit Test Cases * Unit Test Cases * Resolve comments * Follow the checklist and resolved comments * Follow the checklist and resolved comments * Follow the checklist and resolved comments * Fixed gemini related comments * Fixed gemini related comments * Style code * Style code * Personal Review code * Style set * Style set * Required Changes * Required Changes * Required Changes * As per new comments changes * Changes * Remove old test method * Handled System Test cases * Gemini review and style check * Style Check * Style Check * Pending scenario covers * Pending scenario covers * Pending scenario covers * Pending scenario covers * Pending scenario covers * Remove unwanted delete code * Remove unwanted delete code * Add FIle const * Handle more scenario and resolved comments * Add more scenarios and also recheck with document * Make a trait for validateContext and use in both bucket and storageObject file * Changed code as per gemini review * Changed code as per gemini review * Changed code as per gemini review * Changes code as per comments * Style check issue * Style check issue * Style check issue * Review Manage Test * Overall Completed the Test case only filter in system test is pending * Add New cases and scenarios * Updated code * Updated code * Updated code * Updated code * Updated code * Updated code * Updated code * Updated Code * Fixer * CHanges as per gemini review * CS Fixer * gemini review * gemini review * Changed according to feedback * Final changes code * Final changes code * Final changes code * Final change and push * Final change and push * FInal Code * Final Code * Polish code * Apply suggestion from @nidhiii-27 Co-authored-by: Nidhi <nidhiii@google.com> * Jetski review * Fixed Style check * Fixed JSON * Removed White space --------- Co-authored-by: Nidhi <nidhiii@google.com>
diff --git a/Storage/src/Bucket.php b/Storage/src/Bucket.php
@@ -274,6 +274,12 @@ public function exists(array $options = [])
      *     @type array $metadata The full list of available options are outlined
      *           at the [JSON API docs](https://cloud.google.com/storage/docs/json_api/v1/objects/insert#request-body).
      *     @type array $metadata.metadata User-provided metadata, in key/value pairs.
+     *     @type array $contexts Object contexts. See at the
+     *           [API docs](https://docs.cloud.google.com/storage/docs/use-object-contexts) for more details.
+     *     @type string $contexts.custom.{key}.createTime The time the context
+     *           was created in RFC 3339 format. **(read only)**
+     *     @type string $contexts.custom.{key}.updateTime The time the context
+     *           was last updated in RFC 3339 format. **(read only)**
      *     @type string $encryptionKey A base64 encoded AES-256 customer-supplied
      *           encryption key. If you would prefer to manage encryption
      *           utilizing the Cloud Key Management Service (KMS) please use the
@@ -294,6 +300,15 @@ public function upload($data, array $options = [])
             throw new \InvalidArgumentException('A name is required when data is of type string or null.');
         }
 
+        if (isset($options['contexts'])) {
+            if (!is_array($options['contexts'])) {
+                throw new \InvalidArgumentException('Object contexts must be an array.');
+            }
+            if (isset($options['contexts']['custom']) && !is_array($options['contexts']['custom'])) {
+                throw new \InvalidArgumentException('Object contexts custom field must be an array.');
+            }
+        }
+
         $encryptionKey = $options['encryptionKey'] ?? null;
         $encryptionKeySHA256 = $options['encryptionKeySHA256'] ?? null;
 
@@ -703,6 +718,9 @@ public function restore($name, $generation, array $options = [])
      *           distinct results. **Defaults to** `false`.
      *     @type string $fields Selector which will cause the response to only
      *           return the specified fields.
+     *     @type string $filter Filter results to include only objects to which the
+     *           specified context is attached. You can filter by the presence,
+     *           absence, or specific value of context keys.
      *     @type string $matchGlob A glob pattern to filter results. The string
      *           value must be UTF-8 encoded. See:
      *           https://cloud.google.com/storage/docs/json_api/v1/objects/list#list-object-glob
@@ -712,7 +730,6 @@ public function restore($name, $generation, array $options = [])
     public function objects(array $options = [])
     {
         $resultLimit = $this->pluck('resultLimit', $options, false);
-
         return new ObjectIterator(
             new ObjectPageIterator(
                 function (array $object) {
diff --git a/Storage/src/Connection/Rest.php b/Storage/src/Connection/Rest.php
@@ -526,6 +526,12 @@ private function resolveUploadOptions(array $args)
             $args['metadata']['retention'] = $args['retention'];
             unset($args['retention']);
         }
+        if (isset($args['contexts'])) {
+            // during object creation context properties are part of the object resource
+            // and should be included in the request body.
+            $args['metadata']['contexts'] = $args['contexts'];
+            unset($args['contexts']);
+        }
         unset($args['name']);
         $args['contentType'] = $args['metadata']['contentType']
             ?? MimeType::fromFilename($args['metadata']['name']);
diff --git a/Storage/src/Connection/ServiceDefinition/storage-v1.json b/Storage/src/Connection/ServiceDefinition/storage-v1.json
@@ -1561,6 +1561,41 @@
                     "type": "string",
                     "description": "The modification time of the object metadata in RFC 3339 format. Set initially to object creation time and then updated whenever any metadata of the object changes. This includes changes made by a requester, such as modifying custom metadata, as well as changes made by Cloud Storage on behalf of a requester, such as changing the storage class based on an Object Lifecycle Configuration.",
                     "format": "date-time"
+                },
+                "contexts" : {
+                    "type": "object",
+                    "description": "User-defined or system-defined object contexts. Represented as key-payload pairs, where the key identifies the context and the payload contains the associated value and additional metadata.",
+                    "properties" : {
+                        "custom" : {
+                            "type": "object",
+                            "description": "User-provided object contexts where each entry consists of a unique key and a corresponding payload.",
+                            "additionalProperties": {
+                                "$ref": "ObjectCustomContextPayload",
+                                "description": "A single user-defined object context."
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "ObjectCustomContextPayload": {
+            "id": "ObjectCustomContextPayload",
+            "type": "object",
+            "description": "The payload associated with a user-defined context key.",
+            "properties": {
+                "value": {
+                    "type": "string",
+                    "description": "The value of the object contexts."
+                },
+                "createTime": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The time at which the object contexts was created in RFC 3339 format."
+                },
+                "updateTime": {
+                    "type": "string",
+                    "format": "date-time",
+                    "description": "The time at which the object context was last updated in RFC 3339 format."
                 }
             }
         },
@@ -4865,6 +4900,11 @@
                             "required": true,
                             "location": "path"
                         },
+                        "filter": {
+                            "type": "string",
+                            "description": "Filter results to include only objects to which the specified context is attached. You can filter by the presence, absence, or specific value of context keys.",
+                            "location": "query"
+                        },
                         "delimiter": {
                             "type": "string",
                             "description": "Returns results in a directory-like mode. items will contain only objects whose names, aside from the prefix, do not contain delimiter. Objects whose names, aside from the prefix, contain delimiter will have their name, truncated after the delimiter, returned in prefixes. Duplicate prefixes are omitted.",
diff --git a/Storage/src/StorageObject.php b/Storage/src/StorageObject.php
@@ -231,6 +231,12 @@ public function delete(array $options = [])
      *           This is the retention configuration set for this object.
      *     @type string $retention.mode The mode of the retention configuration,
      *           which can be either `"Unlocked"` or `"Locked"`.
+     *     @type array $contexts Object contexts. See at the
+     *           [API docs](https://docs.cloud.google.com/storage/docs/use-object-contexts) for more details.
+     *     @type string $contexts.custom.{key}.createTime The time the context
+     *           was created in RFC 3339 format. **(read only)**
+     *     @type string $contexts.custom.{key}.updateTime The time the context
+     *           was last updated in RFC 3339 format. **(read only)**
      *     @type bool $overrideUnlockedRetention Applicable for objects that
      *           have an unlocked retention configuration. Required to be set to
      *           `true` if the operation includes a retention property that
diff --git a/Storage/tests/System/ManageObjectsTest.php b/Storage/tests/System/ManageObjectsTest.php
diff --git a/Storage/tests/Unit/BucketTest.php b/Storage/tests/Unit/BucketTest.php
