Installation & Configuration

info

Direct Edit is an enterprise bundle. It requires a Pimcore enterprise subscription.

Direct Edit has two parts. The bundle runs inside Pimcore and exposes the download and upload endpoints. The desktop client runs on each editor's machine, downloads the asset, opens it in a local editor, and uploads the changed file back. Both are required.

Prerequisites

The bundle requires Pimcore 2026.1 or later and PHP 8.4 or 8.5. It also needs a running Mercure hub, and Pimcore has to be served over HTTPS.

Bundle Installation

1. Install the package:

composer require pimcore/direct-edit

2. Enable the bundle in config/bundles.php:

use Pimcore\Bundle\DirectEditBundle\PimcoreDirectEditBundle;
// ...

return [
    // ...
    PimcoreDirectEditBundle::class => ['all' => true],
    // ...
];

3. Install the bundle:

bin/console pimcore:bundle:install PimcoreDirectEditBundle

Maintenance Command

Direct Edit issues a token per editing session. Clean up abandoned tokens regularly:

bin/console pimcore:direct-edit:cleanup --hours=12

--hours sets how old a token has to be before it is deleted. It defaults to 12.

JWT Key

Mercure communication is signed with a JWT key. Generate a secure key of at least 32 characters and add it to the Symfony parameters, and to the Mercure hub itself.

parameters:
    # ...
    mercure:
        hub:
            jwt_key: 'your-256-bit-secret-min-32-chars'

Separate keys for publishing and subscribing are supported as well. Configure both, or neither:

parameters:
    mercure:
        hub:
            publisher_jwt_key: 'your-publisher-secret-min-32-chars'
            subscriber_jwt_key: 'your-subscriber-secret-min-32-chars'

Direct Edit fails at runtime unless it finds either mercure.hub.jwt_key, or both mercure.hub.publisher_jwt_key and mercure.hub.subscriber_jwt_key.

warning

Keep the JWT key private. See jwt.io for background on JWT keys.

Mercure Setup

The bundle uses Mercure for the communication between Pimcore and the desktop client while a file is being edited. Without a running hub, direct editing does not work.

Follow the Mercure installation guide. The simplest setup uses the Docker image behind a reverse proxy on your own web server, which also avoids CSP problems. For the details and common questions, see Mercure Setup.

Configure the same JWT key on the Mercure hub and in Pimcore.

Bundle Configuration

All settings live under the pimcore_direct_edit key and all of them are optional.

pimcore_direct_edit:
    client_host_url: 'https://my-host.example.com'
    mercure_settings:
        client_side_url: 'https://my-host.example.com/hub/.well-known/mercure'
        server_side_url: 'http://mercure/.well-known/mercure'
        jwt_cookie_host: '.example.com'
        jwt_cookie_strictness: true

Setting	Default	Description
client_host_url	current request host	Base URL used to build the pimcorefile:// download link sent to the desktop client. Override it when Pimcore runs behind a reverse proxy or in Docker and the client has to reach a different URL.
mercure_settings.client_side_url	http(s)://<PIMCORE_HOST>/hub/.well-known/mercure	Mercure URL reachable by the browser. <PIMCORE_SCHEMA_HOST> works as a placeholder for the current scheme and host.
mercure_settings.server_side_url	http(s)://<PIMCORE_HOST>/hub/.well-known/mercure	Mercure URL reachable by Pimcore itself.
mercure_settings.jwt_cookie_host	current host only	Value of the cookie's Domain attribute.
mercure_settings.jwt_cookie_strictness	true	true sets the cookie's SameSite attribute to Strict, false sets it to None.

Deployment Hint

In pipelines without database access, Doctrine ORM cache warm-up fails because it tries to detect the database version. Configure the server version explicitly in the default DBAL connection:

doctrine:
    dbal:
        default_connection: default
        connections:
            default:
                # ...
                server_version: mariadb-10.11.0

Install the Desktop Client

Install the Pimcore Direct Edit client on every machine that should edit assets locally. The installer registers the pimcorefile protocol handler that Pimcore uses to hand an asset to the client.

See Pimcore Direct Edit Client for the download links for Windows, macOS and macOS ARM64, the install locations, and troubleshooting.

Compatibility

HTTPS Only

Direct Edit requires HTTPS. Only web servers running over HTTPS are supported, development systems included. When the system sits behind a proxy and internal communication is HTTP only, configure the trusted proxies in Symfony.

Self-signed Certificates

To make the desktop client accept self-signed certificates, create certificate-paths.txt in the client's tmp folder and list the paths to the root certificates to verify against, one per line.

Restart the client after changing that file.

Supported Operating Systems for the Desktop Client

• Windows 10
• macOS

Browser Compatibility

The application has been tested with Chrome, Firefox, Microsoft Edge and Safari.

User Permissions

The installer creates one permission, pimcore_direct_edit. Grant it to every user and role that should edit assets locally.

A user may start a Direct Edit session on an asset only if both of these hold:

• the user holds pimcore_direct_edit, and
• the user is allowed to publish that asset.

Without the permission, the Edit Locally action stays unavailable, and every endpoint that starts, checks, or resolves an editing session (generate link, get status, cancel, confirm upload, resolve conflict) rejects the request. The desktop client's download and upload endpoints authenticate with the session token issued when the link was generated, not by rechecking the permission on every call.

note

The endpoints under /pimcore_direct_edit are the protocol between Pimcore and the Direct Edit desktop client. They are not a general-purpose API. To place a Direct Edit button in your own application, see Integrate into Custom Application.