Installing a minor update

Perform a minor update of your OXID eShop if required.

For example, update the compilation from an existing version 6.3.x to version 6.5.0.

Attention

Data loss

To avoid possible data loss, do the following:

  • Always run the update in a test environment, a copy of your current store, first.
  • Always proceed as follows when updating:
    1. Create a backup of the store files and database before the update.
    2. After the update, test the store again.
      In particular, check whether the ordering process and the payment and shipping methods work.

Ensuring the compatibility of third-party modules

If you use third-party modules or themes, ask the third-party vendor if these themes and modules are compatible with the new version of OXID eShop.

Background: Typically, a minor update does not contain any breaking changes. All third-party modules will work as before after the update.

However, in exceptional cases, changes can have such an impact that third-party modules no longer work.
Examples:

  • Third-party modules no longer work when updating from OXID eShop 6.1 to 6.2.
  • The OXID eSales payment module Amazon Pay 3.6.8 no longer works in OXID eShop 6.5 (see OXID eShop 6.5.0).

Ensuring the prerequisites

Before you can perform a minor update to the desired target version of OXID eShop, ensure that you meet the technical prerequisites for the update.

To do this, check the following:

  • Do I need to perform one or more incremental updates?
    Incremental update means: You do not perform an update directly to the target version, but in a previous step you perform an update to a version between your source version and your target version.
    Only in a following update you perform the update from the intermediate version to the target version.
  • In the update or incremental update, do I have a version of Composer that supports both my respective source and target versions?
  • When updating or incrementally updating, do I have a version of PHP that supports both my respective source and target versions?

Procedure

Check step by step which incremental update you need to perform to finally get to the target version of OXID eShop.

Before each update step, make sure that you have versions of Composer and PHP that are supported by both the source and the target versions.

  1. if you have OXID eShop version 5.x or lower, follow the instructions at docs.oxid-esales.com/developer/en/6.0/update/eshop_from_53_to_6/index.html.
    Alternatively: Install the latest version of OXID eShop and port only the important data.

    Note

    Porting modules

    Your modules do not work under OXID eShop version 6 anymore.

    To learn how to port your modules to OXID eShop version 6, visit https://docs.oxid-esales.com/developer/en/6.0/modules/tutorials/porting_tool.html.

    Note

    Azure theme obsolete.

    The Azure theme is still supported in OXID eShop version 6, but is no longer maintained.

  2. If you have OXID eShop version 6.0.x, do the following:

    1. Make sure you have Composer version 1.
    2. Make sure you have PHP version 7.0.
    3. Perform an initial update from version 6.0.x to version 6.1.x.
      For more information, see https://docs.oxid-esales.com/eshop/en/6.1/installation/installing-updates/installing-updates.html
  3. If you have OXID eShop version 6.1.x, do the following:

    1. Make sure you have Composer version 1.
    2. Make sure you have PHP version 7.1.
    3. Update from version 6.1.x to version 6.2.4.
      For more information, see https://docs.oxid-esales.com/eshop/en/6.2/installation/update/update-from-6.1.x-to-6.2.0.html
  4. If you have OXID eShop version 6.2.0, 6.2.1 or 6.2.2, do the following:

    1. Perform a patch update to OXID eShop version 6.2.4.
    2. Optional: Perform an update to from PHP version 7.1 to version 7.4.
      Alternatively: Perform the update to PHP version 7.4 on the following OXID eShop updates.
    3. Perform an update from Composer version 1 to Composer version 2.
  5. If you have OXID eShop version 6.2.3 or 6.2.4, do the following:

    1. Make sure you have Composer version 2.0 to 2.2.x.

      Attention

      Composer version 2.3.x is not supported.

      For example, if you have Composer version 2.3.x, install Composer version 2.2.x as follows:

      composer selfupdate 2.2.12
      
    2. Make sure you have PHP version 7.4.

    3. Without any further intermediate steps, perform the update to the desired target version.

  6. If you have OXID eShop version 6.2.5 or higher, perform the update to the current version directly as described below in Performing the update.

Performing the update

Update your OXID eShop to the latest version.

Prerequisites

You have performed the necessary incremental updates (see Ensuring the prerequisites).

Procedure

  1. Update the metapackage version in the composer.json file.
    To do this, match the name of the metapackage to the desired store edition, as in the following example.
    Example for an update of a community edition with the metapackage name 6.4.2:

    composer require --no-update oxid-esales/oxideshop-metapackage-ce:v6.4.2
    
  2. Update the dependencies.
    Open a shell in the main store directory and run the composer command below.
    This will update all the required libraries.
    Specify the --no-dev parameter if you don’t need the development related files.

    composer update --no-plugins --no-scripts --no-dev
    
  3. To get the new compilation and perform the update, run the scripts.
    To do this, run the following command.

    Note

    The update will overwrite any changes you may have made to modules or themes in the source directory.

    Background: During a store update, Composer first loads the new data into the vendor directory. Then the data is copied to the source directory. This replaces the files of the store, the modules and the themes.

    Your individual customizations of the OXID store or changes to third-party modules are only safe from being overwritten by the update if you have made the changes through one of the OXID eShop’s extension options (component, module, child theme).

    For more information, see the developer documentation under

    Attention

    Confirming queries

    During the update you will be asked which packages may be overwritten.

    To ensure that only compatible and tested packages are installed and to avoid inconsistencies and malfunctions caused by incorrectly implemented modules or themes, you have to confirm the queries with Yes.

    Recommendations:

    • If you use the extension capabilities of OXID eShop, follow the instructions in the developer documentation.
    • To create modules or child themes, get support from an OXID partner agency. This will make any future updates easier for you.
      For a list of OXID certified partner agencies, visit oxid-esales.com/partner/partner-find/.
    • If you use third-party modules or themes, ask the third-party provider if these themes and modules are compatible with the new version of OXID eShop.
      Background: Normally a minor update does not contain any breaking changes. All third-party modules will work as before after the update.
      However, in exceptional cases (for example, when updating from OXID eShop 6.1 to 6.2), changes can have an impact such that third-party modules no longer work.
    composer update --no-dev
    
  4. To ensure that the cached items do not contain incompatibilities, empty the tmp directory.
    To do this, run the following command.

    rm -rf source/tmp/*
    
  5. Migrate the database.
    To do this, run the following command.

    vendor/bin/oe-eshop-db_migrate migrations:migrate
    
  6. Regenerate the database views.
    Background: Depending on the changes and store edition, the store may go into maintenance mode after the update.
    To prevent this, regenerate the database views with the following command:

    vendor/bin/oe-eshop-db_views_generate