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
returnslegacy
, 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
toconfig/*.yaml
- Move templates from
app/Resources/views
totemplates
and bundles templates fromapp/Resources/XYZBundle/views
totemplates/bundles/XYZBundle
- Move
app/AppKernel.php
tosrc/Kernel.php
and edit it to havenamespace App;
and class nameKernel
(add alias to parent class' use statement to prevent class name collision, e.g.use Pimcore\Kernel as PimcoreKernel;
andextends PimcoreKernel
) - Rename
web/
topublic/
&web/app.php
topublic/index.php
- Rename
config/routing.yml
toconfig/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 the following RegEx to Replace Strings in your Template Files
For example Rewrite {% extends ':Layout:default.html.twig' %}
to {% extends 'Layout/default.html.twig' %}
and so on
Use this not as a Batch process try with your IDE to replace it manually
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 (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 tofull_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
Move custom logo
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
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
.