Update assistant

Table of Contents

1. About
2. Branches
3. Prerequisites
4. Installation
   • Create a module from source code
5. Running an update on PrestaShop
   • Update with command line parameters
   • Configuration file
6. Restore a store
   • Restore with command line parameters
7. Channels
8. Configuration Parameters
9. Test module updates locally
10. Local temporary assets
11. Process steps
    • Update steps
    • Backup steps
    • Restore steps
12. Use Storybook for an interface overview
13. Linting and Testing
    • Backend
    • Frontend
14. Local development
15. Documentation
16. Contributing
    • Reporting issues
    • Translations
17. License

About

This module allows to update your store to a more recent version of PrestaShop. It can be used as a CLI tool or with a web assistant. The latest versions of the module are compatible with all PrestaShop 1.7 and higher releases.

[!IMPORTANT] This module has a specific [Release Process][release-process]. If you do release a new version, make sure to follow it.

Branches

| Branch | Status | Docs | PrestaShop Version | |-------------------------------------------------------------------|-------------------|-----------------------------------------|--------------------| | master | Latest (Stable) | Developer documentation | >=1.7 | | dev | Latest (Unstable) | Developer documentation | >=1.7 | | 7.6.x | Supported | Developer documentation | >=1.7 | | 7.5.x | Unmaintained | Developer documentation | >=1.7 | | 7.4.x | Unmaintained | Developer documentation | >=1.7 | | 7.1.x | Unmaintained | Developer documentation | >=1.7 | | 7.0.x | Unmaintained | Developer documentation | >=1.7 | | 6.x | Unmaintained | Developer documentation | >=1.7 | | 5.x | Unmaintained | Developer documentation | >=1.7 | | 4.14.x | Unmaintained | PrestaShop 1.6 documentation | >=1.6 |

Branch dev contains code for future versions of the module, which allows updates from 1.7.x versions to higher. This is the main branch to target when opening a pull-request.

Branch 4.14.x contains code for 4.14.x patch versions which allow updating from 1.6.x versions to 1.7.x .

If you wish to update a store powered by PrestaShop 1.6, please use the latest 4.14.3 version to update to a 1.7 version. To upgrade from PrestaShop 1.6.x to version 8.x or higher, you must do it in two steps: first, upgrade from 1.6.x to 1.7.x, then update your store using the latest version of the module to reach your target version.

Please note that PrestaShop versions 1.6 and older are no longer maintained.

Prerequisites

• PrestaShop >= 1.7
• PHP >= 7.1
• Node.js >= 20 - Download Node.js (preference for LTS 20.11.0)

Installation

All versions can be found in the releases list.

Create a module from source code

If you download a ZIP archive that contains the source code or if you want to use the current state of the code, you need to build the module from the sources:

• Clone (git clone https://github.com/PrestaShop/autoupgrade.git) or download the source code. You can also download a release Source code (ex. v4.14.2). If you download a source code archive, you need to extract the file and rename the extracted folder to autoupgrade
• Enter into folder autoupgrade and run the command composer install (composer).
• Enter into folder autoupgrade/_dev and run the commands npm install and npm run vite:build (npm).
• Create a new ZIP archive from the of autoupgrade folder.
• Now you can install it in your store. For example, you can upload it using the dropzone in Module Manager back office page.

Running an update on PrestaShop

Updating a store can be done using:

• the configuration page of the module (browse the back office page provided by the module)
• in command line by calling bin/console

Update with command line parameters

This module provide a powerful command-line interface based on Symfony Console, allowing you to execute various commands to manage your store. You can use this interface to perform updates, restores, and check system requirements.

To use the Symfony Console, simply run the following command from the root directory of autoupgrade module:

$ php bin/console

The requirements can be reviewed to confirm the store is safe to update:

$ php bin/console update:check-requirements <your-admin-dir>

Modules that require an action before or during the update are listed with:

$ php bin/console update:check-modules <your-admin-dir>

To see which new versions are available for your installation use:

$ php bin/console update:check-new-version <your-admin-dir>

A backup of the store is created with:

$ php bin/console backup:create --config-file-path=[/path/to/config.json] <your-admin-dir>

The update process can be launched with:

$ php bin/console update:start --config-file-path=[/path/to/config.json] <your-admin-dir>

You can see all available parameters and options directly from the console by using the --help option with any command.

For more information on using commands, please refer to the PrestaShop developer documentation

Configuration file

For the proper functioning of the update process via the console, it is necessary to provide a configuration file in JSON format.

Here is an example of the different fields that can be found in it:

{
  "channel": "local",
  "archive_zip": "prestashop_8.0.0.zip",
  "archive_xml": "prestashop_8.0.0.xml",
  "PS_AUTOUP_CUSTOM_MOD_DESACT": 1,
  "PS_AUTOUP_CHANGE_DEFAULT_THEME": 0,
  "PS_AUTOUP_REGEN_EMAIL": 1,
  "PS_AUTOUP_KEEP_IMAGES": 1,
  "PS_DISABLE_OVERRIDES": 1
}

Please see the section Configuration Parameters for explanations concerning the configurations

Restore a store

If an error occurs during the update process, the restore will be suggested. In case you lost the page from your backoffice, note it can be triggered via CLI.

Restore with command line parameters

For restore your store, you would use:

$ php bin/console backup:restore --backup=[backup-name] <your-admin-dir>

You can see all available parameters and options directly from the console by using the --help option with any command.

For more information on using commands, please refer to the PrestaShop developer documentation

Check Modules Compatibility

A command helps you review module compatibility before launching an update, giving you clearer visibility on the actions needed or planned.

Run the command from the root directory of the module:

php bin/console update:check-modules <your-admin-dir>

Running as verbose shows the compatibility details based on the Marketplace API.

Channels

There are 3 channels available for an update:

• online - This channel corresponds to the official "online" update for your store, detected by PrestaShop APIs (m