Download the PHP package champs-libres/wopi-bundle without Composer

WOPI Bundle

A Symfony bundle to facilitate the implementation of the WOPI endpoints and protocol.

Description

The Web Application Open Platform Interface (WOPI) protocol let you integrate Office for the web with your application, but also other software like Collabora Online

This bundle targets the integration with Collabora Online, for now.

In the future, this bundle may achieve a validation for an usage with Office For The Web.

Integration of Collabora Online

• Collabora Online

Overview for WOPI protocol

• wopi

Office for the web platforms:

• Collabora Office
• Office 365

Installation

Usage

This bundle provides the basic implementation of the protocol into Symfony. But there are many ways to:

• store documents in an application;
• secure the protocol
• and manage permission, according to your own business logic.

Therefore, this bundle does not provide a specific implementation of the WOPI protocol described through a basic interface from the champs-libres/wopi-lib bundle.

So, this bundle provides:

• The routes that the WOPI protocol needs, which starts with /wopi path (required by the WOPI protocol);
• A controller to for the WOPI routes;
• And an implementation for the Wopi logic, which will re-use some of your logic to manager permission, document, etc.

Some vocabulary:

• Wopi host: the app which implements this bundle;
• Wopi client: Collabora Online (or Office 365), which will use the endpoint provided by your app (the host)
• Editor: Collabora Online (or office 365). A synonym for Wopi client.

These are steps to integrate the wopi bundle in your application:

Start an editor / your wopi client for development

You will find a free collabora online with the CODE project: CODE.

:warning: the editor must have access to your app, with the same domain name as the browser will open your app.

If you use docker and docker-compose, you can achieve this by manipulating your /etc/hosts file:

With this config, you should be able to reach collabora using http://collabora:9980, and your app through http://app:8001. You must use the latter to access your app during debugging collabora features.

Configure this bundle

Create your document entity

Each document edited should be an entity which implements Document.

Create your document manager

Your manager will implements DocumentManagerInterface.

This DocumentManager will handle the document logic into your application. It provides methods for writing the document, and extract some information from it.

You can read an implementation here.

Create your logic for access token

access_token are created by your app, when it will open the editor page (spoiler: the editor page will be an iframe). The wopi host (your application) will receive this access token on every request made by the client. Each token should have a duration of 10 hours.

You can choose your own logic. But JWT can ease your life.

Some working configuration using LexikJWT

An easy way to authenticate your request is to use JWT (Json Web Token). This can be achieved easily with LexikJWTAuthenticationBundle.

Create a firewall and configure access control for url starting by /wopi:

Configure lexik:

See a working implementation: https://gitea.champs-libres.be/Chill-project/chill-skeleton-basic

Provide information about your user

Implements UserManagerInterface to provide information about your users.

This information should be extracted through access token.

Some working implementation

Provide information about the permissions / authorization

Implements AuthorizationManagerInterface to provide information about the permissions on the given Document.

Some working implementation

Bind all the services

This bundle will require the implementation to be name according to the interface.

Some example:

Create an editor page

The editor page will be the page which will load the editor, through an iframe.

Here is a controller:

Troubleshooting

• check your collabora / CODE 's logs. They provide information about error from within WOPI calls;
• use the profiler to debug the call to WOPI endpoint made behind the scene by the wopi client.

Documentation

• https://wopi.readthedocs.io/en/latest/

Code quality, tests, benchmarks

Every time changes are introduced into the library, Github runs the tests.

The library has tests written with PHPUNIT.

Before each commit, some inspections are executed with GrumPHP; run composer grumphp to check manually.

The quality of the tests is tested with Infection a PHP Mutation testing framework, run composer infection to try it.

Static analyzers are also controlling the code. PHPStan and PSalm are enabled to their maximum level.

Contributing

Feel free to contribute to this project by submitting pull requests on Github.

Changelog

See CHANGELOG.md for a changelog based on git commits.

For more detailed changelogs, please check the release changelogs.