Upgrading your installation from version SuiteCRM 7.13 to 7.14 is a crucial process that requires careful planning and execution. This guide is a walkthrough of the entire upgrade journey, sharing real-world experiences and solutions to help you navigate this important transition smoothly.
Before Upgrade: Setting the Foundation
The thorough preparation of your upgrade will lead you to success. Before starting the upgrade process, make sure that your environment meets all the necessary criteria and that you've taken appropriate precautions.
Understanding System Requirements
SuiteCRM 7.14 brings new changes, especially in PHP version support. Your server environment must be running PHP 8.1 or 8.2, which is a major shift from the PHP 7.x series that supported earlier versions. This is not optional – failing to meet this requirement will result in immediate failure of upgrading.
Linux, Unix, Mac OS, or Windows Server 2019 or higher can serve as your operating system. For web servers, Apache 2.4 or IIS 10 are supported. On the database side, you can use MariaDB versions 10.4 through 10.11, MySQL 5.7 or 8.0, or SQL Server 2019 and above. Make sure your browser is also up to date – Chrome, Firefox, Edge should be version 109 or higher, Safari 16 or higher, and Internet Explorer 11 is still supported though compatibility mode is not.
Preparing Your Environment
Start by creating complete backups for both your database and file system. This is your insurance policy, not just a safety measure. Backup all your current customizations, custom modules, and third-party integrations. When facing troubleshooting issues during upgrade, you will require this information.
Verify your current installation by checking the suitecrm_version.php and loadtasks.php files. These files must be in proper condition before running the upgrade. Most importantly, if you're currently running PHP 7.x, upgrade to PHP 8.1 or 8.2 first. This is a mandatory step to be taken before attempting the SuiteCRM upgrade.
First, thoroughly check your custom code. Search for PHP4-style constructors, static method calls that should be instance methods, and any PHP syntax that is deprecated. PHP 8.x has stricter type checking to detect issues that were early warnings in PHP 7.x. Always test the upgrade in a staging or development environment first. Never try your first upgrade attempt on a production system.
During Upgrade: Navigating the Challenges
With a single command, the upgrade process itself is initiated, but its whole journey from start to finish involves resolving several compatibility concerns. Here's what you're likely to encounter and how you can manage each situation.
Issue 1: PHP Version Incompatibility
PHP version check is the first major hurdle that many administrators face. When attempting to run the upgrade, an error stating that Composer dependencies require PHP version 8.1.0 or higher, but you're running an older version like 7.4.33 might appear. This occurs because the system checks PHP compatibility before proceeding with the upgrade.
The solution is straightforward but critical: you must upgrade your PHP installation to version 8.1 or 8.2 before attempting the SuiteCRM upgrade. After PHP upgrading is done, run Composer to update all dependencies. This ensures the compatibility of all components with the new PHP version. This prepares you to proceed with the SuiteCRM upgrade.
Issue 2: Static Method Call Errors
While carrying out the upgrading process, errors related to non-static methods being called static might occur. A common example is the “MetaParser::hasMultiplePanels()” method in the EditViewMerge.php file. For static versus instance method calls, PHP 8.x enforces stricter rules.
To resolve this, locate the problematic code in the modules/UpgradeWizard/SugarMerge/EditViewMerge.php file around line 612. Instead of calling the method statically, create a new instance of the MetaParser class and call the method on that instance. The updated code should instantiate the class with "new MetaParser()" and then call the “hasMultiplePanels” method on that object. This pattern applies to other similar errors you might encounter throughout the upgrade.
Issue 3: Dynamic Property Deprecation
PHP 8.2 introduces deprecation warnings for dynamic properties – properties that are assigned to objects without being declared in the class definition. Warnings about properties such as the signature property in the OutboundEmail class being deprecated might flash.
The solution includes updating your class definitions to explicitly announce all properties that will be used. After carefully reviewing all classes that show this warning, add an appropriate property declaration at the class level. While these are currently just early warnings, they'll turn into errors in future PHP versions, so it would be best to address them earlier during the upgrade.
Issue 4: Third-Party Integration Conflicts
Custom integrations, especially services like Twilio, can cause serious errors during the upgrade. You might see errors about type mismatches in exception classes or issues with custom integration code that hasn’t been updated yet for PHP 8.x compatibility.
Temporarily removing unused third-party integration files and folders is the most effective approach. Particularly for the Twilio integration, remove the custom/include/twilio directory if not being actively used. After the upgrade is complete, updated versions of these integrations that share compatibility with SuiteCRM 7.14 and PHP 8.x. can be reinstalled.
Issue 5: Version Compatibility Check Failures
Sometimes the upgrade wizard reports that your current version of SuiteCRM is not compatible with the uploaded upgrade file, even when it should be. The version string formatting issues or corruption in version tracking files can be the reason for this.
While not ideally suggested, you may require to manually modify the version information in your configuration to permit the upgrade to proceed. However, this should only be done if you're completely sure about using the correct upgrade package. Verify the package integrity and that it's specifically designed for upgrading from your current version to 7.14.
Issue 6: Method Signature Compatibility
One of the most commonly faced issues includes method signatures in custom modules being inconsistent with their parent class signatures. PHP 8.x strictly imposes that child class methods must be compatible with their parent class counterparts. You'll see errors about declarations being incompatible, particularly with methods like “create_new_list_query”.
The solution requires updating the method signature in your custom module to allow all parameters to be included in the parent class. A new parameter, ifListForExport, was added to the “create_new_list_query” method in SugarBean. Your custom modules must have this parameter embedded in their method signatures, even if they are unused. Update the method signature to include this parameter with a default value of false and make sure you pass it through when calling the parent method.
Issue 7: Missing Callback Functions
Custom search forms and dropdown fields often depend on callback functions to populate options. During the upgrade, you might come across errors asserting that callback functions like get_conf_type, get_event_type, or get_visibility_type cannot be found.
These functions must be integrated into your custom function files, generally add_functions.php. Create simple implementations of these functions that repay the suitable values or arrays. Even if the function just returns true or an empty array temporarily, this allows the upgrade to progress. After completing the upgrade, you can implement the full functionality.
Issue 8: Smarty Template Syntax Changes
SuiteCRM 7.14 uses a newer version of the Smarty template engine that does not support the php tag anymore. Any custom templates that use php tags will cause serious syntax blunders. You'll see errors particularly stating "unknown tag 'php'" in several file templates.
The solution requires either eliminating or updating these templates. For templates in the custom/include/SugarFields directory, you can rename them using a .bak extension to temporarily disable them. For searchdefs files that generate templates with php tags, you will have to rewrite them to employ appropriate Smarty syntax or different methods. Original files must be backed up with a timestamp in the filename before attempting to make changes.
Issue 9: Constructor Modernization
PHP 8.x fully removes support for PHP4-style constructors – methods named same as their class. Custom modules and dashlets that use old-style constructors will malfunction with errors about undefined methods. This affects dashlets, view classes, and custom modules.
Every class must be updated to use the modern __construct method name instead of using the class name as the constructor. Replace all PHP4-style constructors with the “_construct” method and update the parent constructor call from “parent::ClassName()” to “parent::__construct()”. To temporarily maintain backward compatibility, you can retain the old-style constructor as a deprecated wrapper that calls the new __construct method, but this measure should be only adopted temporarily.
Issue 10: View Class Constructor Updates
Custom view classes extending ViewList, ViewDetail, or ViewEdit are specifically vulnerable to constructor issues. The parent classes do not have methods named after themselves anymore, so calls like “parent::ViewList()” will not follow through.
Update all custom view classes to use “parent::__construct()” in place of “parent::ClassName()”. Use grep to find all files that are affected in your custom modules' directory. The pattern is consistent across all view types – only needing to replace the old parent constructor to call the new one.
Issue 11: Module-Specific Display Issues
After the upgrade is done, you might find that some modules like Meetings show blank list views, even though the upgrade is successful. This generally signals that custom query methods require updates.
For the Meetings module particularly, add the “create_new_list_query” method to the Meeting.php file. This method should call the parent method with all parameters, including the new ifListForExport parameter, and then the order should be customized by clause as per needs. The same pattern applies to other modules exhibiting similar symptoms.
Issue 12: Logic Hook Method Errors
Custom logic hooks may reference methods that don't exist or weren't properly defined in earlier versions. You might encounter errors about undefined methods in logic hook classes, especially map integrations or custom processing modules.
Carefully review the logic hook definition files and ensure the implementation of all referenced methods in the hook class. Add any overlooked or missed methods with proper implementation. For example, if a Prospects module hook references a “check_details_method”, ensure this method positively exists in the ProspectsJjwg_MapsLogicHook class file.
Issue 13: Database Query Type Safety
PHP 8.x's has stricter type checking that captures issues where database query results are not properly authenticated before use. You'll see errors about mysqli_fetch_assoc expecting a mysqli_result but receiving a boolean value when queries fail.
Update all database query wrapper functions to check if the query result is valid before attempting to fetch data. Add conditional checks that return false or an empty array if the query fails, rather than trying to process a failed query result. This pertains to custom utility functions that cover database operations.
Issue 14: CURL Handle Management
Custom code that uses CURL for several simultaneous connections might have variable naming inconsistencies that PHP 8.x detects. Errors about curl_multi_remove_handle receiving nulls instead of a CurlMultiHandle specify such issues.
To ensure that handle variables are used consistently throughout the function, carefully review all CURL-related code. If you create a handle as mh, do not try to change its reference later as multiCurl. Use corrects variable names to match throughout the function.
Issue 15: Array Operation Safety
PHP 8.x is stricter about operations on variables that might not be arrayed. Count operations on potentially non-array variables can lead to possible errors or warnings.
Wrap count operations with is_array checks to guarantee that you are only counting real arrays. This defensive programming approach prevents errors when encountering null variables or non-array values. Update custom functions that modify arrays to include these checks.
After Upgrade: Ensuring Success
Your work isn't quite done even when the upgrade process is completed successfully. The post-upgrade phase is important to ensure that everything works accurately and identify any lingering issues.
Immediate Post-Upgrade Steps
Sign in into your SuiteCRM installation as an administrator right after the upgrade is completed. Locate the Admin panel and run Quick Repair and Rebuild. This process updates the database schema and repairs any inconsistencies. Follow this with a Rebuild Relationships operation to ensure correct configuration of all module relationships.
Data Verification
Check that all your data is correctly displayed, especially in modules that have custom modifications. Look at Leads data specifically, as the upgrade documentation highlights potential issues in this area. Review detail view subpanels across different modules to ensure their loading without any errors. Test the search functionality in various modules to confirm that search definitions were upgraded properly.
Cache and File Management
After the upgrade and initial repairs completion, clear all cache directories. This ensures no interference of old cache files with the new version. Review any backup files created during the troubleshooting process and document all changes that were made. Retain these backups temporarily in case you need to reference the original implementations.
Comprehensive Testing
Conduct thorough testing of all functionalities that your users rely on. Basic operations such as creating, editing, and deleting records in all modules should be tested. Verify that reports are generated correctly, and dashboards are displayed properly. Similarly, test email functionality, calendar synchronization, and any third-party integrations. Some issues might not be apparent from an administrative perspective. Hence, have your key users from different departments test their specific workflows to identify those issues.
Performance Optimization
After confirming everything works correctly, run database optimization routines. Based on your usage patterns, review and update indexes if required. Monitor system performance over the first few days to identify any degradation that might need addressing.
Key Takeaways
The upgrade from SuiteCRM 7.13 to 7.14 is essentially about PHP 8.x compatibility. Most issues that you are likely to encounter stem from stricter type checking, deprecated syntax removal, and modernized coding practices that PHP 8.x enforces.
The most vital preparation step is upgrading PHP before attempting to upgrade SuiteCRM. The most common issues you'll face involve constructor modernization, method signature compatibility, and template syntax updates. All of these are solvable with systematic attention to error messages and proper code updates.
Always work in a test environment first. Document every change you make, both for your own reference and for future upgrades. Keep backups of all files before you alter them. And note that while the upgrade process may seem daunting with all these potential issues, every problem has a clear solution once you understand the cause behind it.
The effort invested in properly executing this upgrade from 7.13 to 7.14 pays dividends in enhanced performance, improved security, and access to new features in SuiteCRM 7.14. More importantly, it positions you well for future upgrades, as you'll have all technical debt cleared up, and your custom code modernized to adopt current best practices.
