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.

Mercure Setup

Direct Edit reports back to the browser through a Mercure hub. Without a running hub, direct editing does not work. Run the hub, then point Pimcore at it once under pimcore_studio_backend.mercure_settings, which is the connection the Studio Backend bundle owns and every supported frontend shares. Direct Edit adds no configuration of its own to it.

See Mercure Setup for the worked example, the HTTPS requirement, and the one extra setting a frontend built on the deprecated FileEditControllerTrait still needs.

Bundle Configuration

All settings live under the pimcore_direct_edit key and all of them are optional. mercure_settings is deprecated since 2026.3 and will be removed in 2027.1; setting it logs a deprecation. It configures the legacy hub client only, see Mercure Setup.

pimcore_direct_edit:
    client_host_url: 'https://my-host.example.com'

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 (deprecated)	http(s)://<PIMCORE_HOST>/hub/.well-known/mercure	Hub URL a legacy frontend subscribes to. Not derived from Studio's hub_url_client. <PIMCORE_SCHEMA_HOST> works as a placeholder for the current scheme and host.
mercure_settings.server_side_url (deprecated)	Studio's hub_url_server	Hub URL the legacy topic is published to.
mercure_settings.jwt_cookie_host (deprecated)	null	No effect since 2026.1.
mercure_settings.jwt_cookie_strictness (deprecated)	true	No effect since 2026.1.

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.