X-Cart forums

[cflsystems]

I ran into some issues with first site I upgraded from 5.4.x to 5.5.x so here are some notes to help others.

1. Check your hosting account and make sure you have terminal access - either from within the account or ssh. You absolutely will need this. If you do not have access like this STOP. Contact your host and ask them to turn it on for you.
2. If you do not know how to use the command line or are not comfortable using it - STOP. Hire someone who knows that to upgrade your site.
3. Make sure before you start to close the store and make a good backup of all files and database. Make 2 backups or 3 if you want to be extra careful and protected.
4. Make sure you have XC 5.5.x ready version for all addons you need including the custom ones. If you do not have them ready or some of the marketplace addons are not ready yet - STOP. Do not run the upgrade before you have all you need ready.
5. Make sure you are running the cart on PHP 7.4.x and MySQL 8. XC 5.5.x works only on PHP 7.4 and 8 (not 8.1 or 8.2). XC 5.4.x is not PHP 8 compatible.
6. If you have any custom addons the upgrade screen will warn you they will be disabled during the upgrade process. Don't let this fool you - they will be deleted. However if these custom addons make any changes to database these changes will be preserved, for now.
7. Run the upgrade from admin. The upgrade process pops up a warning 2-3 times about the new version needed to point to "public" directory and is telling you after the upgrade to follow this - https://developer.x-cart.com/getting_started/server_setup. If you have custom addons - IGNORE it. Do NOT follow this or you will end up losing data.
8. When the upgrade is done just leave it as is. I suggest even log out. You can browse admin and storefront if you want to but do NOT run rebuild, cache clear or anything that may cause the cart to regenerate its working files. If you do at this point you will lose data. Keep in mind while you can browse the site at this point not everything will work or work properly due to the site's entry point not being set to "public" directory. Even though XC says fallback is provided at this point not everything works. So it is probably best not to go too much into testing or browsing.
9. Upload your 5.5.x ready custom addons. You will need to have access to your server and manually upload the packages to "modules" directory - upload the actual files/directories not the installation package. For now just upload. With XC 5.5.x the ability to install non-marketplace addons from admin has been removed. The only way to install non-marketplace addons is to login to your hosting account and manually upload the files. Makes you wonder why XC is cutting off 3rd party custom work like this making it more difficult to install addons?!?!
10. You need to make a change to the database if you have any custom addons. The upgrade process completely removes the custom addons files however it keeps their entries in the database as well as a record in service_module table. You need to change the records in the service_module table. Open the table and find the record(s) for the custom addons. Under "version" and "last_enabled_version" change the entry from whatever it is (maybe you have "5.4.1.5") to "5.5.0.0" or whatever your addon 5.5.x version is. Basially you have to change it from 5.4.x to 5.5.x. Without doing this you will not be able to enable/disable the addon from admin or see its settings page. This is clearly a bug in the cart and the upgrade process.
11. With this database change and the custom addons uploaded to "modules" directory now you are ready to make the web server changes. Follow this - https://developer.x-cart.com/getting_started/server_setup. Ask the host to do it for you if you do not have proper access. Then run the rebuild process - best if you do this from the command line rather than admin.
12. After that check the database and make sure your custom addons entries to different tables (if any) are still present in there. If not - you will have to restore from backup and start over.
13. The rebuild will not enable the custom addons. You will need to do that either from admin or one by one on the CLI - ./bin/service xcst:rebuild --enable=AUTHOR-ADDON
14. The upgrade process will transfer whatever is XC default to the "public" directory if need to. However it will not transfer anything custom you have in "var" directory. Also - XC 5.4.x has "public" directory too and if you used it to store anything non-XC standard in there it will be deleted by the upgrade process. Directories will be preserved but files deleted which is strange. I consider this a bug in the upgrade process.
15. To the above - XC 5.5.x runs off of the "public" directory; anything custom you had under "var" - move it to "public/var"; anything custom you had under "public" in 5.4.x - restore from backup. Any references in your code or database to files as "public/some_file" you will have to change to "some_file" - "public" is assumed.

This is based on my experience with site with custom addons. If you do not have any "non-marketplace" addons most of this does not apply as the upgrade process will do what's needed. You still need server access and to make the changes to the web server config for the site. The upgrade will not do this for you.

While on the server - check the .env.local file and make sure the info in there is correct. If this is live site change the APP_ENV from "dev" to "prod" (or remove the line), also APP_DEBUG to 0 (or remove the line). Although the help/comments are limited you can look in .env file for different setup options. Do not change anything in the .env file - use it as reference only. .env.local is the working file you modify if need to.

I am sure there's more to say but so far this is what I found. Suggestion - copy your live site to your local machine or create a copy of it under different VPS and do the upgrade there first as a test; if all good you can repeat the process on the live site.

[cflsystems]

Ran into an issue with db password - not documented by XC in any way, they should have mentioned this.

6.a. If the username, password, host or database name contain any character considered special in a URI (such as +, @, $, #, /, :, *, !, %), you must encode them. See RFC 3986 for the full list of reserved characters or use the urlencode function to encode them. In this case you need to remove the resolve: prefix in config/packages/doctrine.yaml to avoid errors: url: '%env(DATABASE_URL)%'
If the username, password, host or database name contain any character - change them before the upgrade.


If you didn't change them then when upgrade process stops with error make the change in the .env.local. However encoding them did not work for me - the upgrade continued but after it was done the site wouldn't load.
So I suggest not using special symbols in there until XC fixes this issue.
https://symfony.com/doc/current/doctrine.html - scroll down to the first red square note

[cflsystems]

Another issue I'm running at and probably a bug - changing only DocumentRoot to point to "public" and keeping .htaccess in /public directory for other apache settings keeps the message - "We noticed that your server config had not been changed after updating from X-Cart 5.4.1.x to X-Cart 5.5.0.x, and the root folder is still specified as a folder other than public. For reasons of security and correct operation of your X-Cart store, please do update your config info according to these [instructions]. Also, please be aware that your X-Cart software will not be able to run further updates until the changes noted above have been made." - showing in admin. Even though root is public and env setting is off.

[cflsystems]

Another issue


If you have any templates customized with the Theme Tweaker module you will have to track them down after the upgrade and recreate them. The upgrade wipes off all of them.
5.4.x keeps them as files in skins/theme_tweaker while 5.5.x keeps them in the database. Nothing is transferred the upgrade simply removes the theme_tweaker directory


Good luck chasing the templates again and redoing everything.


And the custom css/js is also not inherited with the upgrade. However with these 2 the files actually do stay and they can be restored from admin.