Local Filesystem Driver

Purpose and Scope

This document covers the LocalFilesystemAdapter class, which provides local disk storage capabilities within the Hypervel Filesystem package. The local driver stores files directly on the server's filesystem, making it suitable for development environments, self-hosted applications, or scenarios where files should be stored on attached storage volumes.

For information about the base adapter functionality shared across all drivers, see Driver Architecture and FilesystemAdapter. For cloud-based storage options with object pooling, see Cloud Storage Drivers.

---

Overview

The LocalFilesystemAdapter extends FilesystemAdapter to provide filesystem operations on local disk storage. It supports all core filesystem operations (read, write, delete, copy, move) and can generate signed URLs for secure file access when integrated with a URL generator.

Unlike cloud storage drivers (S3, GCS), the local driver:

• Does not use connection pooling (not needed for local I/O)
• Supports file locking via LockableFile (see File Locking)
• Stores files directly on the server's filesystem
• Can serve files through the web server or generate signed URLs for controlled access

Sources: src/LocalFilesystemAdapter.php1-92

---

Configuration

Basic Structure

The local driver is configured in config/autoload/filesystems.php. The package provides two preconfigured local disks by default:

Disk Name	Purpose	Root Directory	Default Visibility
local	Private file storage	storage/app/private	private
public	Public file storage	storage/app/public	public

Sources: publish/filesystems.php32-45

Private Disk Configuration

The private disk is intended for files that should not be directly web-accessible. Files are stored under storage/app/private by default.

Configuration Keys:

• driver: Must be 'local'
• root: Absolute path to the storage directory
• throw: Whether to throw exceptions on filesystem errors (default: false)

Sources: publish/filesystems.php33-37

Public Disk Configuration

The public disk is intended for web-accessible files. The url key defines the base URL for accessing files through the web server (typically via a symbolic link from public/storage to storage/app/public).

Configuration Keys:

• driver: Must be 'local'
• root: Absolute path to the storage directory
• url: Base URL for public file access
• visibility: Default visibility for new files ('public' or 'private')
• throw: Whether to throw exceptions on filesystem errors

Sources: publish/filesystems.php39-45

Configuration Options Reference

Option	Type	Required	Description
driver	string	Yes	Must be 'local'
root	string	Yes	Absolute path to storage directory
url	string	No	Base URL for public file access
visibility	string	No	Default visibility: 'public' or 'private'
throw	bool	No	Throw exceptions on errors (default: false)
permissions.file.public	int	No	Unix permissions for public files (e.g., 0644)
permissions.file.private	int	No	Unix permissions for private files (e.g., 0600)
permissions.dir.public	int	No	Unix permissions for public directories (e.g., 0755)
permissions.dir.private	int	No	Unix permissions for private directories (e.g., 0700)
lock	int	No	Locking strategy: LOCK_SH, LOCK_EX, LOCK_NB

Sources: publish/filesystems.php33-45 src/LocalFilesystemAdapter.php1-92

---

Architecture

Class Structure

The LocalFilesystemAdapter extends FilesystemAdapter and inherits all base filesystem operations. It adds local-specific functionality for signed URL generation and disk naming.

Sources: src/LocalFilesystemAdapter.php12-14 src/LocalFilesystemAdapter.php19-29

Component Relationships

Creation Flow:

1. FilesystemManager calls createLocalDriver() with configuration
2. Creates LocalFilesystemAdapter instance
3. Calls diskName() to set the disk identifier
4. Optionally calls shouldServeSignedUrls() to enable signed URL support
5. Returns the configured adapter instance

Sources: src/LocalFilesystemAdapter.php12-92

---

Disk Name Configuration

The LocalFilesystemAdapter requires a disk name to be set for proper identification, especially when generating signed URLs. The disk name is set via the diskName() method.

The disk name is stored in the $disk property src/LocalFilesystemAdapter.php19 and used when constructing signed URL routes src/LocalFilesystemAdapter.php61

Implementation:

• The diskName() method accepts a string parameter and returns $this for method chaining
• Located at src/LocalFilesystemAdapter.php73-78

Sources: src/LocalFilesystemAdapter.php17-19 src/LocalFilesystemAdapter.php73-78

---

Signed URL Generation

Overview

The local filesystem driver can generate temporary signed URLs for secure file access. This feature requires integration with a URL generator (typically from the hypervel/http package) and proper route configuration.

Signed URL Flow

Sources: src/LocalFilesystemAdapter.php44-66

Configuration Requirements

To enable signed URL generation for local disks, three components must be configured:

1. Call shouldServeSignedUrls() on the adapter:

   Located at src/LocalFilesystemAdapter.php85-91

2. Provide a URL generator resolver: A closure that returns a URL generator instance (from hypervel/http or similar)

3. Define a signed route: The route name must be 'storage.' . $diskName (e.g., 'storage.local')

Sources: src/LocalFilesystemAdapter.php85-91

Method: providesTemporaryUrls()

Located at src/LocalFilesystemAdapter.php34-39

Returns true if the adapter can generate temporary URLs. This occurs when:

• A custom temporaryUrlCallback is set (inherited from FilesystemAdapter), OR
• Both shouldServeSignedUrls is true AND urlGeneratorResolver is a valid closure

Sources: src/LocalFilesystemAdapter.php34-39

Method: temporaryUrl()

Located at src/LocalFilesystemAdapter.php44-66

Generates a temporary signed URL for the given file path.

Parameters:

• string $path: The file path relative to the disk root
• DateTimeInterface $expiration: When the URL should expire
• array $options: Additional options (merged into route parameters)

Returns: string - The signed URL

Exception: Throws RuntimeException if the driver doesn't support temporary URLs

Logic:

1. If temporaryUrlCallback exists, execute it and return the result src/LocalFilesystemAdapter.php46-52
2. Check if temporary URLs are supported via providesTemporaryUrls() src/LocalFilesystemAdapter.php54-56
3. Resolve the URL generator via urlGeneratorResolver src/LocalFilesystemAdapter.php58
4. Generate a signed route using temporarySignedRoute() with route name 'storage.' . $this->disk src/LocalFilesystemAdapter.php60-65
5. Convert the route to a full URL using to() src/LocalFilesystemAdapter.php60

Sources: src/LocalFilesystemAdapter.php44-66

Signed URL Properties

Property	Type	Location	Purpose
$disk	string	src/LocalFilesystemAdapter.php19	Disk identifier for route naming
$shouldServeSignedUrls	bool	src/LocalFilesystemAdapter.php24	Flag to enable signed URL serving
$urlGeneratorResolver	Closure|null	src/LocalFilesystemAdapter.php29	Resolver for URL generator instance

Sources: src/LocalFilesystemAdapter.php17-29

---

Features and Limitations

Supported Features

Feature	Supported	Notes
CRUD Operations	✓	Read, write, delete, copy, move
Directory Operations	✓	List, create, delete directories
Metadata	✓	Size, lastModified, mimeType, visibility
Streaming	✓	readStream, writeStream
File Locking	✓	Via LockableFile class (see File Locking)
Visibility Control	✓	Public/private via Unix permissions
Signed URLs	✓	Requires URL generator integration
Public URLs	✓	Via url configuration option
HTTP Responses	✓	Via response() and download() methods
Chunked Uploads	✓	Via putFile() and putFileAs()

Sources: src/LocalFilesystemAdapter.php1-92

Limitations

Limitation	Reason
No Connection Pooling	Local I/O doesn't benefit from pooling
Server-bound Storage	Files stored on single server (not distributed)
Scalability	Limited by single server's disk capacity and I/O
Signed URLs Require Integration	Needs URL generator from hypervel/http or similar

Sources: src/LocalFilesystemAdapter.php1-92

---

Method Chain Configuration Pattern

The LocalFilesystemAdapter uses a fluent interface for configuration, allowing method chaining:

Both diskName() and shouldServeSignedUrls() return $this (or static for inheritance support), enabling this pattern:

Sources: src/LocalFilesystemAdapter.php73-78 src/LocalFilesystemAdapter.php85-91

---

Integration with FilesystemManager

The FilesystemManager creates LocalFilesystemAdapter instances through its driver creation methods. The local driver is not wrapped in a FilesystemPoolProxy because local filesystem operations don't require connection pooling.

Key Points:

• Local adapters are cached in FilesystemManager::$disks for reuse
• The 'local' driver string maps to the createLocalDriver() method
• No pooling configuration is used for local drivers

Sources: src/LocalFilesystemAdapter.php12

---

Conditional Usage with Conditionable Trait

The LocalFilesystemAdapter uses the Conditionable trait src/LocalFilesystemAdapter.php14 enabling conditional method execution:

This provides a clean way to conditionally configure the adapter based on runtime conditions.

Sources: src/LocalFilesystemAdapter.php9 src/LocalFilesystemAdapter.php14

---

Comparison: Local vs Cloud Drivers

Aspect	LocalFilesystemAdapter	AwsS3V3Adapter / GoogleCloudStorageAdapter
Base Class	FilesystemAdapter	FilesystemAdapter
Connection Pooling	No (not beneficial)	Yes (via FilesystemPoolProxy)
Signed URLs	Via URL generator integration	Native support via SDK
File Locking	Supported via LockableFile	Not applicable
Storage Location	Server filesystem	Remote object storage
Scalability	Single server	Distributed, highly scalable
Configuration Complexity	Low	Higher (credentials, regions, etc.)
Cost	Server storage only	Per-request and storage costs

Sources: src/LocalFilesystemAdapter.php12

---

Usage Example

Basic Configuration

Accessing the Driver

Signed URLs (when configured)

Sources: publish/filesystems.php33-45 src/LocalFilesystemAdapter.php44-66