Update from 7.x to 7.6

This document describes the update procedure from any previous minor version of the OXID eShop 7 series, 7.x, to the minor release 7.6. This update can involve additional steps due to the possibility of choosing one of three versions of the preinstalled Content & Media Bundle.

Preparation

  1. Verify you are at least on any 7.x version older than 7.6.

  2. Verify what OXID eShop edition you are running (Enterprise, Professional or Community).

  3. Do a backup of your database.

  4. Do a backup of your filesystem.

  5. Decide which Content & Media Bundle you want to use after the update.

    OXID eShop 7.6 has the new Content & Media Bundle 12 preinstalled. This includes the following extensions:

    • Media Library 6

    • WYSIWYG Editor 8

    • Visual CMS 12 (Enterprise and Professional Edition only)

    Alternatively, you can stay on the Content & Media Bundle 11:

    • Media Library 5.2

    • WYSIWYG Editor 7.1

    • Visual CMS 11.1 (Enterprise and Professional Edition only)

    Or stay on the Content & Media Bundle 8:

    • Media Library 3.0

    • WYSIWYG Editor 5.0

    • Visual CMS 8.0 (Enterprise and Professional Edition only)

    To decide which bundle version to use, please refer to our Release Notes.

Procedure

Depending on your edition and your decision about the Content & Media Bundle, the update procedure consists of up to five steps:

Step 1: Preconfigure the Content & Media Bundle

If you decide to use the new Content & Media Bundle 12, you can skip this step and continue with Step 2: Set the Target Version.

Staying on Content & Media Bundle 11

If you are using an OXID eShop Enterprise or Professional Edition, run the following three commands:

composer require oxid-esales/media-library-module:^5.0 --no-update
composer require ddoe/wysiwyg-editor-module:^7.0 --no-update
composer require ddoe/visualcms-module:^11.0 --no-update

If you are using an OXID eShop Community Edition, run the following two commands:

composer require oxid-esales/media-library-module:^5.0 --no-update
composer require ddoe/wysiwyg-editor-module:^7.0 --no-update

Staying on Content & Media Bundle 8

If you are using an OXID eShop Enterprise or Professional Edition, run the following three commands:

composer require oxid-esales/media-library-module:^3.0 --no-update
composer require ddoe/wysiwyg-editor-module:^5.0 --no-update
composer require ddoe/visualcms-module:^8.0 --no-update

If you are using an OXID eShop Community Edition, run the following two commands:

composer require oxid-esales/media-library-module:^3.0 --no-update
composer require ddoe/wysiwyg-editor-module:^5.0 --no-update

Step 2: Set the Target Version

If you are using the OXID eShop Enterprise Edition, run the following command:

composer require oxid-esales/oxideshop-metapackage-ee:^7.6 --no-update

If you are using the OXID eShop Professional Edition, run the following command:

composer require oxid-esales/oxideshop-metapackage-pe:^7.6 --no-update

If you are using the OXID eShop Community Edition, run the following command:

composer require oxid-esales/oxideshop-metapackage-ce:^7.6 --no-update

Hint

The ^7.6 constraint automatically installs the latest available patch version. If you need a specific patch version, specify it explicitly, e.g. v7.6.0. We recommend using the latest patch version.

Step 3: Run the Update Process

In any case, run the following commands to update your OXID eShop:

composer update --no-plugins --no-scripts --no-dev --with-all-dependencies
composer update --no-dev
./vendor/bin/oe-console oe:cache:clear
./vendor/bin/oe-console oe:database:migrate
./vendor/bin/oe-eshop-db_views_generate

Important

The order matters: run oe-eshop-db_views_generate after oe:database:migrate. The migration can change the database schema (for example, the Visual CMS 12 bundle adds tables for Dynamic Blocks) and the database views must be regenerated against the updated schema afterwards. Generating the views before the migration leaves them out of date.

Step 4: Adjust the .htaccess File

The OXID eShop update process does not replace your .htaccess file, because that file is typically customized for the project and its environment. You must therefore apply the following changes manually. Depending on the OXID eShop version you are updating from, up to two adjustments are relevant:

4a) Rewrite Condition with Anchor

A rewrite condition in older OXID eShop versions restricts the use of specific brand names. The corrected condition has been part of the shipped .htaccess template since 7.4 - but because your project-customized .htaccess file is not replaced during updates, the fix is often missing in existing shops. Verify whether the change is present, and apply it if not.

  1. Open the file source/.htaccess.

  2. Search for the affected rewrite condition:

    RewriteCond %{REQUEST_URI} !(\/admin\/|\/Core\/|\/Application\/|\/export\/|\/modules\/|\/out\/|\/Setup\/|\/tmp\/|\/views\/)
    
  3. Replace the first instance with the following condition:

    RewriteCond %{REQUEST_URI} !^(\/admin\/|\/Core\/|\/Application\/|\/export\/|\/modules\/|\/out\/|\/Setup\/|\/tmp\/|\/views\/)
    
  4. Repeat this for the second affected instance.

  5. Save the file.

4b) New Rules for the API Entrypoint (introduced in 7.5)

OXID eShop 7.5 introduced a new REST API entrypoint (api.php). For requests to https://<your-shop>/api/... to be routed correctly to this entrypoint, and for the Authorization header (used for JWT-based authentication) to reach PHP, two additional sections are required in the .htaccess file. Without these rules, the API entrypoint and any features built on top of it (JWT authentication, rate limiting) will not work.

  1. Open the file source/.htaccess.

  2. Verify whether the following lines are already present inside the <IfModule mod_rewrite.c> block:

    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
    
    RewriteRule ^api/(.*)$ api.php/$1 [QSA,NC,L]
    
  3. If the lines are missing, add them as shown below. The Authorization passthrough belongs immediately after RewriteBase /, the API rewrite rule immediately after the existing graphql rule:

    <IfModule mod_rewrite.c>
        Options +FollowSymLinks
        RewriteEngine On
        RewriteBase /
    
        RewriteCond %{HTTP:Authorization} .
        RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
    
        RewriteRule ^graphql/?$    widget.php?cl=graphql&skipSession=1   [QSA,NC,L]
    
        RewriteRule ^api/(.*)$ api.php/$1 [QSA,NC,L]
    
        ...
    
  4. Save the file.

Note

The RewriteCond and RewriteRule lines for Authorization passthrough are needed because many Apache and FastCGI configurations do not forward the Authorization header to PHP by default. The two lines copy the header into an environment variable that PHP can read. Without them, every JWT authentication attempt fails with 401 Unauthorized.

Step 5: Migrate Content and Media

If you decided to keep the Content & Media Bundle 8 or 11, you can skip this step. Your update is complete.

If you decided to use the new Content & Media Bundle 12 and are using an OXID eShop Enterprise or Professional Edition, please read the Update section in our Visual CMS documentation to complete your update. Note: As of Visual CMS 12, custom styles in CMS content are interpreted as SCSS instead of LESS; check existing content beforehand with ./vendor/bin/oe-console ddoevisualcms:migrate:less-to-scss --dry-run.

For the OXID eShop Community Edition, no content migration is required to switch to Bundle 12; your update is complete after Step 3.