Wopi Lib Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require champs-libres/wopi-lib
   

   Add the service provider to config/app.php (if using Laravel):

   ChampsLibres\WopiLib\WopiLibServiceProvider::class,
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="ChampsLibres\WopiLib\WopiLibServiceProvider" --tag="wopi-config"
   

   Update config/wopi.php with your WOPI endpoint details (e.g., host, scheme, baseUrl).

3. First Use Case: File Check Create a controller to handle WOPI requests:

   use ChampsLibres\WopiLib\Wopi;
   
   class WopiController extends Controller
   {
       public function checkFile(Request $request)
       {
           $wopi = new Wopi(config('wopi'));
           $response = $wopi->checkFile($request->all());
   
           return response()->json($response);
       }
   }
   

4. Routing Define a route for WOPI requests (e.g., /wopi/checkfile):

   Route::post('/wopi/checkfile', [WopiController::class, 'checkFile']);
   

Implementation Patterns

Core Workflows

1. WOPI Endpoint Handling Use the Wopi facade or class to handle standard WOPI actions:

   $wopi = new Wopi(config('wopi'));
   
   // Check file
   $checkResponse = $wopi->checkFile($request->all());
   
   // Lock file
   $lockResponse = $wopi->lockFile($request->all());
   
   // Get file info
   $fileInfo = $wopi->getFileInfo($request->all());
   

2. Middleware for Authentication Secure WOPI endpoints with middleware (e.g., API token validation):

   Route::middleware(['auth:wopi'])->post('/wopi/{action}', [WopiController::class, 'handleAction']);
   

   Create a custom middleware to validate WOPI headers (e.g., Authorization, X-WOPI-Override).

3. Integration with Storage Extend the library to work with Laravel’s filesystem or custom storage:

   $wopi->setStorage(new LaravelFilesystemAdapter(storage_path('app/wopi')));
   

4. Async Processing Offload heavy operations (e.g., file conversion) to queues:

   dispatch(new ProcessWopiFile($request->all()))->onQueue('wopi');
   

Advanced Patterns

1. Custom Actions Extend the library to support non-standard WOPI actions:

   class CustomWopiAction extends \ChampsLibres\WopiLib\Actions\BaseAction
   {
       public function execute(array $params)
       {
           // Custom logic
           return ['success' => true, 'data' => []];
       }
   }
   

   Register the action in config/wopi.php:

   'actions' => [
       'custom' => \App\Actions\CustomWopiAction::class,
   ],
   

2. CORS and Headers Configure CORS for WOPI clients (e.g., Office Online):

   Header::set('Access-Control-Allow-Origin', '*');
   Header::set('Access-Control-Allow-Methods', 'POST, OPTIONS');
   

3. Logging and Monitoring Log WOPI requests/responses for debugging:

   $wopi->setLogger(new SingleChannelAdapter([
       new StreamHandler(storage_path('logs/wopi.log'), Logger::DEBUG),
   ]));
   

4. Testing Mock WOPI responses in tests:

   $wopi = new Wopi(config('wopi'));
   $wopi->setHttpClient(new MockHttpClient());
   

Gotchas and Tips

Common Pitfalls

1. CSRF and Security

   • WOPI endpoints must not use Laravel’s CSRF protection. Exclude them in VerifyCsrfToken middleware:

     protected $except = [
         '/wopi/*',
     ];
     

   • Validate X-WOPI-Override headers to prevent CSRF attacks.

2. File Locking Conflicts

   • Ensure your storage adapter handles file locks atomically. Test with concurrent requests.
   • Use wopi->lockFile() with exclusive mode for critical operations.

3. URL and BasePath Issues

   • WOPI clients (e.g., Office Online) require absolute URLs for FileUrl and BaseFileUrl. Use Laravel’s url() helper:

     'BaseFileUrl' => url('/wopi/files/'),
     

   • Avoid relative paths in responses.

4. Timeouts

   • WOPI operations (e.g., file uploads) may time out. Configure PHP’s max_execution_time or use Laravel’s queue:work --timeout=3600.

5. Case Sensitivity

   • WOPI actions (e.g., checkfile, lock) are case-sensitive. Stick to lowercase in routes and config.

Debugging Tips

1. Enable Verbose Logging Set the logger to DEBUG in config/wopi.php:

   'log_level' => \Monolog\Logger::DEBUG,
   

2. Validate WOPI Headers Use dd($request->header()) to inspect incoming WOPI headers (e.g., Authorization, X-WOPI-Override).

3. Test with WOPI Client Use Office Online or OnlyOffice to test integration. Example WOPI request:

   POST /wopi/checkfile HTTP/1.1
   Host: yourdomain.com
   Authorization: Basic base64credentials
   X-WOPI-Override: YOUR_OVERRIDE
   

4. Check WOPI Spec Compliance Validate responses against the WOPI 2.0 spec. Example required fields:

   {
       "UserId": "user@example.com",
       "Access": "edit",
       "BaseFileUrl": "https://yourdomain.com/wopi/files/",
       "FileUrl": "https://yourdomain.com/wopi/files/123.docx",
       "Expires": "2025-12-31T23:59:59Z"
   }
   

Extension Points

1. Custom Storage Adapters Implement ChampsLibres\WopiLib\Contracts\StorageAdapter for S3, Database, etc.:

   class S3StorageAdapter implements StorageAdapter
   {
       public function read($fileId) { /* ... */ }
       public function write($fileId, $content) { /* ... */ }
       // ...
   }
   

2. Override HTTP Client Replace the default Guzzle client for custom behavior (e.g., retries):

   $wopi->setHttpClient(new CustomHttpClient());
   

3. Hook into Actions Extend BaseAction to modify responses:

   $wopi->extendAction('checkfile', function ($response) {
       $response['CustomField'] = 'value';
       return $response;
   });
   

4. Add Metadata Extend file info responses with custom metadata:

   $wopi->setFileInfoTransformer(function ($file) {
       return array_merge($file->toArray(), [
           'custom_metadata' => ['key' => 'value'],
       ]);
   });