 |
VOOZH | about |
|
VOOZH | about |
This page documents the URL generation capabilities of the Hypervel Filesystem package, including public URLs, temporary signed URLs for downloads, and temporary signed upload URLs. The system provides a unified interface for generating URLs across different storage drivers while respecting driver-specific requirements and security mechanisms.
For information about HTTP response generation and file serving, see Streaming and Content Handling. For driver-specific configuration including URL settings, see Configuration Reference.
The filesystem package supports three types of URL generation:
| URL Type | Method | Drivers | Purpose |
|---|---|---|---|
| Public URL | url() | Local, S3, GCS | Generate permanent public URLs for files |
| Temporary Download URL | temporaryUrl() | Local, S3, GCS | Generate time-limited signed URLs for secure downloads |
| Temporary Upload URL | temporaryUploadUrl() | S3, GCS | Generate time-limited signed URLs for direct uploads |
The Cloud contract src/Contracts/Cloud.php1-13 extends the base Filesystem interface and defines the url() method as the primary interface for URL generation. All adapter classes that support URL generation implement this contract.
Sources: src/Contracts/Cloud.php1-13
Diagram: URL Generation Contract Hierarchy
The Cloud interface defines the url() method signature. Each adapter implements this method differently based on the underlying storage backend. The providesTemporaryUrls() method indicates whether a driver supports temporary URL generation.
Sources: src/Contracts/Cloud.php1-13 src/LocalFilesystemAdapter.php12-92 src/AwsS3V3Adapter.php14-125 src/GoogleCloudStorageAdapter.php17-141
The S3 adapter generates public URLs using the S3 client's getObjectUrl() method src/AwsS3V3Adapter.php47-50 If a custom base URL is configured via the url configuration key, it is used instead of the default S3 URL format src/AwsS3V3Adapter.php43-44
Diagram: S3 Public URL Generation Flow
Configuration Example:
Sources: src/AwsS3V3Adapter.php38-51
The GCS adapter generates public URLs by constructing them from the Google Cloud Storage API endpoint src/GoogleCloudStorageAdapter.php37-38 The base URL defaults to https://storage.googleapis.com/{bucket} but can be customized using the storageApiUri configuration option src/GoogleCloudStorageAdapter.php40-42
Diagram: GCS Public URL Generation Flow
Configuration Example:
Sources: src/GoogleCloudStorageAdapter.php35-45
The local filesystem adapter does not provide public URL generation through the url() method. URLs for local files must be handled at the application or web server level. The adapter focuses on temporary signed URL generation for secure access to local files.
Sources: src/LocalFilesystemAdapter.php12-92
Temporary URLs provide time-limited access to files without exposing them publicly. Each driver implements this differently based on the underlying storage platform's security mechanisms.
The providesTemporaryUrls() method indicates whether a driver supports temporary URL generation:
| Driver | Support | Implementation |
|---|---|---|
| LocalFilesystemAdapter | Conditional | Returns true only if temporaryUrlCallback is set or signed URL serving is enabled src/LocalFilesystemAdapter.php34-39 |
| AwsS3V3Adapter | Always | Returns true src/AwsS3V3Adapter.php56-59 |
| GoogleCloudStorageAdapter | Always | Returns true src/GoogleCloudStorageAdapter.php137-140 |
Sources: src/LocalFilesystemAdapter.php34-39 src/AwsS3V3Adapter.php56-59 src/GoogleCloudStorageAdapter.php137-140
The S3 adapter generates pre-signed URLs using the AWS SDK's createPresignedRequest() method src/AwsS3V3Adapter.php71-75
Diagram: S3 Temporary URL Generation Sequence
The method constructs a GetObject command with the bucket and key src/AwsS3V3Adapter.php66-69 creates a presigned request src/AwsS3V3Adapter.php71-75 and optionally replaces the base URL if temporary_url is configured src/AwsS3V3Adapter.php80-82
Usage Example:
Sources: src/AwsS3V3Adapter.php64-85
The GCS adapter generates signed URLs using the GCS SDK's signedUrl() method on the bucket object src/GoogleCloudStorageAdapter.php56
Diagram: GCS Temporary URL Generation Sequence
If a custom storageApiUri is configured, it is passed as the bucketBoundHostname option src/GoogleCloudStorageAdapter.php52-54 The method retrieves the bucket instance src/GoogleCloudStorageAdapter.php129-132 and generates a signed URL for the specified object src/GoogleCloudStorageAdapter.php56
Usage Example:
Sources: src/GoogleCloudStorageAdapter.php50-57 src/GoogleCloudStorageAdapter.php129-132
The local adapter supports temporary URLs through two mechanisms:
temporaryUrlCallback can be set on the adapter instance (inherited from FilesystemAdapter)Diagram: Local Filesystem Temporary URL Decision Flow
The adapter first checks for a custom callback src/LocalFilesystemAdapter.php46-51 If not present, it verifies that signed URL serving is enabled src/LocalFilesystemAdapter.php54-56 then generates a signed route URL using the format storage.{disk} src/LocalFilesystemAdapter.php60-65
Configuration Requirements:
To enable signed URL generation for local disks:
Sources: src/LocalFilesystemAdapter.php44-66 src/LocalFilesystemAdapter.php85-91
Temporary upload URLs allow clients to upload files directly to cloud storage without proxying through the application server. This feature is only available for cloud storage drivers.
The S3 adapter generates pre-signed upload URLs using a PutObject command src/AwsS3V3Adapter.php92-95
Diagram: S3 Temporary Upload URL Generation
The method returns both the URL and required headers as an array src/AwsS3V3Adapter.php112-115 If a custom temporary_url is configured, the base URL is replaced src/AwsS3V3Adapter.php108-110
Usage Example:
Sources: src/AwsS3V3Adapter.php90-116
The GCS adapter generates signed upload sessions using the beginSignedUploadSession() method src/GoogleCloudStorageAdapter.php68
Diagram: GCS Temporary Upload URL Generation
If a custom storageApiUri is configured, it is passed as the bucketBoundHostname option src/GoogleCloudStorageAdapter.php64-66
Usage Example:
Sources: src/GoogleCloudStorageAdapter.php62-69
Both S3 and GCS adapters support custom domains for URL generation, allowing applications to serve files through CDNs or custom domain names.
| Driver | Public URLs | Temporary Download URLs | Temporary Upload URLs |
|---|---|---|---|
| S3 | url config key src/AwsS3V3Adapter.php43 | temporary_url config key src/AwsS3V3Adapter.php80 | temporary_url config key src/AwsS3V3Adapter.php108 |
| GCS | storageApiUri config key src/GoogleCloudStorageAdapter.php40 | storageApiUri config key src/GoogleCloudStorageAdapter.php52 | storageApiUri config key src/GoogleCloudStorageAdapter.php64 |
Diagram: Custom Domain URL Construction
Both adapters use the concatPathToUrl() method (inherited from FilesystemAdapter) to combine the custom domain with the prefixed path. The prefixer property handles path prefixing based on the driver configuration.
Example Configuration:
Sources: src/AwsS3V3Adapter.php38-51 src/AwsS3V3Adapter.php64-85 src/AwsS3V3Adapter.php90-116 src/GoogleCloudStorageAdapter.php35-45 src/GoogleCloudStorageAdapter.php50-57 src/GoogleCloudStorageAdapter.php62-69
| Feature | Local | S3 | GCS |
|---|---|---|---|
| Public URLs | Not supported | url() - via S3 client or custom domain | url() - via GCS API or custom domain |
| Temporary Download URLs | temporaryUrl() - via signed routes | temporaryUrl() - via pre-signed requests | temporaryUrl() - via signed URLs |
| Temporary Upload URLs | Not supported | temporaryUploadUrl() - returns URL + headers | temporaryUploadUrl() - returns resumable upload URL |
| Custom Domain Support | N/A | url, temporary_url config keys | storageApiUri config key |
| providesTemporaryUrls() | Conditional (callback or signed routes) | Always true | Always true |
Sources: src/LocalFilesystemAdapter.php12-92 src/AwsS3V3Adapter.php14-125 src/GoogleCloudStorageAdapter.php17-141 src/Contracts/Cloud.php1-13
Refresh this wiki