Editable Naming Strategies

Before Pimcore 5 build 54, Pimcore saved editable names in a way which couldn't always reliably determine an element's hierarchy inside block elements. This caused problems when copy/pasting elements in editmode and when accessing elements programmatically through the PHP API. See https://github.com/pimcore/pimcore/issues/559.

To address this issues, we implemented a new nested naming strategy which stores editable names in a more concise and clear way and allows to access and modify (e.g. copy/paste) document elements more efficiently and reliably in https://github.com/pimcore/pimcore/issues/1467.

A comparison between the legacy and the nested naming strategy:

# the element referenced here would be "content[7].accordion[1].headline"
# in array notation

# legacy naming strategy
headlinecontent_accordioncontent77_1

# nested naming strategy
content:7.accordion:1.headline

If you installed Pimcore 5 before build 54 or migrated Pimcore from version 4, you'll need to make sure you either migrate your document structure to the new nested naming strategy or you configure the system to use the legacy naming scheme. If you installed Pimcore after build 54 you don't need to migrate anything as your documents already use the new naming strategy.

You can check the currently configured naming strategy by issuing the following command:

$ bin/console debug:config pimcore documents.editables.naming_strategy

Current configuration for "pimcore.documents.editables.naming_strategy"
=======================================================================

legacy

As new Pimcore installations default to the nested naming strategy, the Pimcore update script for build 54 creates a config file in app/config/local/update_54_legacy_naming.yml which configures your installation to use the legacy naming strategy:

# created by build 54 - see https://github.com/pimcore/pimcore/issues/1467
pimcore:
    documents:
        editables:
            naming_strategy: legacy

This configuration is important and needs to be included as otherwise all nested editables would lose their data. However as the app/config/local directory is ignored in Git by default, please make sure you take care to track this configuration in your projects (either by moving the config entry to a tracked config file or by tracking configurations in app/config/local in your repository.

Migration to the nested naming strategy

Migration to the nested naming strategy is implemented as console command which will guide you through the migration:

$ bin/console pimcore:documents:migrate-naming-strategy

There are currently 2 different strategies which can be used to migrate your editables:

• render: renders all documents to fetch all editable names. To make the render strategy work you must make sure that all your documents/templates can be rendered without errors.

• analyze: analyzes the DB structure and tries to fetch editable names to migrate from the existing editable names. As this can't always be reliably determined, you'll be prompted to resolve potential conflicts.

Which strategy you use depends on you and your project. The render strategy can resolve the mapping without user interaction, but as it needs to render all documents it can take a long time (depending on your templates) and the amount of documents and it demands that all your documents/templates can be rendered without errors.

The analyze strategy tries to parse the editable hierarchy directly from the database structure and is quite fast if all editables can be automatically resolved. In cases of ambiguous editable names (e.g. 2 blocks named content and content1) it may be needed that you need to resolve conflicts manually. Also, the analyze strategy is not able to deal with orphaned elements which don't have any parent block, e.g. because the editable does not exist in the template anymore and it's up to you to decide if you want to ignore the editable. In many cases, orphaned elements can be cleaned up by opening and re-saving the failed document in the admin interface as this will remove any elements which don't exist anymore.

No matter which strategy you use, please make sure you have a proper backup before running the migration as the migration is irreversible!

You can try to run the migration with the --dry-run option first to see any conflicts without changing your actual elements. Even in --dry-run, the migration will write a cache of successfully migrated documents, so if you run the command again, cached documents don't need to be analyzed again.

After completing the migration, make sure you configure Pimcore to use the nested naming strategy. You can do this by either removing the file created by the updater (Pimcore will default to nested) or updating your configuration to use nested for pimcore.documents.editables.naming_strategy