Skip to main content
Version: 2024.1

Upgrading Pimcore from Version 10.x to Version 11

Tasks to Do Prior the Update​

Migrate System Settings​

System settings are using LocationAwareConfigRepository in Pimcore 11. To keep your specific settings, please follow the steps below:

Database​

Make sure to change the type from json_array to json when upgrading to 11, since the type json_array is removed in doctrine/dbal 3. Use the following script to list the columns which contains the json_array.

mysqldump -u <USERNAME> -p <PASSWORD> --no-data <DATABASENAME> | grep -i json_array

Appearance & Branding​

Appearance & Branding settings will be separated from the system settings in Pimcore 11 and stored in var/config/admin_system_settings/admin_system_settings.yaml by default. Please copy every relevant settings from var/config/system.yaml into var/config/admin_system_settings/admin_system_settings.yaml to keep your settings.

To save these settings into the settings store, you can use the following configuration:

pimcore_admin:
    config_location:
        admin_system_settings:
            write_target:
                type: 'settings-store'
            read_target:
                type: 'settings-store'

System Settings​

Please copy all relevant settings from var/config/system.yaml into var/config/system_settings/system_settings.yaml.

To save system settings into the settings store, please add the following to your configuration:

pimcore:
    config_location:
        system_settings:
            write_target:
                type: 'settings-store'
            read_target:
                type: 'settings-store'

Configuration Storage Settings​

As some features were moved to separate bundles, their configuration storage settings might need to be moved. This is a two steps process:

  1. Remove settings before the update.
  2. Re-Add settings after the extracted bundles installation.

The relevant configs are:

# pimcore_custom_reports:
#  config_location:
#    custom_reports:
#      write_target:
#        type: 'settings-store'

# pimcore_web_to_print:
#  config_location:
#    web_to_print:
#      write_target:
#        type: 'settings-store'

# pimcore_static_routes:
#  config_location:
#    staticroutes:
#      write_target:
#        type: 'settings-store'

Web2Print​

If you are using the Web2Print functionality, set the flag "Enable Web2Print documents in default documents view" to true to ensure the PimcoreWebToPrintBundle gets installed by default.

If you are not using Web2Print functionality, set the flag to false.

WYSIWYG-Editor​

Please add all html tags with attributes you want to allow to the html_sanitizer like described here

Redis Cache Configuration​

If you are using Redis adapter for Pimcore\Cache then adapt the configuration as below:

framework:
    cache:
        pools:
            pimcore.cache.pool:
                #tags: true // this line needs to be removed
                public: true 
                default_lifetime: 31536000  # 1 year
                adapter: cache.adapter.redis_tag_aware # use this instead of pimcore.cache.adapter.redis_tag_aware
                ...

Update Pimcore via Composer​

Update Pimcore to Pimcore 11 via composer statement composer require -W pimcore/pimcore:^11.0 pimcore/admin-ui-classic-bundle.

Depending on your setup, it might be necessary to include additional dependencies in the update statement and/or to clean up the composer.lock file and the vendor folder.

After composer, some tasks like bin/console assets:install might fail due to necessary additional adaptions before the Symfony container can be built again. For more info, see the following Tasks section.

Tasks to Do After the Update​

Admin Bundle​

Register the admin-ui-classic-bundle in Kernel (and adapt method signature if necessary): src/Kernel.php

public function registerBundlesToCollection(BundleCollection $collection): void
{
    // pimcore bundles
    $collection->addBundle(new \Pimcore\Bundle\AdminBundle\PimcoreAdminBundle(), 60);
}

Some Code Changes​

  • Update config/packages/security.yaml to the latest format. As reference use security.yaml of our skeleton.
  • Update references from @PimcoreCoreBundle/Resources/config/... to @PimcoreCoreBundle/config/...
    • especially in config/routes.yaml (you probably also need to change routing.yml to routing.yaml there).

Install Extracted Bundles via Composer if Necessary​

Add the extracted bundles (such as PimcoreEcommerceFrameworkBundle or PimcorePersonalizationBundle) via composer if necessary.

composer require pimcore/system-info-bundle pimcore/file-explorer-bundle pimcore/personalization-bundle pimcore/google-marketing-bundle pimcore/web-to-print-bundle pimcore/ecommerce-framework-bundle pimcore/newsletter-bundle

Skip bundles as per your requirements.

Activate Extracted Bundles in config/bundles.php if Necessary​

Update config/bundles.php and add all the needed extracted bundles to the array:

  \Pimcore\Bundle\EcommerceFrameworkBundle\PimcoreEcommerceFrameworkBundle::class => ['all' => true], 
  \Pimcore\Bundle\PersonalizationBundle\PimcorePersonalizationBundle::class => ['all' => true],
  \Pimcore\Bundle\GlossaryBundle\PimcoreGlossaryBundle::class => ['all' => true],
  \Pimcore\Bundle\SeoBundle\PimcoreSeoBundle::class => ['all' => true],
  \Pimcore\Bundle\SimpleBackendSearchBundle\PimcoreSimpleBackendSearchBundle::class => ['all' => true],
  \Pimcore\Bundle\CustomReportsBundle\PimcoreCustomReportsBundle::class => ['all' => true],
  \Pimcore\Bundle\GoogleMarketingBundle\PimcoreGoogleMarketingBundle::class => ['all' => true],
  \Pimcore\Bundle\ApplicationLoggerBundle\PimcoreApplicationLoggerBundle::class => ['all' => true],
  \Pimcore\Bundle\WebToPrintBundle\PimcoreWebToPrintBundle::class => ['all' => true], 
  \Pimcore\Bundle\TinymceBundle\PimcoreTinymceBundle::class => ['all' => true],
  \Pimcore\Bundle\StaticRoutesBundle\PimcoreStaticRoutesBundle::class => ['all' => true],
  \Pimcore\Bundle\NewsletterBundle\PimcoreNewsletterBundle::class => ['all' => true],
  \Pimcore\Bundle\WordExportBundle\PimcoreWordExportBundle::class => ['all' => true],
  \Pimcore\Bundle\XliffBundle\PimcoreXliffBundle::class => ['all' => true],
  \Pimcore\Bundle\FileExplorerBundle\PimcoreFileExplorerBundle::class => ['all' => true],
  \Pimcore\Bundle\SystemInfoBundle\PimcoreSystemInfoBundle::class => ['all' => true],

Remove bundles as per your requirements.

Configuration Storage Settings - Part 2​

Reactivate the configuration storage settings for the extracted bundles as needed:

#custom_reports
pimcore_custom_reports:
  config_location:
    custom_reports:
      ...

#web_to_print
pimcore_web_to_print:
  config_location:
    web_to_print:
       ...

#static_routes
pimcore_static_routes:
  config_location:
    staticroutes:
       ...

Migrations​

As soon as the Symfony container can be built again, you can execute all the migrations:

bin/console doctrine:migrations:migrate

Web2Print​

If you do not use the Web2Print functionality, then please make sure to run the following command and queries to clean up your system:

bin/console pimcore:documents:cleanup printpage printcontainer
DELETE FROM `users_permission_definitions` WHERE `key` = 'web2print_settings';
UPDATE `users` SET `permissions`=REGEXP_REPLACE(`permissions`, '(?:^|,)web2print_settings(?:$|,)', '') WHERE `permissions` REGEXP '(?:^|,)web2print_settings(?:$|,)';

Newsletters​

If you do not use the Newsletter functionality, then please make sure to run the following command to clean up your system:

bin/console pimcore:documents:cleanup newsletter

Remove orphaned custom settings​

Since the facedetect support was removed in v11, we recommend to remove the corresponding custom settings in the database. You can do that by running the following commands:

bin/console pimcore:assets:remove-custom-setting faceCoordinates
bin/console pimcore:assets:remove-custom-setting disableFocalPointDetection
bin/console pimcore:assets:remove-custom-setting disableImageFeatureAutoDetection

Rebuild classes, objectBricks, fieldCollections and customLayouts​

Make sure you ran the following commands to rebuild the classes, objectBricks, fieldCollections and customLayouts:

bin/console doctrine:migration:exec 'Pimcore\Bundle\CoreBundle\Migrations\Version20230412105530'

Additional Cleanups​

  • Remove var/config/system.yaml after migrating all settings.

Server Configuration​

  • WebDav: please keep in mind that the nginx configuration has changed due to the WebDav path being moved. Please adapt your configuration accordingly by following the instruction under the WebDav section in the upgrade notes page.

Update Symfony Messenger Worker Configuration​

With Pimcore 11, certain Symfony Messenger tasks were moved to a separate receiver. Make sure you adapt your Symfony Messenger worker configuration (e.g. your supervisor configuration here so that all receivers are consumed. Newly added consumers are:

  • pimcore_scheduled_tasks
  • pimcore_image_optimize
  • pimcore_asset_update
  • pimcore_search_backend_message