Prepare for SugarCloud PHP 8.2 Upgrade

Edit: Plan, timeline and execution has been updated on September 2023

What is PHP 8.2 upgrade? 

SugarCRM periodically updates the set of supported platforms for running Sugar Enterprise, and Sugar Sell & Sugar Serve in our cloud. Upgrading supported platforms improves the performance and security of Sugar applications that run on top of them. Shortly, SugarCloud will be updating its PHP version from 7.4 to 8.2. This means any PHP code running in the SugarCloud, including customizations built by customers or partners, will need to be modified to support PHP 8.2. 

Why are we upgrading PHP?

It is crucial that we upgrade our cloud stacks to ensure we are running on supported software versions adhering to security best practices. PHP 7.4 has reached its end-of-life, and PHP 8.0 is no longer actively supported, therefore Sugar has decided to upgrade to PHP 8.2, the latest supported version.

For more detailed information regarding PHP support, please refer to the PHP community’s Supported Versions documentation.   

Who is affected by this upgrade? 

Moving from PHP 7.4 to 8.2 introduces improvements and some breaking changes to the PHP language. In short, some PHP code that works in the current PHP 7.4 environment will break when run in PHP 8.2. The SugarCloud operations team, in collaboration with the engineering team, has conducted a comprehensive Rector scan to identify potential incompatibilities in Sugar instances across our entire SugarCloud environment. This scan has provided valuable insights into how customers and partners are customizing Sugar. 

On SugarCloud:  

We have conducted a thorough scan for PHP 8.2 compatibility on all Sugar instances. The purpose of the scan was to ensure that the PHP code in these instances was compatible with PHP 8.2. It has identified customizations that range from overriding core code to utilizing PHP libraries that are incompatible with PHP 8.2.

It's important to note that our scan excluded cosmetic (non-breaking) changes from PHP 7.4 to 8.2.  

SugarOutfitters Add-Ons: 

After conducting a scan of our SugarCloud environment, the SugarOutfitters team identified add-ons that are incompatible with PHP 8.2. It's important to note that this identification process has been carried out using regular expressions (regex scripts) and may not be as comprehensive or accurate as Rector. Nevertheless, it is allowing us to proactively reach out to the affected ISV partners so they can promptly address PHP 8.2 compatibility issues. 

On-Premise:

Sugar Enterprise 13.0 adds support for PHP 8.2. While it is strongly advised customers upgrade their on-premise platforms to use PHP 8.2 as soon as possible. The timeline to upgrade your environments and customizations ultimately rests with you and your IT team. Make sure they are aware of the risks and consequences of running on unsupported versions of PHP. 

What will happen during/after upgrade? 

Sugar has started to make a first attempt to remediate any incompatible code associated with your customizations or 3rd party plug-ins by running an automated tool called Rector (continue reading for details).

Code mitigation will run on all sandbox instances followed by their production instances respecting the same process as used by SugarCloud's regular upgrades.

Admin and users entitled to upgrade notifications will receive emails with details (file diffs) that Sugar/Rector has updated to make it compatible with PHP8.2.

Note: Code mitigation will execute only once per instance. If you introduce or update your packages/code with any incompatible PHP code after code mitigation, it will result in a PHP runtime error when executed using the new PHP 8.2 interpreter. 

If these runtime errors occur during a user interface (UI) interaction, users may encounter UI errors. However, if the error happens in server-side code, logic hooks, jobs, APIs, or other components, it may not be easily identifiable unless you periodically check PHP error log using SugarCloud Insights. 

For those who sell add-ons through SugarOutfitters, it is important to note that if an add-on is not compatible with PHP 8.2, it may not function properly or fail to install properly or later when users attempt to use affected functionality. 

When is this happening (plan and timeline)? 

Sugar has already started to execute the following plan:

Important Dates​

• Code mitigation in preparation for the PHP upgrade will happen in nightly batches over time
• Customers can work with support if they need to adjust within the window​
  
  • Start: September 1st, 2023​
  • Planned End: November 1st, 2023​

• PHP upgrades will occur during regular scheduled maintenance windows and will happen on a rolling basis over a period of weeks​
• It is crucial to emphasize that once a stack is upgraded, all Sugar instances within that stack* will be running PHP 8.2. It is not possible to opt out of the PHP 8.2 upgrade. 
  
  • Start: November 4th, 2023​
  • Planned End: December 9th, 2023​

* In the context of Sugar, a cloud stack refers to the virtualized hardware on which instances run within each of our hosting regions. 

What action do I need to take? 

You must test your customizations and add-ons using a PHP 8.2 environment to ensure they continue to function as intended. This includes conducting comprehensive testing of your server-side code, as it often contains significant portions written in pure PHP.

Sugar has built Test environments running PHP 8.2 and is available now for customers to test, you can coordinate with Sugar Support to get your sandbox over this test environment.

If your customization “writes PHP files to filesystem”, ensure it creates PHP 8.2 compatible code. It will not be available at the time of scans and/or when you scan with Rector. 

By conducting thorough testing, utilizing tools like Rector, and ensuring PHP 8.2 compatibility in your customizations, you can address potential issues and ensure a smooth transition to the upgraded environment.  

You must make your code compliant, do not rely on code mitigation. Your code, your responsibility! If you need to make updates to your packages/custom code, they must be compatible.

Is there a tool that can help me keep my code compatible?

Absolutely yes! That is exactly how Sugar maintains compatibility across multiple PHP versions. We leverage the power of Rector, an open-source project that can automatically detect and make your code compatible on your behalf.   

For all the detailed information and instructions, please refer to the comprehensive guide available at the following link: Automated PHP Compatibility Tool Guide.