How can I upgrade/update the Pearl Theme to the latest version?

When a Pearl Theme Update is released it is recommended to install it on your store as new updates contain new features and fixes for issues reported by users. 

In order to make sure you do not experience any problems we explained below the best way to do the upgrade.

 

Prerequisites before the upgrade. Please read carefully, to avoid potential issues:

! Important : Before any upgrade, it is recommended to backup your Code and Database.

!! Important : In case you extended the theme functionality with customizations make sure you placed your custom code in a Child Theme in order not to lose your work. By respecting Magento best practice and making all customizations in a child theme, Pearl Theme will always be update proof and you will not have any risk of losing your changes. 

!!! Important : In case you have translation files, make sure you copy them in the right location after the update is complete.

!!!! Important : If you are using Pearl Theme on multiple store views, make sure to follow this article before the upgrade, as Pearl Theme functionality on store view level has been improved starting with release 1.5.5 October 20, 2017: How to use Pearl Theme on multiple store views. Important update / install instructions. If you have a single store view, you can ignore this instruction.

!!!!! Important : In order for you to be able to perform the upgrade, Magento will need to be in developer mode. For more details about how to set up developer/production mode, refer to this article: https://support.weltpixel.com/hc/en-us/articles/115004436368-How-to-set-Magento-2-Developer-and-Production-Mode-via-SSH 

 

Pearl Theme Upgrade Steps: 

 

Step 1. Checking the current theme version

Head into the Magento Admin -> WeltPixel -> WeltPixel Debugger -> Extensions Version and compare your current version to the latest version available. If the latest version is greater than your current version, an update should be performed. 

 

Step 2. Downloading the latest version files.

Go to your account on www.weltpixel.com and download the latest Pearl Theme Pack from Downloadable Products section of your account.

Note: If you purchased the Pearl Theme from Magento Marketplace please refer to this article HERE on how to download the files. Make sure you have the latest release in your marketplace account before upgrading, from experience Magento Marketplace requires 1-2 months before approving a new version due to a rigorous process of 4 step review system. We would like our updates to reach our clients ASAP but unfortunately, we cannot control how fast Magento Marketplace processes our product submission. This article HERE explains how you can check the Version of Pearl Theme in your Magento Marketplace account.

 

How can you get the latest release now if I purchased via Magento Marketplace?

Contact WeltPixel Support in case you need the latest Pearl Theme release and do not wish to wait until Magento Marketplace approves it. Please provide Magento Marketplace Name, Order Number and Purchase Date, and your weltpixel.com account email. We'll add the theme to your weltpixel.com account so you'll get faster updates. 

 

Using Pearl Theme for Enterprise Cloud Edition?

If you are using Pearl Theme on Enterprise Cloud Edition, follow this Pearl Theme ECE Installation Guide, and skip the below steps.

 

Step 3. Disabling the Magento caches.

Disable Magento Cache from System -> Cache Management -> Select All and hit disable and refresh all caches. Note: This step is required even if the cache is disabled.

During the theme upgrade process, existing sample pages, blocks, sliders will not be overwritten but only add new sample elements included in the latest release. 

 

Step 4. Removing old files.

Replace Pearl Theme files with the new ones you just downloaded. It's important to replace the files and not overwrite them. Some parts of the theme may be refactored and some of the files are not needed anymore and could generate errors.  

What files to remove before the upgrade:

a. Remove all Theme Files (all files and folders) under '/app/design/frontend/Pearl/weltpixel' 

 

b. Remove dependencies (all files and folders) included with Pearl Theme under  '/app/code/WeltPixel/'

Note: You may use other extensions provided by WeltPixel that are not part of the theme, no need to remove them as they are not part of the theme upgrade. Here is a list of them just to be sure:

- Maxmind ( Maxmind )

- Google Analytics ( GA4 )

  

Step 5. Uploading the new files.

Unzip and upload (merge) the content from the 'Theme Files' directory into the root of your Magento installation. 

! Note on theme files: Make sure you use the directory specific to your Magento version, as there are three sets of files: one for Magento 2.0.x - 2.2.x one for Magento 2.3.x, and one for Magento 2.4.x. This is very important, as the files are different, and using the wrong set of files can lead to installation and functionality issues. 

This process will not overwrite any files that you might have on your server, it will only merge them! 

Note: If you have customizations in your Child Theme under app/design/frontend/Pearl/weltpixel_custom/, remove the weltpixel_custom folder from the Installation Kit, in order to avoid overwriting any customization you may have.

Note: If you're running Magento 2.3.0 - 2.3.2, please also copy the content from the Patches folder, making sure you select the Overwrite option when prompted.

Note: Some Magento servers/versions have their index in the pub folder, as opposed to the root. If this is the case on your instance, you'll need to move the pearl-theme-installation folder into the pub directory or you won't be able to access it. This will generally manifest on the frontend via a 404 message.

Note! If you're using FileZilla for copying over the files, make sure there are no Failed Transfers. If you find any, Reset and Requeue all the files, and then process the queue again.

 

 

 

Only for Enterprise Cloud Edition(ECE), if you are using CE and EE go to Step 5.

Don't forget to re-apply the ECE patch once you updated the Pearl Theme files. More details here on How to apply the ECE patch. 

Once the patch is applied commit the updated code to your ECE repository. 

DONE, Pearl Theme is now updated. No need for Step 5 on ECE environments.

 

Step 6. Running the installer/updater.

In your browser go to www.yourmagentostore.com/pearl-theme-installation/ and simply follow the installation steps from the GUI (graphical user interface), presented in your browser URL. 

 

In GUI Pearl Theme Installer skip the theme configuration (Step 4, 5 and 6 from the installer) if you wish to keep your current theme configuration. Using the theme configurator will overwrite your current settings.  

Skip importing demo store settings:

 

Skip the theme configurator:

 

Step 7. Verifying that the update was completed successfully.

Head into the Magento Admin -> WeltPixel -> WeltPixel Debugger -> Extensions Version to check if the current version matches the latest available version, which confirms the upgrade was completed successfully.    

 

Step 8. Re-enabling the Magento Caches

If you've disabled the Magento Caches at Step 3, you can re-enable them by heading into System -> Cache Management -> Select All and hitting Enable. 

Woohoo! You updated Pearl Responsive Theme! 

 

Note:

If using AWS hosting with Bitnami see below related article for setting the proper file permissions after update: Bitnami AWS - Installation issues with Magento 2 Theme or Extensions