Flysystem Webdav Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require league/flysystem-webdav
   

2. Basic Usage:

   use League\Flysystem\Filesystem;
   use League\Flysystem\WebDAV\WebDAVAdapter;
   
   $adapter = new WebDAVAdapter('https://example.com/webdav', [
       'username' => 'your_username',
       'password' => 'your_password',
   ]);
   
   $filesystem = new Filesystem($adapter);
   

3. First Use Case: Upload a file:

   $filesystem->write('remote/path/file.txt', 'Hello, WebDAV!');
   

   List files:

   $files = $filesystem->listContents('remote/path');
   

Where to Look First

• Official Flysystem WebDAV Documentation (primary source).
• Sabre/Dav Library: Understand WebDAV limitations (e.g., no atomic writes, partial support for metadata).
• League/Flysystem Issues: Check for known WebDAV-specific edge cases (e.g., GitHub Issues).

Implementation Patterns

Common Workflows

1. File Operations:

   • Upload/Download:

     // Upload from local to WebDAV
     $filesystem->writeStream('remote/file.jpg', fopen('local.jpg', 'r'));
     
     // Download to local
     $file = $filesystem->readStream('remote/file.jpg');
     file_put_contents('local_copy.jpg', $file);
     

   • Directory Handling:

     $filesystem->createDir('remote/new_folder');
     $filesystem->delete('remote/unwanted_file.txt');
     

2. Metadata and Visibility:

   • Set custom metadata (if supported by server):

     $filesystem->fileMetadata('remote/file.txt', ['custom' => 'value']);
     

   • Toggle visibility (if server supports it):

     $filesystem->setVisibility('remote/file.txt', 'hidden');
     

3. Streaming Large Files: Use writeStream()/readStream() to avoid memory issues with large files:

   $filesystem->writeStream('remote/large_video.mp4', fopen('local_video.mp4', 'r'));
   

4. Error Handling: Wrap operations in try-catch for WebDAV-specific errors (e.g., authentication, server timeouts):

   try {
       $filesystem->write('remote/file.txt', 'content');
   } catch (\League\Flysystem\WebDAV\Exception\WebDAVException $e) {
       // Handle WebDAV errors (e.g., retry or log)
   }
   

Integration Tips

• Laravel Filesystem: Add to config/filesystems.php:

  'webdav' => [
      'driver' => 'webdav',
      'url' => env('WEBDAV_URL'),
      'username' => env('WEBDAV_USERNAME'),
      'password' => env('WEBDAV_PASSWORD'),
      'options' => [
          'use_ssl' => true,
          'verify_peer' => false, // Disable if using self-signed certs
      ],
  ],
  

  Then use via Storage::disk('webdav').

• Caching: Disable caching if WebDAV server doesn’t support ETag/Last-Modified headers:

  $adapter = new WebDAVAdapter('https://example.com', [
      'cache' => false,
  ]);
  

• Proxy Support: Configure proxy settings if behind a corporate network:

  $adapter = new WebDAVAdapter('https://example.com', [
      'proxy' => [
          'http' => 'http://proxy.example.com:8080',
          'https' => 'http://proxy.example.com:8080',
      ],
  ]);
  

Gotchas and Tips

Pitfalls

1. Authentication Issues:

   • Basic Auth: Ensure credentials are correct and the server supports Basic Auth.
   • Preemptive Auth: Some servers require preemptive authentication. Use:

     $adapter = new WebDAVAdapter('https://example.com', [
         'auth' => ['username', 'password'],
         'preemptive_auth' => true,
     ]);
     

   • OAuth/Token Auth: Not natively supported. Use a custom HttpClient (e.g., Guzzle with middleware).

2. Server-Specific Quirks:

   • Case Sensitivity: WebDAV paths are often case-sensitive. Normalize paths:

     $filesystem->write(strtolower('Remote/Path/File.txt'), 'content');
     

   • No Atomic Writes: WebDAV lacks atomic operations. Use temporary files or external locking.
   • Metadata Limitations: Not all servers support custom metadata. Test with fileMetadata().

3. Performance:

   • Slow Servers: Add timeouts to avoid hanging:

     $adapter = new WebDAVAdapter('https://example.com', [
         'connect_timeout' => 10,
         'timeout' => 30,
     ]);
     

   • Large Directories: listContents() may time out. Use pagination or server-side filtering if available.

4. SSL/TLS:

   • Self-Signed Certs: Disable verification (not recommended for production):

     $adapter = new WebDAVAdapter('https://example.com', [
         'verify_peer' => false,
         'verify_host' => false,
     ]);
     

   • Certificates: For production, use a valid certificate or add custom CA bundle.

5. Partial Support:

   • Symlinks: Not all WebDAV servers support symlinks. Test with createSymlink().
   • Hard Links: Rarely supported. Avoid unless confirmed.

Debugging Tips

1. Enable Verbose Logging: Use Sabre/Dav’s debug mode to inspect requests/responses:

   $adapter = new WebDAVAdapter('https://example.com', [
       'debug' => true,
   ]);
   

   Logs will appear in storage/logs/laravel.log (Laravel) or stderr.

2. Inspect Headers: Add a custom HttpClient to log headers (e.g., using Guzzle):

   $client = new \GuzzleHttp\Client([
       'handler' => \GuzzleHttp\HandlerStack::create([
           new \GuzzleHttp\Middleware::tap(function ($request) {
               \Log::debug('Request:', [
                   'url' => (string) $request->getUri(),
                   'headers' => $request->getHeaders(),
               ]);
           }),
       ]),
   ]);
   $adapter = new WebDAVAdapter('https://example.com', ['http_client' => $client]);
   

3. Common Errors:

   • 401 Unauthorized: Check credentials or enable preemptive auth.
   • 403 Forbidden: Verify file permissions or server ACLs.
   • 507 Insufficient Storage: Server-side quota exceeded.
   • 501 Not Implemented: Server lacks support for an operation (e.g., PROPPATCH).

Extension Points

1. Custom HTTP Client: Replace the default client (Guzzle) for advanced features (e.g., retries, custom headers):

   $client = new \GuzzleHttp\Client(['timeout' => 60]);
   $adapter = new WebDAVAdapter('https://example.com', ['http_client' => $client]);
   

2. Event Dispatching: Use Flysystem’s events to hook into file operations:

   $filesystem->addListener('file.*', function ($event) {
       \Log::info('File event:', $event->getArgument('path'));
   });
   

3. Adapter Wrappers: Chain adapters for local fallback or caching:

   use League\Flysystem\Cached\CachedAdapter;
   use League\Flysystem\Cached\Storage\MemoryStorage;
   
   $cache = new MemoryStorage();
   $cachedAdapter = new CachedAdapter($adapter, $cache);
   $filesystem = new Filesystem($cachedAdapter);
   

4. Sabre/Dav Extensions: Extend Sabre/Dav’s behavior by subclassing WebDAVAdapter and overriding methods like createFile() or delete(). Example:

   class CustomWebDAVAdapter extends WebDAVAdapter {
       protected function createFile($path, $source = null) {
           // Custom logic (e.g., pre-process content)
           return parent::createFile($path, $source);
       }
   }