Contracts and Interfaces

Purpose: This page documents the three core interface contracts that define the public API of the Hypervel Filesystem package: Factory, Filesystem, and Cloud. These contracts enable polymorphic driver usage, allowing different storage backends (local, S3, GCS, FTP, SFTP) to be used interchangeably through a unified, type-safe API.

For information about how these contracts are implemented in concrete driver classes, see Driver Architecture and FilesystemAdapter. For details on how the Factory pattern is used to create driver instances, see Factory Pattern and FilesystemManager.

---

Overview

The package defines three primary interface contracts located in the src/Contracts/ directory:

Interface	Purpose	Methods
Factory	Entry point for obtaining filesystem instances	1 method
Filesystem	Complete API for file and directory operations	24 methods + 2 constants
Cloud	Extends Filesystem with URL generation for cloud storage	Inherits 24 + adds 1 method

These interfaces enable:

• Polymorphism: Application code depends on abstractions rather than concrete implementations
• Type Safety: PHP 8.2+ type hints ensure compile-time verification
• Extensibility: Custom drivers can implement these contracts to integrate seamlessly
• Testability: Interfaces can be mocked for unit testing without external dependencies

Sources: src/Contracts/Factory.php src/Contracts/Filesystem.php src/Contracts/Cloud.php

---

Contract Hierarchy

Sources: src/Contracts/Factory.php1-14 src/Contracts/Filesystem.php1-156 src/Contracts/Cloud.php1-14

---

Factory Interface

The Factory interface defines the contract for obtaining filesystem instances. It serves as the primary entry point for all filesystem operations in the package.

Interface Definition

src/Contracts/Factory.php7-13

Method: disk()

Signature: public function disk(?string $name = null): Filesystem

Parameters:

• $name (string|null): The name of the disk configuration to retrieve. When null, returns the default disk specified in configuration.

Returns: Filesystem - A filesystem instance implementing the Filesystem contract (or Cloud which extends it)

Purpose: Retrieves a configured filesystem instance by name. The implementation (typically FilesystemManager) handles:

• Configuration resolution from filesystems.php
• Driver instantiation or cache retrieval
• Pooling wrapper application for cloud drivers
• Custom driver resolution via registered creators

Implementation Classes

Class	Location	Description
FilesystemManager	src/FilesystemManager.php	Primary implementation; manages driver lifecycle, caching, and pooling

Sources: src/Contracts/Factory.php1-14

---

Filesystem Interface

The Filesystem interface defines the complete API for file and directory operations. All drivers in the package implement this interface, either directly or through the Cloud interface extension.

Interface Definition Location

src/Contracts/Filesystem.php11-155

The interface resides in the Hypervel\Filesystem\Contracts namespace and defines 2 visibility constants and 24 methods organized into functional categories.

Visibility Constants

src/Contracts/Filesystem.php14-25

Constant	Value	Description
VISIBILITY_PUBLIC	'public'	Files are publicly accessible (HTTP readable without authentication)
VISIBILITY_PRIVATE	'private'	Files require authentication or signed URLs for access

These constants standardize visibility settings across storage backends with different native permission systems (Unix permissions, S3 ACLs, GCS IAM, etc.).

Sources: src/Contracts/Filesystem.php14-25

Method Categories

Sources: src/Contracts/Filesystem.php1-156

---

File Operations Methods

path()

src/Contracts/Filesystem.php28-30

Signature: public function path(string $path): string

Returns: Full absolute path to the file

Purpose: Returns the complete filesystem path. For local drivers, this is the absolute disk path. For cloud drivers, behavior varies by implementation.

---

exists()

src/Contracts/Filesystem.php33-35

Signature: public function exists(string $path): bool

Returns: true if file exists, false otherwise

Purpose: Checks for file existence without reading content.

---

get()

src/Contracts/Filesystem.php38-40

Signature: public function get(string $path): ?string

Returns: File contents as string, or null if file doesn't exist

Purpose: Retrieves complete file contents as a string. For large files, consider using readStream() to avoid memory exhaustion.

---

put()

src/Contracts/Filesystem.php58-62

Signature: public function put(string $path, mixed $contents, mixed $options = []): bool|string

Parameters:

• $path: Target file path (relative to disk root)
• $contents: Can be string, resource, StreamInterface, or UploadedFile
• $options: Driver-specific options (visibility, metadata, etc.)

Returns: true on success, false on failure, or string path in some implementations

Purpose: Writes content to a file, creating or overwriting as needed.

---

delete()

src/Contracts/Filesystem.php103-104

Signature: public function delete(array|string $paths): bool

Parameters:

• $paths: Single path string or array of paths

Returns: true if all files deleted successfully

Purpose: Deletes one or more files. Non-existent files typically don't cause failure.

---

copy()

src/Contracts/Filesystem.php108-109

Signature: public function copy(string $from, string $to): bool

Purpose: Copies a file to a new location within the same disk.

---

move()

src/Contracts/Filesystem.php113-114

Signature: public function move(string $from, string $to): bool

Purpose: Moves (renames) a file within the same disk.

Sources: src/Contracts/Filesystem.php28-114

---

Stream Operations Methods

readStream()

src/Contracts/Filesystem.php43-47

Signature: public function readStream(string $path): mixed

Returns: PHP resource handle for reading, or null on failure

Purpose: Opens a stream for reading file contents incrementally. Caller must close the resource.

Example Usage Pattern:

---

readStreamRange()

src/Contracts/Filesystem.php50-55

Signature: public function readStreamRange(string $path, ?int $start, ?int $end): mixed

Parameters:

• $path: File path
• $start: Starting byte position (null for beginning)
• $end: Ending byte position (null for end of file)

Returns: PHP resource handle for the byte range, or null on failure

Throws: RuntimeException if driver doesn't support range requests

Purpose: Opens a stream for reading a specific byte range, enabling HTTP range requests and partial downloads. Supported by S3 and GCS drivers.

---

writeStream()

src/Contracts/Filesystem.php75-79

Signature: public function writeStream(string $path, mixed $resource, array $options = []): bool

Parameters:

• $path: Target file path
• $resource: PHP resource handle to read from
• $options: Driver-specific options

Purpose: Writes a file from a stream resource, enabling efficient uploads of large files without loading entire contents into memory.

Sources: src/Contracts/Filesystem.php43-79

---

Upload Operations Methods

putFile()

src/Contracts/Filesystem.php65-67

Signature: public function putFile(string|UploadedFile $path, array|string|UploadedFile|null $file = null, mixed $options = []): false|string

Returns: Stored file path on success, false on failure

Purpose: Stores an uploaded file with an automatically generated unique filename. Parameter flexibility supports both putFile($directory, $uploadedFile) and putFile($uploadedFile) patterns.

---

putFileAs()

src/Contracts/Filesystem.php70-72

Signature: public function putFileAs(string|UploadedFile $path, array|string|UploadedFile|null $file, array|string|null $name = null, mixed $options = []): false|string

Returns: Stored file path on success, false on failure

Purpose: Stores an uploaded file with a specific filename rather than generating one.

Sources: src/Contracts/Filesystem.php65-72

---

Visibility Operations Methods

getVisibility()

src/Contracts/Filesystem.php82-84

Signature: public function getVisibility(string $path): string

Returns: Filesystem::VISIBILITY_PUBLIC or Filesystem::VISIBILITY_PRIVATE

Purpose: Retrieves the current access level of a file.

---

setVisibility()

src/Contracts/Filesystem.php87-89

Signature: public function setVisibility(string $path, string $visibility): bool

Parameters:

• $visibility: One of the visibility constants

Purpose: Changes file access level. For S3, maps to ACLs. For local storage, may affect Unix permissions.

Sources: src/Contracts/Filesystem.php82-89

---

Text Operations Methods

prepend()

src/Contracts/Filesystem.php92-94

Signature: public function prepend(string $path, string $data): bool

Purpose: Adds content to the beginning of a file. Creates file if it doesn't exist.

---

append()

src/Contracts/Filesystem.php97-99

Signature: public function append(string $path, string $data): bool

Purpose: Adds content to the end of a file. Creates file if it doesn't exist.

Sources: src/Contracts/Filesystem.php92-99

---

Metadata Operations Methods

size()

src/Contracts/Filesystem.php117-119

Signature: public function size(string $path): int

Returns: File size in bytes

Purpose: Gets file size without reading contents.

---

lastModified()

src/Contracts/Filesystem.php122-124

Signature: public function lastModified(string $path): int

Returns: Unix timestamp of last modification

Purpose: Retrieves file modification time.

Sources: src/Contracts/Filesystem.php117-124

---

Directory Operations Methods

files()

src/Contracts/Filesystem.php127-129

Signature: public function files(?string $directory = null, bool $recursive = false): array

Parameters:

• $directory: Directory path (null for root)
• $recursive: Whether to include subdirectories

Returns: Array of file paths

---

allFiles()

src/Contracts/Filesystem.php131-134

Signature: public function allFiles(?string $directory = null): array

Purpose: Convenience method equivalent to files($directory, true).

---

directories()

src/Contracts/Filesystem.php137-139

Signature: public function directories(?string $directory = null, bool $recursive = false): array

Returns: Array of directory paths

---

allDirectories()

src/Contracts/Filesystem.php142-144

Signature: public function allDirectories(?string $directory = null): array

Purpose: Convenience method equivalent to directories($directory, true).

---

makeDirectory()

src/Contracts/Filesystem.php147-149

Signature: public function makeDirectory(string $path): bool

Purpose: Creates a directory. Most implementations create parent directories automatically.

---

deleteDirectory()

src/Contracts/Filesystem.php152-154

Signature: public function deleteDirectory(string $directory): bool

Purpose: Recursively deletes a directory and all its contents.

Sources: src/Contracts/Filesystem.php127-154

---

Method Summary Table

Category	Methods	Count
File Operations	path(), exists(), get(), put(), delete(), copy(), move()	7
Stream Operations	readStream(), readStreamRange(), writeStream()	3
Upload Operations	putFile(), putFileAs()	2
Visibility Operations	getVisibility(), setVisibility()	2
Text Operations	prepend(), append()	2
Metadata Operations	size(), lastModified()	2
Directory Operations	files(), allFiles(), directories(), allDirectories(), makeDirectory(), deleteDirectory()	6
Total	24

Sources: src/Contracts/Filesystem.php1-156

---

Cloud Interface

The Cloud interface extends Filesystem with URL generation capabilities for cloud storage backends. All cloud storage drivers (S3, GCS) and the local driver implement this interface.

Interface Definition

src/Contracts/Cloud.php7-13

Inheritance

The Cloud interface inherits all 24 methods from Filesystem and adds 1 method, totaling 25 methods for cloud storage operations.

Method: url()

src/Contracts/Cloud.php10-12

Signature: public function url(string $path): string

Returns: Publicly accessible URL for the file

Purpose: Generates a URL for accessing the file. URL format and accessibility depend on the storage provider and configuration.

Behavior by Driver:

Driver	URL Format	Requirements
LocalFilesystemAdapter	http://domain.com/storage/path	Requires url or serve configuration
AwsS3V3Adapter	https://bucket.s3.region.amazonaws.com/path	Bucket public read access for public files
GoogleCloudStorageAdapter	https://storage.googleapis.com/bucket/path	Bucket public access configuration

Common Extension Methods

While not defined in the Cloud interface, most implementations provide these additional methods:

Method	Description	Available In
temporaryUrl(path, expiration)	Generates time-limited signed URL	Local, S3, GCS
temporaryUploadUrl(path, expiration)	Generates signed URL for uploads	S3 only
providesTemporaryUrls()	Checks if driver supports signed URLs	Local, S3, GCS

These extension methods are checked at runtime using method_exists() since they're not part of the interface contract. See URL Generation for detailed documentation.

Sources: src/Contracts/Cloud.php1-14

---

Contract Implementation Map

Sources: src/Contracts/Factory.php src/Contracts/Filesystem.php src/Contracts/Cloud.php

---

Polymorphic Usage Patterns

Pattern 1: Dependency Injection with Factory

Type-hint Factory to enable disk resolution at runtime:

Pattern 2: Type-Hint Filesystem for Operations

Type-hint Filesystem to work with any driver:

Pattern 3: Type-Hint Cloud for URL Generation

Type-hint Cloud when URL generation is required:

Pattern 4: Runtime Driver Switching

Use Factory::disk() to switch between configured drivers:

Sources: src/Contracts/Factory.php src/Contracts/Filesystem.php src/Contracts/Cloud.php

---

Contract Guarantees and Type Safety

Return Type Contracts

Return Type	Meaning	Methods
bool	Success/failure indicator	exists(), put(), delete(), copy(), move(), writeStream(), setVisibility(), prepend(), append(), makeDirectory(), deleteDirectory()
string	Text data or URL	path(), getVisibility(), url()
?string	Nullable text data	get()
int	Numeric value	size(), lastModified()
array	Collection of paths	files(), allFiles(), directories(), allDirectories()
resource|null	Stream handle or failure	readStream(), readStreamRange()
false|string	Failure or success with path	putFile(), putFileAs()
bool|string	Success or path	put()

Exception Handling

• src/Contracts/Filesystem.php50-55: readStreamRange() may throw RuntimeException when range requests are unsupported
• Other methods generally return failure indicators (false, null) rather than throwing exceptions
• Implementations may throw additional exceptions for I/O errors, authentication failures, or network issues

Nullable Parameter Conventions

Method	Nullable Parameter	Default Behavior
disk(?string $name)	$name	Returns default disk when null
files(?string $directory)	$directory	Lists files in root when null
allFiles(?string $directory)	$directory	Lists all files from root when null
directories(?string $directory)	$directory	Lists directories in root when null
allDirectories(?string $directory)	$directory	Lists all directories from root when null

Flexible Parameter Types

src/Contracts/Filesystem.php58-72

• put($path, $contents, $options): $contents accepts resource, StreamInterface, string, or UploadedFile
• delete($paths): Accepts single string or array of strings
• putFile() and putFileAs(): Use mixed type parameters to support multiple calling conventions

Sources: src/Contracts/Filesystem.php1-156 src/Contracts/Cloud.php1-14

---

Extension Methods Pattern

The package uses an extension method pattern where drivers can provide additional functionality beyond interface requirements:

Extension Methods Not in Cloud Interface

Method	Purpose	Implementations
temporaryUrl(path, expiration)	Generate time-limited signed URL	LocalFilesystemAdapter, AwsS3V3Adapter, GoogleCloudStorageAdapter
temporaryUploadUrl(path, expiration)	Generate pre-signed upload URL	AwsS3V3Adapter
providesTemporaryUrls()	Check if signed URLs are supported	LocalFilesystemAdapter, AwsS3V3Adapter, GoogleCloudStorageAdapter

Usage Pattern

Check for method existence at runtime:

This pattern enables:

• Feature evolution without breaking interface contracts
• Driver-specific capabilities
• Backward compatibility
• Graceful feature degradation

Sources: src/Contracts/Cloud.php1-14

---

Contract to Implementation Flow

Sources: src/Contracts/Factory.php1-14 src/Contracts/Filesystem.php1-156 src/Contracts/Cloud.php1-14