349 lines
10 KiB
Markdown
349 lines
10 KiB
Markdown
# FileSystem Package Gap Analysis
|
|
|
|
## Overview
|
|
|
|
This document analyzes the gaps between our current filesystem handling (in Core package) and Laravel's FileSystem package functionality, identifying what needs to be implemented as a standalone FileSystem package.
|
|
|
|
> **Related Documentation**
|
|
> - See [FileSystem Package Specification](filesystem_package_specification.md) for current implementation
|
|
> - See [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md) for overall status
|
|
> - See [Foundation Integration Guide](foundation_integration_guide.md) for integration patterns
|
|
> - See [Testing Guide](testing_guide.md) for testing approaches
|
|
> - See [Getting Started Guide](getting_started.md) for development setup
|
|
|
|
## Implementation Gaps
|
|
|
|
### 1. Missing Package Structure
|
|
```dart
|
|
// Need to create dedicated FileSystem package:
|
|
|
|
packages/filesystem/
|
|
├── lib/
|
|
│ ├── src/
|
|
│ │ ├── filesystem.dart
|
|
│ │ ├── filesystem_manager.dart
|
|
│ │ ├── drivers/
|
|
│ │ │ ├── local_driver.dart
|
|
│ │ │ ├── s3_driver.dart
|
|
│ │ │ └── gcs_driver.dart
|
|
│ │ └── contracts/
|
|
│ │ ├── filesystem.dart
|
|
│ │ └── driver.dart
|
|
│ └── filesystem.dart
|
|
├── test/
|
|
└── example/
|
|
```
|
|
|
|
### 2. Missing Core Features
|
|
```dart
|
|
// 1. Filesystem Manager
|
|
class FilesystemManager {
|
|
// Need to implement:
|
|
Filesystem disk([String? name]);
|
|
void extend(String driver, FilesystemDriver Function() callback);
|
|
FilesystemDriver createDriver(Map<String, dynamic> config);
|
|
}
|
|
|
|
// 2. Filesystem Implementation
|
|
class Filesystem {
|
|
// Need to implement:
|
|
Future<bool> exists(String path);
|
|
Future<String> get(String path);
|
|
Future<void> put(String path, dynamic contents, [Map<String, String>? options]);
|
|
Future<void> delete(String path);
|
|
Future<void> copy(String from, String to);
|
|
Future<void> move(String from, String to);
|
|
Future<String> url(String path);
|
|
Future<Stream<List<int>>> readStream(String path);
|
|
Future<void> writeStream(String path, Stream<List<int>> contents);
|
|
}
|
|
|
|
// 3. Driver Implementations
|
|
class LocalDriver {
|
|
// Need to implement:
|
|
Future<void> ensureDirectory(String path);
|
|
Future<void> setVisibility(String path, String visibility);
|
|
Future<Map<String, dynamic>> getMetadata(String path);
|
|
}
|
|
```
|
|
|
|
### 3. Missing Laravel Features
|
|
```dart
|
|
// 1. Cloud Storage
|
|
class S3Driver {
|
|
// Need to implement:
|
|
Future<void> upload(String path, dynamic contents, String visibility);
|
|
Future<String> temporaryUrl(String path, Duration expiration);
|
|
Future<void> setVisibility(String path, String visibility);
|
|
}
|
|
|
|
// 2. Directory Operations
|
|
class DirectoryOperations {
|
|
// Need to implement:
|
|
Future<List<String>> files(String directory);
|
|
Future<List<String>> allFiles(String directory);
|
|
Future<List<String>> directories(String directory);
|
|
Future<List<String>> allDirectories(String directory);
|
|
Future<void> makeDirectory(String path);
|
|
Future<void> deleteDirectory(String directory);
|
|
}
|
|
|
|
// 3. File Visibility
|
|
class VisibilityConverter {
|
|
// Need to implement:
|
|
String toOctal(String visibility);
|
|
String fromOctal(String permissions);
|
|
bool isPublic(String path);
|
|
bool isPrivate(String path);
|
|
}
|
|
```
|
|
|
|
## Integration Gaps
|
|
|
|
### 1. Container Integration
|
|
```dart
|
|
// Need to implement:
|
|
|
|
class FilesystemServiceProvider {
|
|
void register() {
|
|
// Register filesystem manager
|
|
container.singleton<FilesystemManager>((c) =>
|
|
FilesystemManager(
|
|
config: c.make<ConfigContract>()
|
|
)
|
|
);
|
|
|
|
// Register default filesystem
|
|
container.singleton<Filesystem>((c) =>
|
|
c.make<FilesystemManager>().disk()
|
|
);
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Config Integration
|
|
```dart
|
|
// Need to implement:
|
|
|
|
// config/filesystems.dart
|
|
class FilesystemsConfig {
|
|
static Map<String, dynamic> get config => {
|
|
'default': 'local',
|
|
'disks': {
|
|
'local': {
|
|
'driver': 'local',
|
|
'root': 'storage/app'
|
|
},
|
|
's3': {
|
|
'driver': 's3',
|
|
'key': env('AWS_ACCESS_KEY_ID'),
|
|
'secret': env('AWS_SECRET_ACCESS_KEY'),
|
|
'region': env('AWS_DEFAULT_REGION'),
|
|
'bucket': env('AWS_BUCKET')
|
|
}
|
|
}
|
|
};
|
|
}
|
|
```
|
|
|
|
### 3. Event Integration
|
|
```dart
|
|
// Need to implement:
|
|
|
|
class FilesystemEvents {
|
|
// File events
|
|
static const String writing = 'filesystem.writing';
|
|
static const String written = 'filesystem.written';
|
|
static const String deleting = 'filesystem.deleting';
|
|
static const String deleted = 'filesystem.deleted';
|
|
|
|
// Directory events
|
|
static const String makingDirectory = 'filesystem.making_directory';
|
|
static const String madeDirectory = 'filesystem.made_directory';
|
|
static const String deletingDirectory = 'filesystem.deleting_directory';
|
|
static const String deletedDirectory = 'filesystem.deleted_directory';
|
|
}
|
|
```
|
|
|
|
## Documentation Gaps
|
|
|
|
### 1. Missing API Documentation
|
|
```dart
|
|
// Need to document:
|
|
|
|
/// Manages filesystem operations across multiple storage drivers.
|
|
///
|
|
/// Provides a unified API for working with files across different storage systems:
|
|
/// ```dart
|
|
/// // Store a file
|
|
/// await storage.put('avatars/user1.jpg', fileContents);
|
|
///
|
|
/// // Get a file
|
|
/// var contents = await storage.get('avatars/user1.jpg');
|
|
/// ```
|
|
class Filesystem {
|
|
/// Stores a file at the specified path.
|
|
///
|
|
/// Options can include:
|
|
/// - visibility: 'public' or 'private'
|
|
/// - mime: MIME type of the file
|
|
Future<void> put(String path, dynamic contents, [Map<String, String>? options]);
|
|
}
|
|
```
|
|
|
|
### 2. Missing Usage Examples
|
|
```dart
|
|
// Need examples for:
|
|
|
|
// 1. Basic File Operations
|
|
var storage = Storage.disk();
|
|
await storage.put('file.txt', 'Hello World');
|
|
var contents = await storage.get('file.txt');
|
|
await storage.delete('file.txt');
|
|
|
|
// 2. Stream Operations
|
|
var fileStream = File('large.zip').openRead();
|
|
await storage.writeStream('uploads/large.zip', fileStream);
|
|
var downloadStream = await storage.readStream('uploads/large.zip');
|
|
|
|
// 3. Cloud Storage
|
|
var s3 = Storage.disk('s3');
|
|
await s3.put(
|
|
'images/photo.jpg',
|
|
photoBytes,
|
|
{'visibility': 'public'}
|
|
);
|
|
var url = await s3.url('images/photo.jpg');
|
|
```
|
|
|
|
### 3. Missing Test Coverage
|
|
```dart
|
|
// Need tests for:
|
|
|
|
void main() {
|
|
group('Local Driver', () {
|
|
test('handles file operations', () async {
|
|
var storage = Filesystem(LocalDriver(root: 'storage'));
|
|
|
|
await storage.put('test.txt', 'contents');
|
|
expect(await storage.exists('test.txt'), isTrue);
|
|
expect(await storage.get('test.txt'), equals('contents'));
|
|
|
|
await storage.delete('test.txt');
|
|
expect(await storage.exists('test.txt'), isFalse);
|
|
});
|
|
});
|
|
|
|
group('S3 Driver', () {
|
|
test('handles cloud operations', () async {
|
|
var storage = Filesystem(S3Driver(config));
|
|
|
|
await storage.put('test.txt', 'contents', {
|
|
'visibility': 'public'
|
|
});
|
|
|
|
var url = await storage.url('test.txt');
|
|
expect(url, startsWith('https://'));
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
## Implementation Priority
|
|
|
|
1. **High Priority**
|
|
- Create FileSystem package structure
|
|
- Implement core filesystem
|
|
- Add local driver
|
|
- Add basic operations
|
|
|
|
2. **Medium Priority**
|
|
- Add cloud drivers
|
|
- Add streaming support
|
|
- Add directory operations
|
|
- Add container integration
|
|
|
|
3. **Low Priority**
|
|
- Add helper functions
|
|
- Add testing utilities
|
|
- Add debugging tools
|
|
|
|
## Next Steps
|
|
|
|
1. **Package Creation**
|
|
- Create package structure
|
|
- Move filesystem code from Core
|
|
- Add package dependencies
|
|
- Setup testing
|
|
|
|
2. **Core Implementation**
|
|
- Implement FilesystemManager
|
|
- Implement Filesystem
|
|
- Implement LocalDriver
|
|
- Add cloud drivers
|
|
|
|
3. **Integration Implementation**
|
|
- Add container integration
|
|
- Add config support
|
|
- Add event support
|
|
- Add service providers
|
|
|
|
Would you like me to:
|
|
1. Create the FileSystem package structure?
|
|
2. Start implementing core features?
|
|
3. Create detailed implementation plans?
|
|
|
|
## Development Guidelines
|
|
|
|
### 1. Getting Started
|
|
Before implementing filesystem features:
|
|
1. Review [Getting Started Guide](getting_started.md)
|
|
2. Check [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Follow [Testing Guide](testing_guide.md)
|
|
4. Use [Foundation Integration Guide](foundation_integration_guide.md)
|
|
5. Review [FileSystem Package Specification](filesystem_package_specification.md)
|
|
|
|
### 2. Implementation Process
|
|
For each filesystem feature:
|
|
1. Write tests following [Testing Guide](testing_guide.md)
|
|
2. Implement following Laravel patterns
|
|
3. Document following [Getting Started Guide](getting_started.md#documentation)
|
|
4. Integrate following [Foundation Integration Guide](foundation_integration_guide.md)
|
|
|
|
### 3. Quality Requirements
|
|
All implementations must:
|
|
1. Pass all tests (see [Testing Guide](testing_guide.md))
|
|
2. Meet Laravel compatibility requirements
|
|
3. Follow integration patterns (see [Foundation Integration Guide](foundation_integration_guide.md))
|
|
4. Match specifications in [FileSystem Package Specification](filesystem_package_specification.md)
|
|
|
|
### 4. Integration Considerations
|
|
When implementing filesystem features:
|
|
1. Follow patterns in [Foundation Integration Guide](foundation_integration_guide.md)
|
|
2. Ensure Laravel compatibility per [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Use testing approaches from [Testing Guide](testing_guide.md)
|
|
4. Follow development setup in [Getting Started Guide](getting_started.md)
|
|
|
|
### 5. Performance Guidelines
|
|
Filesystem system must:
|
|
1. Handle large files efficiently
|
|
2. Use streaming where appropriate
|
|
3. Minimize memory usage
|
|
4. Support concurrent operations
|
|
5. Meet performance targets in [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md#performance-benchmarks)
|
|
|
|
### 6. Testing Requirements
|
|
Filesystem tests must:
|
|
1. Cover all file operations
|
|
2. Test streaming behavior
|
|
3. Verify cloud storage
|
|
4. Check metadata handling
|
|
5. Follow patterns in [Testing Guide](testing_guide.md)
|
|
|
|
### 7. Documentation Requirements
|
|
Filesystem documentation must:
|
|
1. Explain filesystem patterns
|
|
2. Show driver examples
|
|
3. Cover error handling
|
|
4. Include performance tips
|
|
5. Follow standards in [Getting Started Guide](getting_started.md#documentation)
|