• Documentation >
• Update and migration >
• Updating Ibexa DXP >
• Updating to v3.3

Updating Ibexa DXP to v3.3

Ibexa DXP v3.3 uses Symfony Flex. When updating from v3.2 to v3.3, you need to follow a special update procedure.

If you are updating from an earlier version, start with updating your installation to v3.2. If you want to update from v3.3.2 to a later v3.3 version, for example v3.3.3, see Update to v3.3.x.

Note

Ibexa DXP v3.3 requires Composer 2.0.13 or higher.

First, create an update branch in git and commit your work.

If you have not done it before, add the relevant meta-repository as an upstream remote:

ezplatform

git remote add upstream http://github.com/ezsystems/ezplatform.git

ezplatform-ee

git remote add upstream http://github.com/ezsystems/ezplatform-ee.git

ezcommerce

git remote add upstream http://github.com/ezsystems/ezcommerce.git

Tip

It is good practice to make git commits after every step of the update procedure.

Merge composer.json

Merge the special v3.2-to-v3.3-upgrade update branch into your project:

git pull upstream v3.2-to-v3.3-upgrade

This will introduce changes from the website skeleton and result in conflicts in composer.json.

Resolve the conflicts in the following way:

• Make sure all automatically added ezsystems/* packages are removed. If you explicitly added any packages that are not part of the standard installation, retain them.
• Review the rest of the packages. If your project requires a package, keep it.
• If a package is only used as a dependency of an ezsystems package, remove it. You can check how the package is used with composer why <packageName>.
• Keep the dependencies listed in the website skeleton.

Make sure extra.symfony.endpoint is set to https://flex.ibexa.co, and extra.symfony.require to 5.3.*:

"require": "5.3.*",
"endpoint": "https://flex.ibexa.co"

For all dependencies that you removed from composer.json, check if the bin folder contains files that will not be used and remove them, for example:

rm bin/{ezbehat,ezreport,phpunit,behat,fastest}

Add your Ibexa DXP edition to composer.json, for example:

composer require ibexa/experience:^3.3 --no-update

Caution

It is impossible to update an Enterprise edition (ezsystems/ezplatform-ee) to an Ibexa Content edition.

Update the app

Run composer update to update the dependencies:

composer update

If Composer informs you that the composer.lock file is out of date, run composer update again.

Update recipes for third party packages

Run composer recipes to get a list of all the available recipes.

For every recipe that needs updating, run:

composer sync-recipes <package_name> --force -v

Review changes from each package and integrate them into your project.

Install Ibexa recipes

Install recipes for Ibexa packages for your product edition, for example:

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

Review the changes and add them to your project.

Then, run the post-installation command:

composer run post-install-cmd

Configure the web server

Add the following rewrite rule to your web server configuration:

Apache

RewriteRule ^/build/ - [L]

nginx

rewrite "^/build/(.*)" "/build/$1" break;

Update the database

Caution

Before starting this step, back up your database.

Apply the following database update script:

MySQL

mysql -u <username> -p <password> <database_name> < upgrade/db/mysql/ezplatform-3.2.0-to-3.3.0.sql

PostgreSQL

psql <database_name> < upgrade/db/postgresql/ezplatform-3.2.0-to-3.3.0.sql

If you are updating from an installation based on the ezsystems/ezplatform-ee metarepository, run the following command to upgrade your database:

php bin/console ibexa:upgrade

Caution

You can only run this command once.

Check the Location ID of the "Components" Content item and set it as a value of the content_tree_module.contextual_tree_root_location_ids key in config/ezplatform.yaml:

- 60 # Components

If you are upgrading between Ibexa Commerce versions, add the content/read Policy with the Owner Limitation set to self to the "Ecommerce registered users" Role.

Finish the update

Finish the update by running the following commands:

php bin/console ibexa:graphql:generate-schema
composer run post-install-cmd

Update to v3.3.x

Note

You can only update to the latest patch release of 3.3.x.

Caution

To update to v3.3.3, remove Kaliop\eZMigrationBundle\eZMigrationBundle::class => ['all' => true], from config/bundles.php before running composer require.

Then, in composer.json, set minimum stability to stable:

"minimum-stability": "stable",

v3.3.6 starts using Symfony 5.3. To update from an earlier v3.3 patch version to v3.3.6, update the following package versions in your composer.json, including the Symfony version (line 9):

"symfony/flex": "^1.3.1"
"sensio/framework-extra-bundle": "^6.1",
"symfony/runtime": "*",
"doctrine/doctrine-bundle": "^2.4"
"symfony/maker-bundle": "^1.0",

"symfony": {
    "allow-contrib": true,
    "require": "5.3.*",
    "endpoint": "https://flex.ibexa.co"
},

See https://github.com/ibexa/website-skeleton/pull/5/files for details of the package version change.

Next, run:

Ibexa Content

composer require ibexa/content:3.3.6 --with-all-dependencies --no-scripts
composer recipes:install ibexa/content --force -v
composer run post-install-cmd

Ibexa Experience

composer require ibexa/experience:3.3.6 --with-all-dependencies --no-scripts
composer recipes:install ibexa/experience --force -v
composer run post-install-cmd

Ibexa Commerce

composer require ibexa/commerce:3.3.6 --with-all-dependencies --no-scripts
composer recipes:install ibexa/commerce --force -v
composer run post-install-cmd

Review the changes to make sure your custom configuration was not affected.

Then, perform a database upgrade relevant to the version you are updating to.

Clear Redis cache

If you are using Redis as your persistence cache storage you should always clear it manually after an upgrade. You can do it by executing the following command:

php bin/console cache:pool:clear cache.redis

Update database to v3.3.2

To update to v3.3.2, if you are using MySQL, additionally run the following update script:

mysql -u <username> -p <password> <database_name> < vendor/ibexa/installer/upgrade/db/mysql/ibexa-3.3.1-to-3.3.2.sql

Update entity managers

Version v3.3.2 introduces new entity managers. To ensure that they work in multi-repository setups, you must update the GraphQL schema. You do this manually by following this procedure:

1. Update your project to v3.3.2 and run the php bin/console cache:clear command to generate the service container.

2. Run the following command to discover the names of the new entity managers. Take note of the names that you discover:

   php bin/console debug:container --parameter=doctrine.entity_managers --format=json | grep ibexa_

3. For every entity manager prefixed with ibexa_, run the following command:

   php bin/console doctrine:schema:update --em=<ENTITY_MANAGER_NAME> --dump-sql

4. Review the queries and ensure that there are no harmful changes that could affect your data.

5. For every entity manager prefixed with ibexa_, run the following command to run queries on the database:

   php bin/console doctrine:schema:update --em=<ENTITY_MANAGER_NAME> --force

VCL configuration for Fastly

If you use Fastly, update your VCL configuration.

Locate the vendor/ezsystems/ezplatform-http-cache-fastly/fastly/ez_main.vcl file and add the following lines to it:

if (req.restarts == 0 && resp.status == 301 && req.http.x-fos-original-url) {
    set resp.http.location = regsub(resp.http.location, "/_fos_user_context_hash", req.http.x-fos-original-url);
}

Optimize workflow queries

Run the following SQL queries to optimize workflow performance:

CREATE INDEX idx_workflow_co_id_ver ON ezeditorialworkflow_workflows(content_id, version_no);
CREATE INDEX idx_workflow_name ON ezeditorialworkflow_workflows(workflow_name);

Update database to v3.3.7

To update to v3.3.7, additionally run the following script:

MySQL

CREATE TABLE IF NOT EXISTS `ibexa_workflow_version_lock` (
    `id` INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
    `content_id` INT(11) NOT NULL,
    `version` INT(11) NOT NULL,
    `user_id` INT(11) NOT NULL,
    `created` INT(11) NOT NULL DEFAULT 0,
    `modified` INT(11) NOT NULL DEFAULT 0,
    `is_locked` BOOLEAN NOT NULL DEFAULT true,
    KEY `ibexa_workflow_version_lock_content_id_index` (`content_id`) USING BTREE,
    KEY `ibexa_workflow_version_lock_user_id_index` (`user_id`) USING BTREE,
    UNIQUE KEY `ibexa_workflow_version_lock_content_id_version_uindex` (`content_id`,`version`) USING BTREE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

PostgreSQL

CREATE TABLE IF NOT EXISTS ibexa_workflow_version_lock
(
    "id" SERIAL,
    "content_id" INTEGER,
    "version" INTEGER,
    "user_id" INTEGER,
    "created" INTEGER DEFAULT 0 NOT NULL,
    "modified" INTEGER DEFAULT 0 NOT NULL,
    "is_locked" boolean DEFAULT TRUE NOT NULL,
    CONSTRAINT "ibexa_workflow_version_lock_pk" PRIMARY KEY ("id")
);

CREATE INDEX IF NOT EXISTS "ibexa_workflow_version_lock_content_id_index"
    ON "ibexa_workflow_version_lock" ("content_id");

CREATE INDEX IF NOT EXISTS "ibexa_workflow_version_lock_user_id_index"
    ON "ibexa_workflow_version_lock" ("user_id");

CREATE UNIQUE INDEX IF NOT EXISTS "ibexa_workflow_version_lock_content_id_version_uindex"
    ON "ibexa_workflow_version_lock" ("content_id", "version");

Enable Commerce features

With the v3.3.2 update, Commerce features in Experience and Content editions are disabled by default. If you use these features, after the update refer to Enable Commerce features and manually enable them.

Update database to v3.3.9

To update to v3.3.9, additionally run the following update script:

MySQL

mysql -u <username> -p <password> <database_name> < vendor/ibexa/installer/upgrade/db/mysql/ibexa-3.3.8-to-3.3.9.sql

PostgreSQL

psql <database_name> < vendor/ibexa/installer/upgrade/db/postgresql/ibexa-3.3.8-to-3.3.9.sql