- How do I use this package with Laravel’s Storage facade?
- This package doesn’t integrate directly with Laravel’s Storage facade. You’ll need to manually register the stream wrapper with your Flysystem adapter, then use `fly://` paths in native PHP functions like `file_put_contents`. For Laravel-specific storage, bind the Flysystem adapter to the facade via `Storage::extend()`.
- Does this work with Laravel’s filesystem caching?
- No, this package bypasses Laravel’s filesystem caching layer. If caching is critical, implement custom filesystem events or use Laravel’s native Flysystem integration instead of stream wrappers.
- Which Laravel versions are supported?
- This package doesn’t enforce Laravel-specific dependencies, but it requires PHP 8.1+ (fixed in v1.4.1). Test thoroughly with Laravel 9+ or 10+ for compatibility, as stream wrappers may interact unpredictably with Laravel’s filesystem abstractions.
- Can I use this with S3 or other cloud storage?
- Yes, this works with any Flysystem v2/v3 adapter, including S3 (via `league/flysystem-aws-s3-v3`). Register your cloud adapter with the stream wrapper, then use `fly://` paths in native PHP functions.
- How do I handle errors like ‘stream wrapper is not supported’?
- Ensure the stream wrapper is registered before use (e.g., `FlysystemStreamWrapper::register('fly', $filesystem)`). For debugging, enable `collectErrorMessage` in config or log warnings via `error_log`. PR #23 improves error handling for invalid `fly://` URLs.
- Will this break existing Laravel file uploads or downloads?
- No, but only use `fly://` paths for operations handled by this wrapper. Native Laravel uploads/downloads (e.g., `Storage::put()`) remain unaffected. Test hybrid workflows carefully, as stream wrappers may not support all Flysystem features.
- How do I configure file locking for concurrent access?
- Use the `LOCK_STORE` and `LOCK_TTL` options during registration. Example: `FlysystemStreamWrapper::register('fly', $filesystem, [LOCK_STORE => 'flock:///tmp', LOCK_TTL => 300])`. Defaults to `/tmp` with a 5-minute TTL.
- Are there performance implications for Laravel apps?
- No direct performance impact, but stream wrappers bypass Laravel’s filesystem caching. For high-traffic apps, consider caching responses manually or using Laravel’s native Flysystem integration instead.
- What’s the alternative if I need Laravel-specific features?
- Use Laravel’s built-in Flysystem integration (`league/flysystem`) via `Storage::extend()`. This provides caching, events, and Laravel-specific optimizations, though it lacks native `fly://` path support.
- How do I test this in a Laravel CI pipeline?
- Mock the stream wrapper registration in tests (e.g., `FlysystemStreamWrapper::register()`). Avoid real filesystem operations; use in-memory adapters (e.g., `league/flysystem-memory`) for unit tests. Test edge cases like concurrent writes with locking.