💡 Feature Proposals for Post-1.0.0 Releases

[dereuromark]

Following the upcoming 1.0.0 stable release, I'd like to propose several features that would enhance the file-storage library.

🎯 Core Library Enhancements

1. Advanced Path Builders

Why: More flexibility in organizing files

Proposed Features:

• Date-based path builders (/2025/11/07/file.jpg)
• Hash-based sharding (/ab/cd/abcd1234.jpg)
• Custom path templates
• Configurable path strategies per collection

Example:

$pathBuilder = new DateHashPathBuilder([
    'pattern' => '{year}/{month}/{hash:2}/{hash:2}/{filename}',
    'hash' => 'md5',
]);

2. File Metadata Enhancement

Why: Richer metadata support for various file types

Features:

• Metadata extractors for different file types
• EXIF/IPTC/XMP extraction for images
• Video metadata (duration, codec, resolution)
• Audio metadata (artist, album, duration)
• PDF metadata (pages, author, creation date)
• Geo-location support

Example:

$file = $file->withMetadata([
    'exif' => $exifExtractor->extract($file),
    'geo' => ['lat' => 40.7128, 'lng' => -74.0060],
    'custom' => ['author' => 'John Doe'],
]);

3. File Validation Framework

Why: Centralized validation logic

Features:

• Configurable validators (size, type, dimensions)
• Virus scanning integration
• Content validation (image corruption detection)
• Custom validator interface

Example:

$validator = new FileValidator([
    'maxSize' => '10MB',
    'allowedTypes' => ['image/jpeg', 'image/png'],
    'virusScan' => true,
]);

if (!$validator->validate($file)) {
    throw new ValidationException($validator->getErrors());
}

4. Deduplication Support

Why: Save storage space and costs

Features:

• Hash-based deduplication
• Reference counting
• Smart cleanup (delete physical file when last reference removed)
• Deduplication across collections

Example:

$storage = new FileStorage($adapter, [
    'deduplicate' => true,
    'hashAlgorithm' => 'sha256',
]);

// If file with same hash exists, returns reference instead of uploading
$file = $storage->store($uploadedFile);

5. Streaming & Large File Support

Why: Handle large files efficiently

Features:

• Chunked uploads
• Streaming downloads
• Resume capability
• Memory-efficient processing

Example:

// Chunked upload
$uploader = new ChunkedUploader($storage);
$uploader->uploadChunk($fileId, $chunkData, $chunkIndex);

// Streaming download
$stream = $storage->stream($file->uuid());

6. File Transformation Interface

Why: Standardize file processing

Features:

• Generic transformation interface
• Chain transformations
• Async processing support
• Rollback on failure

Example:

$file = $storage->transform($file, [
    new ResizeTransformation(800, 600),
    new WatermarkTransformation('logo.png'),
    new OptimizeTransformation(),
]);

7. Storage Adapter Enhancements

Multi-Region Support

$storage = new MultiRegionAdapter([
    'primary' => $s3UsEast,
    'failover' => $s3UsWest,
    'read_preference' => 'nearest',
]);

Adapter Middleware

$adapter = new LocalAdapter('/path');
$adapter = new CachingMiddleware($adapter, $cache);
$adapter = new MetricsMiddleware($adapter, $metrics);
$adapter = new RetryMiddleware($adapter, ['max_attempts' => 3]);

8. Event System

Why: Extensibility and integration

Proposed Events:

• file.before_store
• file.after_store
• file.before_delete
• file.after_delete
• file.transformation.before
• file.transformation.after
• file.access (for analytics)

Example:

$storage->on('file.after_store', function($event) {
    Log::info('File stored: ' . $event->file->uuid());
});

9. Temporary Files & Cleanup

Why: Manage temporary uploads

Features:

• TTL-based automatic cleanup
• Temporary file marking
• Scheduled cleanup jobs
• Garbage collection

Example:

$file = $storage->storeTemporary($uploadedFile, [
    'ttl' => 3600, // 1 hour
]);

// Later, promote to permanent
$storage->promoteToPerment($file->uuid());

10. File Collections

Why: Group related files

Features:

• Collection grouping
• Batch operations on collections
• Collection-level permissions
• Collection metadata

Example:

$collection = $storage->createCollection('vacation-2025', [
    'metadata' => ['location' => 'Hawaii', 'date' => '2025-07-01'],
]);

$collection->add($file1, $file2, $file3);
$collection->delete(); // Delete all files in collection

🛠️ Technical Improvements

11. Type Safety Improvements

• Stricter type hints
• Readonly properties for immutable data
• Enums for constants

Example:

enum StorageVisibility: string {
    case Public = 'public';
    case Private = 'private';
}

readonly class FileMetadata {
    public function __construct(
        public int $size,
        public string $mimeType,
        public ?array $exif = null,
    ) {}
}

12. Better Error Handling

• Custom exception hierarchy
• More descriptive error messages
• Error context for debugging

Example:

class FileNotFoundException extends StorageException {}
class FileToolargeException extends ValidationException {}
class AdapterNotAvailableException extends StorageException {}

13. Testing Utilities

• Mock adapter for testing
• Test fixtures
• Factory methods

Example:

$storage = FileStorage::mock([
    'preset_files' => [
        'test-uuid' => File::create('test.jpg', 1024, 'image/jpeg'),
    ],
]);

📊 Suggested Roadmap

1.1.0 - Core Enhancements

• Advanced path builders
• Metadata enhancement
• File validation framework

1.2.0 - Storage Features

• Deduplication
• Streaming/chunked uploads
• Multi-region support

1.3.0 - Extensibility

• Event system
• Transformation interface
• Adapter middleware

2.0.0 - Modern PHP & Breaking Changes

• PHP 8.2+ requirement
• Enums and readonly properties
• Refined API based on 1.x learnings

🤔 Questions

1. Which features would be most valuable?
2. Any features missing from this list?
3. Would you contribute to any of these?
4. Preference for separate packages vs. core library?

💬 Feedback Welcome

See related discussion in cakephp-file-storage: dereuromark/cakephp-file-storage#13