Skip to content
  • Documentation >
  • Update and migration >
  • Update from v3.3 >
  • Update to v4.0

Update from v3.3.x to v4.0

This update procedure applies if you are using v3.3.

Go through the following steps to update to v4.0.

Besides updating the application and database, you need to account for changes related to code refactoring and numerous namespace changes. See a list of all changed namespaces, configuration key, service names, and other changes.

An additional compatibility layer makes the process of updating your code easier.

Temporary need of Composer conflict

To go through this update, map the conflicting packages in your composer.json file as following: 

1
2
3
4
"conflict": {
    "jms/serializer": ">=3.30.0",
    "gedmo/doctrine-extensions": ">=3.12.0"
},
These entries can be removed after fully upgrading to v4.6 LTS.

Symfony 5.4

If you are using Symfony 5.3, you need to update your installation to Symfony 5.4. To do this, update your composer.json to refer to 5.4.* instead or 5.3.*.

Refer to the relevant website skeleton for an example: content, experience, commerce.

Update the app to v4.0

First, run:

1
composer require ibexa/content:4.0.8 --with-all-dependencies --no-scripts

1
composer require ibexa/experience:4.0.8 --with-all-dependencies --no-scripts

1
composer require ibexa/commerce:4.0.8 --with-all-dependencies --no-scripts

Update Flex server

The flex.ibexa.co Flex server has been disabled. If you are using v4.0.2 or earlier v4.0 version, you need to update your Flex server.

To do it, in your composer.json check whether the https://flex.ibexa.co endpoint is still listed in extra.symfony.endpoint. If so, replace it with the new https://api.github.com/repos/ibexa/recipes/contents/index.json?ref=flex/main endpoint.

If your composer.json still uses the https://flex.ibexa.co endpoint in extra.symfony.endpoint, replace it with the new https://api.github.com/repos/ibexa/recipes/contents/index.json?ref=flex/main endpoint.

You can do it manually, or by running the following command:

1
composer config extra.symfony.endpoint "https://api.github.com/repos/ibexa/recipes/contents/index.json?ref=flex/main"

Next, continue with updating the app:

1
composer recipes:install ibexa/content --force -v

1
composer recipes:install ibexa/experience --force -v

1
composer recipes:install ibexa/commerce --force -v

The recipes:install command installs new YAML configuration files, which have been renamed in this release.

Look through the old YAML files and move your custom configuration to the relevant new files.

In bundles.php, remove all entries starting with eZ, EzSystems, Ibexa\Platform, Silversolutions and Siso. Leave only third-party entires and entries added by the recipes:install command, starting with Ibexa\Bundle.

Add compatibility layer package

You can use the provided compatibility layer to speed up adaptation of your custom code to the new namespaces.

Add the compatibility layer package using Composer:

1
2
composer require ibexa/compatibility-layer
composer recipes:install ibexa/compatibility-layer --force

Make sure that Ibexa\Bundle\CompatibilityLayer\IbexaCompatibilityLayerBundle is last in your bundle list in config/bundles.php.

Next, clear the cache:

1
php bin/console cache:clear

Update the database

Apply the following database update script:

Ibexa DXP

1
mysql -u <username> -p <password> <database_name> < vendor/ibexa/installer/upgrade/db/mysql/ibexa-3.3.latest-to-4.0.0.sql

1
psql <database_name> < vendor/ibexa/installer/upgrade/db/postgresql/ibexa-3.3.latest-to-4.0.0.sql

Ibexa Open Source

If you have no access to Ibexa DXP's ibexa/installer package, apply the following database upgrade script:

1
ALTER TABLE `ezcontentclassgroup` ADD COLUMN `is_system` BOOLEAN NOT NULL DEFAULT false;

1
ALTER TABLE "ezcontentclassgroup" ADD "is_system" boolean DEFAULT false NOT NULL;

Prepare new database tables

For every database connection you have configured, perform the following steps:

  1. Run php bin/console doctrine:schema:update --dump-sql --em=ibexa_{connection}
  2. Check the queries and verify that they are safe and will not damage the data.
  3. Run php bin/console doctrine:schema:update --dump-sql --em=ibexa_{connection} --force

Next, run the following commands to import necessary data migration scripts:

1
2
3
4
5
6
php bin/console ibexa:migrations:import vendor/ibexa/taxonomy/src/bundle/Resources/install/migrations/content_types.yaml --name=000_taxonomy_content_types.yml
php bin/console ibexa:migrations:import vendor/ibexa/taxonomy/src/bundle/Resources/install/migrations/sections.yaml --name=001_taxonomy_sections.yml
php bin/console ibexa:migrations:import vendor/ibexa/taxonomy/src/bundle/Resources/install/migrations/content.yaml --name=002_taxonomy_content.yml
php bin/console ibexa:migrations:import vendor/ibexa/taxonomy/src/bundle/Resources/install/migrations/permissions.yaml --name=003_taxonomy_permissions.yml
php bin/console ibexa:migrations:import vendor/ibexa/product-catalog/src/bundle/Resources/migrations/product_catalog.yaml --name=001_product_catalog.yaml
php bin/console ibexa:migrations:import vendor/ibexa/product-catalog/src/bundle/Resources/migrations/currencies.yaml --name=001_currencies.yaml

Run php bin/console ibexa:migrations:migrate -v --dry-run to ensure that all migrations are ready to be performed. If the dry run is successful, run:

1
php bin/console ibexa:migrations:migrate

Update your custom code

Back Office customization

The v4 version of Ibexa DXP is using Bootstrap 5 in the Back Office. If you were using Bootstrap 4 for styling, you need to update and adjust all custom Back Office components following the migration guide from Bootstrap 4.

Online editor

Custom plugins and buttons

If you added your own Online Editor plugins or buttons, you need to rewrite them using CKEditor 5's extensibility.

Custom tags

If you created a custom tag, you need to adapt it to the new configuration, for example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
ibexa:
    system:
        admin_group:
            fieldtypes:
                ezrichtext:
                    custom_tags: [ezfactbox]
                    toolbar:
                        custom_tags_group:
                            buttons:
                                ezfactbox:
                                    priority: 5

Personalization

In Personalization, the included_content_types configuration key has changed to included_item_types. Update your configuration, if it applies.

Finish update

Adapt your composer.json file according to manifest.json, by adding the following lines:

1
2
3
4
"yarn install": "script",
"ibexa:encore:compile --config-name app": "symfony-cmd",
"bazinga:js-translation:dump %PUBLIC_DIR%/assets --merge-domains": "symfony-cmd",
"ibexa:encore:compile": "symfony-cmd"

Then, finish the update process:

1
composer run post-install-cmd

Finally, generate the new GraphQl schema:

1
php bin/console ibexa:graphql:generate-schema

Ibexa Cloud

Update Platform.sh configuration and scripts.

Generate new configuration with the following command:

1
composer ibexa:setup --platformsh

Review the changes applied to .platform.app.yaml, .platform/ and bin/platformsh_prestart_cacheclear.sh, merge with your custom settings if needed, and commit them to Git.