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
A comparison between the
legacy and the
nested naming strategy:
# the element referenced here would be "content.accordion.headline"
# in array notation
# legacy naming strategy
# nested naming strategy
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
nestednaming strategy or you configure the system to use the
legacynaming 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"
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
# created by build 54 - see https://github.com/pimcore/pimcore/issues/1467
This configuration is important and needs to be included as otherwise all nested editables would lose their data. However
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
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.
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
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
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.
--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
nestednaming 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