Upgrade Akeneo PIM projects

#Upgrade from 4.0 to 5.0

Use this documentation to upgrade projects based on Akeneo PIM Community Edition or Enterprise Edition 4.0 to 5.0.

#Disclaimer

Make sure your production database is backed-up before performing the data migration. The queue daemon(s) must be stopped as well.

#Requirements

#Updated System components

You have to make sure your system components are updated to the version required for Akeneo PIM:
  • PHP 7.4

  • MySQL 8.0

  • Elasticsearch 7.10

Elasticsearch supports in-place update: Elasticsearch 7.10 will be able to use indexes created by Elasticsearch 7.5.

So there’s no need to export and reimport data for this system.

#Updated System dependencies

Check your system dependencies are in sync with System Requirements

#Enterprise Edition

The aspell dependencies are new. Please note you have to use a composer v2 or above.

#Updated crontab definition

Check your crontab is in sync with Periodic tasks & Crontab configuration

#Enterprise Edition

Renamed

  • From pimee:data-quality-insights:schedule-periodic-tasks to pim:data-quality-insights:schedule-periodic-tasks

  • From pimee:data-quality-insights:evaluate-products to pim:data-quality-insights:evaluations

#Upgraded Virtual Host configuration

Since Akeneo PIM, instead of using one fpm pool, we are using one for the API, and one for UI.

You can check the VirtualHost configuration for 5.0 on your system: Install Akeneo PIM manually

#Prepare your project

Your current v4.0 application must have up to date migrations before migrating on the new technical stack.

The root of your current installation dir is referred as $INSTALLATION_DIR.

$ export APP_ENV=prod
$ cd $INSTALLATION_DIR
$ cp -R ./vendor/akeneo/pim-community-dev/upgrades/* ./upgrades/
$ cp -R ./vendor/akeneo/pim-enterprise-dev/upgrades/* ./upgrades/
$ php bin/console doctrine:migrations:migrate
$ rm -rf var/cache/

#Akeneo PIM composer.json

#Community Edition

You can download the composer.json file directly from the Github repository:

$  curl https://raw.githubusercontent.com/akeneo/pim-community-standard/5.0/composer.json > $INSTALLATION_DIR/composer.json

#Enterprise Edition

Please visit your Akeneo Portal to download the archive.

$ tar xvzf pim-enterprise-standard-<archive-suffix>.tar.gz -C $INSTALLATION_DIR --strip-components 1 pim-enterprise-standard/composer.json

#Load your PIM Enterprise dependencies

$ composer update

You may need to increase the memory provided to composer, as this step can be very memory consuming:

$ php  -d memory_limit=4G /path/to/composer update

#Let Akeneo PIM continue the preparation for you

#Community Edition

$ export APP_ENV=prod
$ vendor/akeneo/pim-community-dev/std-build/migration/prepare_40_to_50.sh

#Enterprise Edition

$ export APP_ENV=prod
$ vendor/akeneo/pim-enterprise-dev/std-build/upgrade/prepare_40_to_50.sh
We have overwritten:
  • Makefile

  • package.json

  • yarn.lock

  • tsconfig.json

  • src/Kernel.php

  • config/packages/security.yml

  • config/packages/dev

  • config/packages/prod_flex

  • config/packages/prod_onprem

In case of customisation, you need to resolve conflicts.

#Make sure your environment is ready to be migrated

$ rm -Rf var/cache
$ bin/console pim:installer:check-requirements

If this command detects something not working or not properly configured, please fix the problem before continuing.

#Prepare the front

$ make upgrade-front

#Migrate your data

$ bin/console doctrine:migrations:migrate
$ bin/console pimee:data-quality-insights:migrate-product-criterion-evaluation

You may receive the following warnings:

WARNING! You have X previously executed migrations in the database that are not registered migrations.

This can be safely ignored as this only means that your database is up to date, but without finding the corresponding migration files.

Another message could be Migration _X_Y_ZZZZ was executed but did not result in any SQL statements.

This makes sense for some migration that only touches the Elasticsearch index or don’t apply because no data linked to this migration have been found.

The message “The migration has already been performed.” concerning the “data-quality-insights” migration could be ignored .

#Migrating your custom code

#Applying automatic fixes

Some changes we made in the code of Akeneo PIM can be automatically applied to your own code.

In order to make this process easier and more error proof, we decided to use PHP Rector (https://github.com/rectorphp/rector) to apply these changes.

#Installing Rector

composer require --dev rector/rector-prefixed

#Applying automatic fixes

vendor/bin/rector process src/

This will use the rector.yaml file created by the prepare.sh above. Feel free to add your own refactoring rules inside it. More information on https://getrector.org/

#Identifying broken code

You can use PHPStan to help you identify broken code:

composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src/

More information, please check https://github.com/phpstan/phpstan

From that point, you will have to migrate your bundle one by one.

Remember to check if they are still relevant, as each Akeneo version brings new features.


Found a typo or a hole in the documentation and feel like contributing?
Join us on Github!