Version: Edit on GitHub

Upgrading Pimcore from Version 6.x to Version 10

System Requirement changes

  • PHP >= 8.0
  • Apache >= 2.4

Database Requirement changes

  • MariaDB >= 10.3
  • MySQL >= 8.0

Preparatory Work

  • If you're on a version between 6.0.0 and 6.8.x, then please update to 6.9.x first and then continue with the upgrade steps.
  • Check if all of your used Bundles are compatible with Pimcore X
  • If you're using REST Webservices or the PHP templating engine, upgrade to Datahub and Twig templates or consider using our LTS offering which brings back this functionality as optional commercial bundles.

IMPORTANT CHANGES PRIOR THE UPDATE!

Update folder structure

Update your project folder structure as per Symfony Flex guidelines. See demo changes here

Migrate legacy module/controller/action configurations to new controller references

You can use ./bin/console migration:controller-reference to migrate your existing Documents, Static routes and Document Types to the new controller references in the format: AppBundle\Controller\FooController::barAction.

Migrate Document versions to be compatible with Pimcore X (only relevant for versions created before 6.7)

If you wish to carry forward Document version files from 6.x to Pimcore X, then it is required run command pimcore:documents:migrate-elements to migrate deprecated property elements to editables.

Ensure your database configuration includes the following definitions:

doctrine:
  dbal:
    connections:
      default:
        mapping_types:
          enum: string
          bit: boolean

Cleanup your composer.json

composer remove --no-update wikimedia/composer-merge-plugin doctrine/migrations php-http/guzzle6-adapter
composer require --no-update php-http/guzzle7-adapter:^0.1.1
Update composer.json as per [skeleton](https://github.com/pimcore/skeleton/blob/10.x/composer.json)

Important changes:

  • Move configs from app/config/*.yml to config/*.yaml
  • Move templates from app/Resources/views to templates and bundles templates from app/Resources/XYZBundle/views to templates/bundles/XYZBundle
  • Move app/AppKernel.php to src/Kernel.php and edit it to have namespace App; and class name Kernel
  • Rename web/ to public/ & web/app.php to public/index.php

Add .env environment file

Add .env file to project root, if not exists already.

Migrate Php templates to Twig

Since Pimcore X supports only Symfony 5, which dropped the support for Php templates, it is required to update your php templates to Twig.

If you are using enterprise edition, then it is still possible to support Php templates by installing pimcore/php-templating-engine-bundle.

Adapt System settings

Due to change in Pimcore config that no extra keys are allowed under pimcore node anymore, it is required to adapt system settings as per system.template.yml & config.yaml

Adapt Security config

It is not longer possible to merge security configurations from multiple locations, including bundles. Instead you have to move them to one single config file, e.g. config/packages/security.yaml. Check bin/console debug:config security firewalls to find firewall configurations which have to be moved. Please adapt config/packages/security.yaml from skeleton and merge your own firewall configs into one single file.

points to consider:

  • Removed swiftmailer config
  • cache key renamed to full_page_cache
  • Removed webservice config

Flush your /tmp directories

rm -r var/tmp
rm -r public/var/tmp

Flush your recycle-bin

Migrating the items in the recycle-bin is not supported. To have a clear start with Pimcore 10 we recommend to flush it before migration.

rm -r var/recyclebin
TRUNCATE TABLE recyclebin;

Move user images

The default location of the user images has changed, simply move the contents over to the new location:

mkdir var/admin
mv var/user-image var/admin/user-image

Update your .htaccess or your Nginx configuration

  • Updated .htaccess is available here.
  • Updated Nginx configuration is available here.

CHANGES AFTER THE UPDATE!

Verify migrations execution

By default, Composer update runs Pimcore migrations automatically, however it is better to check if all migrations are executed for smooth transition. To verify, run command: ./bin/console doctrine:migrations:up-to-date --prefix=Pimcore\\Bundle\\CoreBundle.

If you see message, [ERROR] Out-of-date! x migrations are available to execute., then run command: ./bin/console doctrine:migrations:migrate --prefix=Pimcore\\Bundle\\CoreBundle.