Upgrading Ibexa DXP from version 3 to 4
During writing this blog post the Ibexa doc Team has published the update steps from v3.3 to v4.0 in https://doc.ibexa.co/en/latest/updating/from_3.3/to_4.0/ . We will follow the documentation, runs the commands provided and understand the upgrade steps and features added to this version.
The good news is that the current version is using symfony 5.4. So, the upgrade to this version will not end up with symfony deprecation issues like the upgrade from v2 to v3.
This Document handles the migration of Ibexa Content DXP version 3.3.18 to v4.1.2.
Major changes in Ibexa v4
- The most important changes in Ibexa v4 are the namespaces or configuration keys: “ezplatform”, “eZ” and “ezpublish”. All these keys are now deprecated.
- All bundles are moved under the vendor name “ibexa”. So, under the old “ezsystems” vendor there are almost 6 bundles left but not really affecting most of the application upgrade process.
Update the installation to v4.1.2
Git:
First, we start creating a new upgrade branch so that we can follow and commit or rollback the changes if something goes wrong:
git checkout -b upgrade_to_v412
If we install standard Ibexa content v3.3.18 and v4.1.2 and compare the composer.json files you will notice the following changes:
- "minimum-stability": "stable",
- "prefer-stable": true,
"require": {
- "php": ">=7.3",
+ "php": ">=7.4",
- "ibexa/content": "3.3.18",
+ "ibexa/content": "4.1.2",This is a pretty nice result because outside of the PHP and the Ibexa version there is nothing special to change as long as we are working with the symfony 5.4 version.
Expert Tip: Install a clean latest v4.x version and compare your project composer.json and merge changes e.g flex server in extra.symfony.endpoint
But let us follow the documentation and check the final results:
composer require ibexa/content:4.1.2 --with-all-dependencies --no-scripts
By executing this command you will notice changes in composer.json and this is basically the same as above but keeping the same PHP version to 7.3
composer require ibexa/content:4.1.2 --with-all-dependencies --no-scripts
You can still use PHP7.4 or much better PHP8.1(recommended)
Now you will notice that the “ibexa” vendor folder contains all v4 refactored bundles.
Updating the app:
Now things will be much more serious as the app update will affect all configuration files in the “config” folder , .env , package.json and webpack files in the project root.
first, let’s check the changes using the git history:
changed: .env changed: composer.json changed: composer.lock changed: config/bundles.php changed: config/packages/cache_pool/cache.memcached.yaml changed: config/packages/cache_pool/cache.redis.yaml changed: config/packages/dfs/dfs.yaml changed: config/packages/nelmio_solarium.yaml changed: config/packages/security.yaml changed: package.json changed: symfony.lock changed: templates/themes/standard/full/welcome_page.html.twig changed: templates/themes/standard/pagelayout.html.twig changed: webpack.config.js
The most important changes are in “config/bundles.php”. At this step we just follow the documentation:
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.
The bundles.php file is now clean and using only:
Ibexa\Bundle\...
Before going further with the next step we have to clean up some files still using the above namespaces otherwise we will end up with issues like bundle or extension name not found.
Remove:
config/routes/ezcommerce.yaml # contains SilversolutionsEshopBundle config/packages/ezcommerce/ezcommerce_common.yaml # contains SilversolutionsEshopBundle
Remove or deactivate below imports in “config/packages/ecommerce.yaml”:
- { resource: ezcommerce/autogenerated/*.yaml }
- { resource: ezcommerce/ecommerce_parameters.yaml }
- { resource: ezcommerce/ezcommerce.yaml }
- { resource: '@SilversolutionsEshopBundle/Resources/config/config_data_provider_ez.yml' }
- { resource: ezcommerce/ezcommerce_demo.yaml }
- { resource: ezcommerce/ezcommerce_common.yaml }
- { resource: ezcommerce/ezcommerce_advanced.yaml }Before running in the next issue that there is no extension able to load the configuration for “ezplatform” you have to check the old configuration files with the “ezplatform” prefix in “config/packages/”. Compare and copy your custom configuration in the new files provided with the “ibexa” prefix in the same path.
This step is easy to do because only the prefix name has been changed to “ibexa” which makes comparing settings more comfortable.
ezplatform_admin_ui.yaml -> ibexa_admin_ui.yaml ezplatform.yaml -> ibexa.yaml
Note: We have to do the same in “config/routes” files. Be careful that other files with “ibexa_platform” prefix should be removed as they now exist with only “ibexa” prefix otherwise, we will get below issue for example for the DAM connector:
Bundle "IbexaPlatformConnectorDamBundle" does not exist or it is not enabled. Maybe you forgot to add it
besides that, there are three new webpack config files with the same prefix also available in the project root. These files are responsible for UI assets generation. Most of the time we don’t touch them as we configure the front separately or we add our custom configuration either in bundles or in webpack.config.js main file.
ibexa.webpack.config.js ibexa.webpack.config.manager.js ibexa.webpack.custom.configs.js
If this is the case you can safely remove the old files with “ez.webpack” prefix name.
before going further with the clean up we can commit all changes first.
Go further with the clean up
Ibexa provides a compatibility layer package to speed up the adaptation of our custom code to the new namespaces.
To install it we have to execute below composer command:
composer require ibexa/compatibility-layer composer recipes:install ibexa/compatibility-layer --force
If you run in below issue during cache cleaning, then just remove the “package/graphql/*” folder and we will generate the GraphQL schema at the end of the upgrade process
Type "DomainContentByIdentifierConnection" inherited by "UserContentConnection" not found.
Another issue was discovered on 16.05.2002 after twig upgrade to v3.4.0 which did not allow defining a twig function without its method implementation. For the being a downgrade to twig v3.3.10 solve the issue and Ibexa dev team is investigating to provide a fix to the missing method. The issue will result in below output during cache clear process:
Failed to create closure from callable: class 'Ibexa\Bundle\Commerce\Eshop\Twig\SilvercommonExtension' does not have a method 'getNavigation'
Coming now back to the compatibility layer package which adds some deprecated routes and also adds the file “config/packages/ibexa_compatibility_layer.yaml” that keeps compatibility with “ezplatform” key used in JS and CSS templates as well as the folder where assets will be generated.
We would like to remove anything related to “ezplatform” so we can safely remove this file as we already have the new ibexa webpack files in place and changes are already merged in webpack.config.js
Next, we use the IDE to replace the JS and CSS entries in Templates, This step has to be done most of the time if you have already extended the Ibexa UI in the previous versions.
v3
{{ encore_entry_script_tags('< entry-name >', null, 'ezplatform') }}
{{ encore_entry_link_tags('< entry-name >', null, 'ezplatform') }}v2
{{ encore_entry_script_tags('< entry-name >', null, 'ibexa') }}
{{ encore_entry_link_tags('< entry-name >', null, 'ibexa') }}Database Upgrade
In Ibexa Content v3.x there are almost 56 Database tables coming with a standard installation. 53 legacy tables have the prefix “ez” and 3 tables have “ibexa” prefix:
ibexa_migrations ibexa_setting ibexa_workflow_version_lock
In Ibexa Experience there are additional tables with the “ez” prefix to handle pagebuilder and formbuilder Features. If you have already enabled the commerce component in this version you have already recognized 27 tables with “ses_*” and “sve_*” prefixes. This is almost done by following DB steps in v3.3 upgrade doc in https://doc.ibexa.co/en/latest/updating/from_3.3/update_from_3.3/
Version v4 adds 23 tables with “ibexa” prefixes as well as 6 tables without any prefixes.
New tables:
ibexa_attribute_definition ibexa_attribute_definition_assignment ibexa_attribute_definition_ml ibexa_attribute_group ibexa_attribute_group_ml ibexa_content_customer_group ibexa_currency ibexa_customer_group ibexa_customer_group_ml ibexa_measurement_range_value ibexa_measurement_type ibexa_measurement_unit ibexa_measurement_value ibexa_product_specification ibexa_product_specification_attribute ibexa_product_specification_availability ibexa_product_specification_price ibexa_product_specification_price_customer_group ibexa_product_type_specification_region_vat_category ibexa_taxonomy_assignments ibexa_taxonomy_entries
In addition to v3, we have now 111 tables in total with taxonomy and product features tables.
For MySQL databases you can get the new tables by running the below SQL queries:
mysql -u -p < vendor/ibexa/installer/upgrade/db/mysql/ibexa-3.3.latest-to-4.0.0.sql mysql -u -p < vendor/ibexa/installer/upgrade/db/mysql/ibexa-4.0.0-to-4.1.0.sql mysql -u -p < vendor/ibexa/installer/upgrade/db/mysql/ibexa-4.0.3-to-4.0.4.sql mysql -u -p < vendor/ibexa/installer/upgrade/db/mysql/ibexa-4.1.0-to-4.1.1.sql
For PostgreSQL you have to consider the SQL files in:
vendor/ibexa/installer/upgrade/db/postgresql
If you still not see the tables above then be sure to update your entities manager by following these steps in https://doc.ibexa.co/en/latest/updating/from_2.5/to_3.3.latest/#update-entity-managers
If we try now to load the UI we will run in below issue:
Could not find 'ContentTypeGroup' with identifier 'product'
This is because some migrations are missing. This is covered in the next section.
Migrations
Ibexa v4 introduce the taxonomy tag that provides a new contenttype, the main content entry, section and new policies. For the commerce part, two migrations are available for the product catalog and currencies as well
To get the new content we have to run the import migration commands:
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
Below commands just copy the migration files from the taxonomy bundle to “src/Migrations/Ibexa/migrations” folder. Now we can execute the migration command using:
php bin/console ibexa:migrations:migrate
Note: if you like to keep the migration folder clean for your application files you can then remove these files from the migrations folder and remove the corresponding records with the file names in the “ibexa_migrations” table.
Finish update
We recommend following the documentation to run composer post scripts and generate GraphQL schema.
Now we are done and we can visit the UI which will indicate the current version of Ibexa DXP.
Summary
Ibexa dev and doc Team provide good migration steps to move to Ibexa DXP v4 from the previous version. On the application level, there are some new configuration files with “ibexa” prefix that should be merged with the old files. basically, these changes are just about the vendor name and bundle routes in v4. composer.json, webpack*.js and bundles.php can be merged and fixed quickly. The next step is about updating custom code to v4 and this is the topic of the next blog post.
