Google Cloud Storage Driver

Purpose and Scope

This document details the GoogleCloudStorageAdapter class, which provides integration with Google Cloud Storage (GCS) for the Hypervel Filesystem package. It covers authentication mechanisms, bucket configuration, URL generation (public and signed), streaming operations with range support, and GCS-specific features.

For general cloud storage concepts and features common to both S3 and GCS, see Cloud Storage Drivers. For AWS S3 implementation details, see AWS S3 Driver. For object pooling configuration that applies to GCS, see Object Pooling for Cloud Drivers.

Sources: src/GoogleCloudStorageAdapter.php1-141

---

Class Architecture

The GoogleCloudStorageAdapter extends FilesystemAdapter and integrates with the Google Cloud PHP SDK. It wraps the Flysystem GCS adapter while providing additional functionality specific to the Hypervel ecosystem.

Class Hierarchy

Sources: src/GoogleCloudStorageAdapter.php17-28 src/FilesystemAdapter.php

---

Configuration

Basic Configuration Structure

The GCS driver is configured in config/autoload/filesystems.php under the disks array with driver set to 'gcs'.

Configuration Key	Type	Required	Description
driver	string	Yes	Must be 'gcs'
key_file_path	string	Conditional	Path to service account JSON file
key_file	array	Conditional	Service account credentials as array
project_id	string	Yes	Google Cloud project ID
bucket	string	Yes	GCS bucket name
path_prefix	string	No	Default path prefix for all operations
storage_api_uri	string	No	Custom endpoint for URL generation
api_endpoint	string	No	Custom API endpoint for StorageClient
visibility	string	No	Default visibility ('public' or 'private')
visibility_handler	string	No	Custom visibility handler class
metadata	array	No	Default metadata for uploaded objects
throw	bool	No	Whether to throw exceptions on errors
stream_reads	bool	No	Enable streaming for read operations
pool	array	No	Object pooling configuration

Sources: publish/filesystems.php65-85

Authentication Configuration

GCS authentication uses one of two methods:

Method 1: Key File Path

Method 2: Key File Array

Sources: publish/filesystems.php67-69

Configuration Flow

Sources: src/GoogleCloudStorageAdapter.php21-28 publish/filesystems.php79-84

---

URL Generation

Public URLs

The url() method generates public URLs for accessing objects stored in GCS. It uses the storage_api_uri configuration if provided, otherwise defaults to the standard Google Cloud Storage endpoint.

The implementation at src/GoogleCloudStorageAdapter.php35-45 shows:

1. Default endpoint construction: DEFAULT_API_ENDPOINT (defined as 'https://storage.googleapis.com' at line 19) concatenated with the bucket name
2. Override with storage_api_uri if configured
3. Path prefixing applied via the inherited prefixer property
4. URL concatenation via concatPathToUrl() helper

Sources: src/GoogleCloudStorageAdapter.php19-45

Temporary Signed URLs

The temporaryUrl() method generates time-limited signed URLs for secure access to private objects. It delegates to the Google Cloud Storage SDK's signedUrl() method.

Parameter	Type	Required	Description
$path	string	Yes	Object path within bucket
$expiration	DateTimeInterface	Yes	URL expiration timestamp
$options	array	No	Additional options for signed URL generation

Implementation Details

At src/GoogleCloudStorageAdapter.php50-57 the method:

1. Checks if storage_api_uri is configured
2. If set, adds it as bucketBoundHostname option to use custom domain
3. Retrieves bucket via getBucket() helper method
4. Calls object()->signedUrl() on the Google Cloud Storage object
5. Automatically applies path prefix via prefixer->prefixPath()

Sources: src/GoogleCloudStorageAdapter.php50-57

Temporary Upload URLs

The temporaryUploadUrl() method generates signed URLs specifically for uploading content. It returns an array containing the upload URL and session details.

The method at src/GoogleCloudStorageAdapter.php62-69 follows similar logic to temporaryUrl() but calls beginSignedUploadSession() instead, which returns:

• Upload URL for PUT/POST requests
• Session token for resumable uploads
• Additional session metadata

Sources: src/GoogleCloudStorageAdapter.php62-69

---

Streaming Operations

Standard Stream Reading

The readStream() method returns a PHP resource for reading file content. The behavior is controlled by the stream_reads configuration option.

At src/GoogleCloudStorageAdapter.php76-82 the method:

• Checks $this->config['stream_reads'] flag
• If true, passes ['restOptions' => ['stream' => true]] to optimize for streaming
• Delegates to internal readStreamWithOptions() method

Sources: src/GoogleCloudStorageAdapter.php76-82

Range Stream Reading

The readStreamRange() method enables partial content retrieval using HTTP Range headers, essential for video streaming and large file handling.

Parameter	Type	Required	Description
$path	string	Yes	Object path
$start	int	No	Starting byte position (null for beginning)
$end	int	No	Ending byte position (null for end)

Range Request Implementation

At src/GoogleCloudStorageAdapter.php89-102 the method:

1. Constructs Range header: "bytes={$start}-{$end}"
2. Merges with stream_reads configuration
3. Passes to readStreamWithOptions()

The internal readStreamWithOptions() method at src/GoogleCloudStorageAdapter.php112-127:

1. Applies path prefix
2. Calls getBucket()->object()->downloadAsStream($options)
3. Detaches the PSR-7 stream to get raw PHP resource
4. Validates resource and throws UnableToReadFile if invalid

Sources: src/GoogleCloudStorageAdapter.php89-127

---

Client Access and Bucket Management

StorageClient Access

The getClient() method at src/GoogleCloudStorageAdapter.php107-110 provides direct access to the underlying StorageClient instance for advanced operations not covered by the adapter interface.

Internal Bucket Retrieval

The private getBucket() method at src/GoogleCloudStorageAdapter.php129-132 retrieves the configured bucket instance:

This helper is used internally by temporaryUrl(), temporaryUploadUrl(), and streaming methods to access bucket-level operations.

Sources: src/GoogleCloudStorageAdapter.php107-132

---

GCS-Specific Features

Custom Storage API URI

The storage_api_uri configuration enables custom domain URLs for public and signed URLs. This is useful for:

• Custom domains mapped to GCS buckets
• CDN endpoints in front of GCS
• Internal/private GCS endpoints

When configured at publish/filesystems.php72:

• url() method uses it as base URL instead of storage.googleapis.com
• temporaryUrl() passes it as bucketBoundHostname option
• temporaryUploadUrl() includes it in session configuration

Sources: src/GoogleCloudStorageAdapter.php37-44 src/GoogleCloudStorageAdapter.php52-54 publish/filesystems.php72

API Endpoint Configuration

The api_endpoint configuration at publish/filesystems.php73 sets a custom API endpoint for the StorageClient itself, enabling:

• Regional endpoints for reduced latency
• Private Google Cloud API access
• Development/testing against GCS emulators

This differs from storage_api_uri which only affects URL generation, not the actual API communication.

Sources: publish/filesystems.php73

Visibility Handler

The visibility_handler configuration at publish/filesystems.php75 allows specifying a custom visibility handler class. The example configuration mentions UniformBucketLevelAccessVisibility::class which enables uniform bucket-level access control rather than per-object ACLs.

Sources: publish/filesystems.php75

Default Metadata

The metadata configuration at publish/filesystems.php76 sets default metadata for all uploaded objects. Example:

These metadata values are applied by the Flysystem GCS adapter during write operations.

Sources: publish/filesystems.php76

Stream Reads Configuration

The stream_reads option at publish/filesystems.php78 controls whether the Google Cloud SDK should use streaming for downloads. When enabled:

• The SDK passes data through without buffering in memory
• More efficient for large files
• Reduces memory usage in high-concurrency environments

The flag is checked at src/GoogleCloudStorageAdapter.php80 and src/GoogleCloudStorageAdapter.php98

Sources: src/GoogleCloudStorageAdapter.php76-102 publish/filesystems.php78

---

Object Pooling Support

The GoogleCloudStorageAdapter is marked as poolable in the FilesystemManager, meaning it can be wrapped in a FilesystemPoolProxy for connection pooling in Swoole/Hyperf environments.

Pool Configuration

Pooling Architecture

The pooling mechanism:

1. Reuses StorageClient instances across requests
2. Prevents authentication overhead for each request
3. Manages connection lifecycle automatically
4. Returns connections to pool after operations complete

For detailed pooling behavior and configuration, see Object Pooling for Cloud Drivers.

Sources: publish/filesystems.php79-84

---

Temporary URLs Capability

The GoogleCloudStorageAdapter implements the providesTemporaryUrls() method, which always returns true at src/GoogleCloudStorageAdapter.php137-140 This indicates that the driver supports signed URL generation for secure temporary access to private objects.

This method is used by the framework to determine whether methods like temporaryUrl() and temporaryUploadUrl() can be safely called on the driver instance.

Sources: src/GoogleCloudStorageAdapter.php137-140

---

Error Handling

Stream Reading Errors

The readStreamWithOptions() method at src/GoogleCloudStorageAdapter.php112-127 implements comprehensive error handling:

1. Exception Catching: Wraps all Google Cloud SDK exceptions in Flysystem's UnableToReadFile exception
2. Resource Validation: Verifies that detach() returns a valid PHP resource
3. Descriptive Messages: Includes original exception message and path information

Sources: src/GoogleCloudStorageAdapter.php116-124

---

Integration Points

Constructor Dependencies

The GoogleCloudStorageAdapter constructor at src/GoogleCloudStorageAdapter.php21-28 requires four dependencies:

Parameter	Type	Purpose
$driver	FilesystemOperator	Flysystem operator instance
$adapter	FlysystemGoogleCloudAdapter	Flysystem GCS adapter
$config	array	Driver configuration
$client	StorageClient	Google Cloud Storage client

These are injected by the FilesystemManager when creating the GCS driver instance. The manager is responsible for instantiating the StorageClient with proper authentication and creating the Flysystem adapter before constructing the GoogleCloudStorageAdapter.

Sources: src/GoogleCloudStorageAdapter.php21-28

Inherited Capabilities

As a subclass of FilesystemAdapter, the GoogleCloudStorageAdapter inherits:

• Standard CRUD operations (exists, get, put, delete)
• Directory operations (files, directories, makeDirectory)
• Metadata operations (size, lastModified, mimeType)
• Visibility management (getVisibility, setVisibility)
• File upload handling (putFile, putFileAs)
• HTTP response generation (response, download)

These methods are implemented in the base FilesystemAdapter class and work seamlessly with GCS through the Flysystem abstraction layer.

Sources: src/GoogleCloudStorageAdapter.php17

---

Usage Examples

Basic Setup

Generating Temporary URLs

Range Stream Reading

Custom Domain Configuration

Sources: src/GoogleCloudStorageAdapter.php35-69 publish/filesystems.php65-85