Skip to main content
Version: 2023.3

Upgrading Pimcore from Version 6.x to Version 10

System Requirement changes

  • PHP >=8.0 <8.2
  • Apache >= 2.4
  • Composer >= 2.0

As Pimcore 6.x works only with PHP < 8.0 and Pimcore 10 works only with PHP >=8.0 <8.2, a switch of PHP version is needed during the upgrade process.

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.
  • In case bin/console debug:config pimcore documents.editables.naming_strategy returns legacy, you did not adapt to the new editable naming strategy since Pimcore 5. Please migrate in Pimcore 6 before updating to Pimcore X, otherwise all your document editables will lose their data. Follow this guide

IMPORTANT CHANGES TO DO PRIOR THE UPDATE! (TO DO WITH PHP < 8.0)

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 versions to be compatible with Pimcore X

Documents: 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. (only relevant for versions created before 6.7)

Data Objects: Please adapt this migration script and execute to migrate to new class Namespaces in your old version files, if you wish to carry forward these files on Pimcore X, e.g., AppBundle\\.. to App\\...

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

Remove

"autoload": {
"classmap": [
"app/AppKernel.php"
]
}

from composer.json.

Add "AppBundle\\": ["src/"], to the autoload block, if you would like to keep using AppBundle instead of App.

"autoload": {
"psr-4": {
"App\\": ["src/"],
"AppBundle\\": ["src/"],
"Pimcore\\Model\\DataObject\\": "var/classes/DataObject",
... some other items maybe
}
},

(Alternatively you can change the namespaces of all classes under app/ folder to App\... which had AppBundle\... before.)

File / Folder 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 (add alias to parent class' use statement to prevent class name collision, e.g. use Pimcore\Kernel as PimcoreKernel; and extends PimcoreKernel)
  • Rename web/ to public/ & web/app.php to public/index.php
  • Rename config/routing.yml to config/routes.yaml
  • Move your Environment specific configs to config/packages/$ENV/*.yaml (e.g. config.prod.yml)
  • Check your Folder Structure with Skeleton Project

Some Helpers for your changes

mv app/config/ config/
mv web/ public/
mv app/Resources/views/ templates/
mv src/AppBundle/* src/
mv public/app.php public/index.php
mv app/AppKernel.php src/Kernel.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.

You can use a RegEx to replace strings in your template files. For example, rewrite {% extends ':Layout:default.html.twig' %} to {% extends 'Layout/default.html.twig' %}.

tip

Better replace the strings manually with your IDE instead of as a batch process.

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.yaml (default path <Pimcore root>/var/config/system.yaml) and config.yaml (default path after adapting folder structure <Pimcore root>/config/config.yaml)

Points to consider:

  • Remove swiftmailer config
  • Rename cache key to full_page_cache
  • Remove webservice config

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.

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;

Decompress your zipped version data

Pimcore X doesn't support compressed version data anymore, run the following command to recursively decompress them:
gzip -d -r var/versions/

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

The location of the custom logo has changed, simply move it over to the new location:

mkdir var/admin
mv var/config/custom-logo.* var/admin/custom-logo.image

Update your .htaccess or your Nginx configuration

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

SWITCH COMPOSER AND PHP VERSION, AND DO THE UPDATE!

  • Ensure Composer is updated to version >= 2.0
  • Switch PHP version to PHP >=8.0 <8.2
  • Run composer update (COMPOSER_MEMORY_LIMIT=-1 composer update)

CHANGES TO DO AFTER THE UPDATE! (TO DO WITH PHP >=8.0 <8.2)

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.