Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
salilg-eng wants to merge 8 commits into
base: main
Choose a base branch
from
+236 −0
Open

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

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
10f5d6f
Object Contexts Sample
salilg-eng Apr 13, 2026
3083a83
Final code
salilg-eng Apr 17, 2026
d1c784b
Final code
salilg-eng Apr 17, 2026
9cf1530
Final code
salilg-eng Apr 17, 2026
e061129
Final code
salilg-eng Apr 17, 2026
7b2aeac
Comments resolved
salilg-eng Apr 20, 2026
60200fd
Update object contexts
salilg-eng Apr 20, 2026
6553999
Fixes as per gemini review
salilg-eng Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 57 additions & 0 deletions storage/src/get_object_contexts.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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']);
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Consider using the null coalescing operator (??) when accessing context fields to make the sample more robust against unexpected API response structures or missing metadata fields.

            printf(' - Key: %s, Value: %s' . PHP_EOL, $key, $data['value'] ?? '');
            printf(' - Created: %s' . PHP_EOL, $data['createTime'] ?? '');
            printf(' - Updated: %s' . PHP_EOL, $data['updateTime'] ?? '');

Copy link
Copy Markdown
Author

@salilg-eng salilg-eng Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added.

}
}
}
# [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);
52 changes: 52 additions & 0 deletions storage/src/list_object_contexts.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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);
64 changes: 64 additions & 0 deletions storage/src/set_object_contexts.php
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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);
61 changes: 61 additions & 0 deletions storage/test/ObjectsTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,67 @@ public static function setUpBeforeClass(): void
self::$contents = ' !"#$%&\'()*,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~';
}

public function testObjectContexts()
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The PR description mentions implementing comprehensive system tests covering presence, absence (-), and existence (:) filter operators in storageTest.php. However, these tests are missing from the current changes in ObjectsTest.php. Please include the promised test cases to ensure full coverage of the filtering logic.

Copy link
Copy Markdown
Author

@salilg-eng salilg-eng Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That is my bad above description mentioned storageTest.php actually made changes in ObjectTest.php file.

{
$objectContextsBucket = self::$storage->createBucket(
sprintf('%s-test-bucket-%s', self::$projectId, time())
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The variable self::$projectId is uninitialized in this test class, which will cause the bucket name to start with a hyphen (e.g., -test-bucket-...). This is an invalid bucket name in Cloud Storage and will cause the test to fail. Additionally, using uniqid() is preferred over time() to avoid collisions during parallel test runs.

            sprintf('%s-test-bucket-%s', self::$storage->projectId(), uniqid())

Copy link
Copy Markdown
Author

@salilg-eng salilg-eng Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since we are using the testTrait file and have the $projectId defined, I believe this approach is correct. However, following your feedback, I have updated time() to uniqid()

);
$bucketName = $objectContextsBucket->name();
$objectName = 'object-contexts-'.uniqid();
$object = $objectContextsBucket->upload('test', [
'name' => $objectName,
]);
$objectName = $object->info()['name'];
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This assignment is redundant as $objectName is already defined on line 51 and its value remains unchanged after the upload. Removing this line improves code clarity and avoids an unnecessary call to the info() method.

        ]);

Copy link
Copy Markdown
Author

@salilg-eng salilg-eng Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Variable name changed.


// Set Object Contexts
$setOutput = $this->runFunctionSnippet('set_object_contexts', [
$bucketName,
$objectName,
]);

$this->assertStringContainsString("Contexts for object $objectName were updated", $setOutput);

// Get Object Contexts
$getOutput = $this->runFunctionSnippet('get_object_contexts', [
$bucketName,
$objectName
]);

$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: $objectName", $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));
}
Comment on lines +47 to +106
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist bot Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

high

The bucket created for this test is never deleted, leading to resource leaks in the test project. Ensure the bucket is deleted at the end of the test, or consider using the shared bucket self::$bucketName if isolation is not strictly required.

Copy link
Copy Markdown
Author

@salilg-eng salilg-eng Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes both object and bucket deleted


public function testListObjects()
{
$output = self::runFunctionSnippet('list_objects', [
Expand Down