Wopi Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric Design: The bundle is explicitly built for Symfony, leveraging its bundle architecture (Symfony 6.4+). This aligns well with applications already using Symfony, reducing architectural friction.
• WOPI Protocol Abstraction: Provides a standardized interface for WOPI (Web Application Open Platform Interface), abstracting low-level protocol handling. This is ideal for integrating Collabora Online or Microsoft Office 365 without reinventing the wheel.
• Decoupled Core Logic: Relies on champs-libres/wopi-lib for core WOPI logic, promoting modularity. The bundle itself focuses on routing, glue code, and Symfony integration, allowing customization of storage, security, and permissions via interfaces.
• Extensibility: Designed for future compatibility with Office for the Web (Microsoft), though currently Collabora-focused. This reduces risk of vendor lock-in if requirements evolve.

Integration Feasibility

• Low-Coupling: The bundle does not impose a specific storage backend (e.g., database, S3) or security model, making it adaptable to existing systems.
• Dependency Clarity: Requires champs-libres/wopi-lib (v2.0+) and Symfony components (e.g., http-client, framework-bundle). Compatibility with Symfony 6.4+ is confirmed, but older versions may need validation.
• Protocol Validation: WOPI compliance is not guaranteed out-of-the-box; the bundle enforces the protocol but delegates business logic (e.g., file access, permissions) to the application. This requires upfront planning for custom implementations.
• Middleware Integration: WOPI endpoints (e.g., /wopi/files/...) must be exposed via Symfony’s routing system. Potential conflicts with existing routes or security layers (e.g., API Platform, API Gateway) need assessment.

Technical Risk

• Protocol Complexity: WOPI involves intricate handshakes (e.g., CheckFileInfo, GetFile, Lock), error handling, and security tokens. Missteps in custom logic (e.g., permission checks) could break compatibility with clients like Collabora.
• Security Gaps: The bundle does not include built-in authentication/authorization. Integrating with Symfony’s security system (e.g., Firebase, OAuth) or custom logic is mandatory but adds complexity.
• Performance Overhead: WOPI operations (e.g., file streaming) may introduce latency if not optimized. The bundle’s abstraction layer could obscure bottlenecks in custom storage backends.
• Collabora-Specific Quirks: While designed for Collabora, undocumented behaviors (e.g., specific headers, timeouts) might emerge during testing. Microsoft Office 365 compatibility is untested.

Key Questions

1. Storage Backend: How will documents be stored/retrieved (e.g., database BLOBs, S3, filesystem)? Does the backend support streaming for large files?
2. Security Model: How will WOPI tokens/authentication map to your existing auth system (e.g., JWT, session-based)? Will you use Symfony’s security component or a custom solution?
3. Permission Logic: How will WOPI’s UserId/AccessToken translate to your application’s RBAC? Will you extend the WopiFile interface or use middleware?
4. Routing Conflicts: Are the default WOPI routes (/wopi/...) safe to use, or will they clash with existing endpoints? Will you use Symfony’s route prefix or custom routing?
5. Error Handling: How will WOPI errors (e.g., 403 Forbidden, 500 Internal Error) be logged and surfaced to clients? Will you extend the bundle’s exception handling?
6. Scaling: How will WOPI requests scale under load? Will you need to implement caching (e.g., for CheckFileInfo) or async processing for file operations?
7. Testing: Do you have a WOPI client (e.g., Collabora) to validate integration early? Will you mock WOPI calls during unit testing?
8. Future-Proofing: If Microsoft Office 365 support is added, will your custom logic remain compatible? Are there plans to validate against WOPI’s official test suite?

Integration Approach

Stack Fit

• Symfony Ecosystem: Ideal for Symfony-based applications (6.4+). Leverages Symfony’s dependency injection, routing, and HTTP client for seamless integration.
• WOPI Clients: Primarily designed for Collabora Online, but theoretically compatible with Microsoft Office 365 (with validation). Other WOPI clients (e.g., OnlyOffice) may require testing.
• Storage Agnostic: Works with any storage backend that implements the champs-libres/wopi-lib interface (e.g., Doctrine ORM, custom filesystem adapter, cloud storage).
• Security Integration: Compatible with Symfony’s security system (e.g., Guard, Voters) or custom auth logic. May require middleware for token validation.

Migration Path

1. Prerequisites:

   • Upgrade Symfony to 6.4+ (if not already).
   • Install dependencies:

     composer require champs-libres/wopi-bundle champs-libres/wopi-lib
     

   • Configure Symfony’s bundles.php to include ChampsLibres\WopiBundle\WopiBundle.

2. Core Integration:

   • Implement the WopiFile interface (from wopi-lib) to define how files are stored/retrieved and permissions are checked.
   • Example:

     // src/Wopi/FileAdapter.php
     use ChampsLibres\WopiLib\WopiFile;
     
     class FileAdapter implements WopiFile {
         public function getFileUrl(string $fileId): string { ... }
         public function getFileSize(string $fileId): int { ... }
         public function getUserId(): string { ... }
         public function checkPermission(string $fileId, string $permission): bool { ... }
     }
     

   • Register the adapter as a service:

     # config/services.yaml
     services:
         ChampsLibres\WopiBundle\Wopi\WopiFile:
             alias: App\Wopi\FileAdapter
     

3. Routing:

   • The bundle auto-registers WOPI routes under /wopi/. Customize via:

     # config/routes.yaml
     champs_libres_wopi:
         resource: "@WopiBundle/Resources/config/routing.yaml"
         prefix: "/api/wopi"  # Optional: Change base path
     

   • Ensure CORS headers are configured if WOPI clients are cross-origin.

4. Security:

   • Secure WOPI endpoints with Symfony’s security (e.g., IP whitelisting, token validation).
   • Example: Use a firewall for /api/wopi:

     # config/packages/security.yaml
     firewalls:
         wopi:
             pattern: ^/api/wopi
             stateless: true
             provider: your_auth_provider
             custom_authenticators:
                 - App\Security\WopiTokenAuthenticator
     

5. Testing:

   • Use wopi-lib's test utilities to validate protocol compliance.
   • Test with a real WOPI client (e.g., Collabora) early to catch integration issues.

Compatibility

• Symfony Versions: Confirmed for 6.4+. Older versions may require patches.
• PHP Versions: Requires PHP 8.1+ (due to wopi-lib dependencies).
• WOPI Clients: Officially tested with Collabora Online. Microsoft Office 365 support is planned but unvalidated.
• Dependencies: Conflicts unlikely, but ensure symfony/http-client and symfony/framework-bundle versions are compatible.

Sequencing

1. Phase 1: Setup & Core Integration (2–4 weeks)

   • Install bundle and dependencies.
   • Implement WopiFile adapter for your storage backend.
   • Configure basic routing and security.

2. Phase 2: Custom Logic (1–3 weeks)

   • Implement permission checks (checkPermission).
   • Handle edge cases (e.g., file locks, concurrent edits).
   • Integrate with existing auth systems.

3. Phase 3: Testing & Validation (2–4 weeks)

   • Test with Collabora Online (or other WOPI clients).
   • Validate WOPI protocol compliance (e.g., CheckFileInfo responses).
   • Load-test file operations (e.g., large document streaming).

4. Phase 4: Deployment & Monitoring (1–2 weeks)

   • Deploy to staging with real WOPI clients.
   • Monitor logs for errors (e.g., 401 Unauthorized, 500 Internal Server Error).
   • Optimize performance (e.g., caching, async file ops).

Operational Impact

Maintenance

• Bundle Updates: Monitor champs-libres/wopi-bundle for breaking changes. The MIT license allows forks if needed.
• Dependency Management: wopi-lib is the critical dependency; watch for updates to the underlying WOPI protocol.
• Custom Logic: Maintenance burden shifts to your WopiFile implementation. Document assumptions (e.g., file naming conventions, permission rules).
• Security Patches: Stay vigilant for Symfony/WOPI security advisories