Dev Tutorials

Helpful Links

Alex Nassi — Fri, 10 Apr 2026 18:15:03 GMT

Current Revision posted to Dev Tutorials by Alex Nassi on 4/10/2026 6:15:03 PM

Helpful Links

Everything a Sugar Developer needs!

Documentation
Developer Policy Developer Guides Developer & Solution Architect Training DevClub Tutorials API References
Downloads
Mobile Developers SugarCRM Marketplace Download Manager* Developer Builds* *Must be a partner or customer with download permissions to access
Git Repositories (Code)
Open Source contributions Developer Tools & Code Examples
Social
Developer Blog @sugarcrmdev Twitter

Creating Complex Quotes Documents with Doc Merge

Keith Neuendorff — Tue, 27 Jan 2026 00:10:05 GMT

Current Revision posted to Dev Tutorials by Keith Neuendorff on 1/27/2026 12:10:05 AM

Introduction
A need for a complex quote document
A new approach
The technical details plus the code and template

Introduction

Doc Merge is a very useful but underused feature in Sugar. We have leveraged it in a number of projects and recently had a chance to use it for a Quote generation project for a client that required us to think creatively to produce a complex quote document that also required a reasonably short document generation time.

A need for a complex quote document

The client needed to be able to provide quotes that had multiple scenarios that could show multiple items and the costs for each item across multiple years. They had previously developed a custom Line Item module that could represent an item and the pricing for a single year and associate it to a scenario. An item could be in one or more scenarios. Even though this was done with a custom module, the approach we used can also be applied to the stock Quoted Line Items module.

Here is an example of a set of Line Items that represents two scenarios with multiple items.

They had a way to define their complex quote with the data for their custom module but they needed a way to translate it to a document they could present to their customers. They had an initial idea for the document which we then developed into a full version. Each scenario would exist as a separate section in the generated document. In each section, every item in that scenario would have its own table. In each of those tables there would be a line for each year showing the pricing being offered for that item in a single year. The following is an example of what we were trying to generated for a document using the previous example data.

With some effort, a person could sort the data into those sections and tables to produce a document, but it is error prone and time consuming. There was a definite value to being able to have Doc Merge inside Sugar produce the document.

Our initial solution had a way of getting all of the item numbers for a scenario, looping through all of the items to create a table for each one and then for each item table again looping through the Line Items to produce a list of the line items ordered by year. This approach used the standard looping for a related module that Doc Merge provides and it worked and produced the desired quote.

However, we found that beyond very simple cases, the time to generated the document was growing very long. And the more scenarios, items, and years we added Line Item records for, the longer the generation time would get. For a few scenarios with a few items with less than five years, we were getting generation times of over 30 minutes and it was getting worse as we added more data. The two layers of looping through the related records was simply not going to work.

A new Doc Merge approach

After brainstorming the technical side of this problem, we came up with a new approach for creating the data that would be picked up by Doc Merge. We decided to “pre-render” the data tables for each line item in a scenario so that Doc Merge would only have a single loop for each scenario where it would just need to pick up the block of data to be shown in each table. This does required a code customization, but after considering a few ways to do it, we settled on using just a before_save logic hook on the Line Item module.

The logic hook we made triggers when a Line Item record is created or updated. When this hook is triggered, the table for that line item is generated and saved and then all of the other tables are also updated. This full update of all tables was done to cover the case where a Line Item record was initially in one scenario/item but was moved to another scenario/item, which guarantees that all pre-rendered data is correct. This approach in the logic hook did not add any noticeable time to the save of a Line Item, but it did improve the generation time of a quote document from 30+ minutes to an average of 15 seconds. We also found that adding more scenarios, items, and years added very little time under the new approach and it satisfied the client needs and provided a good user experience.

The technical details plus the code and template

To make this approach work, we needed to specify on the quote what the first year covered by the Line Items would be. This was passed down to the individual Line Items on a calculated field. The pre-rendered table data is saved on the earliest year Line Item record for each table.

For the text in the tables, we needed to have all the pre-rendered text across multiple lines be presented as one text block in the resulting table. We generated column divisions in that text data with the “|” character substituting for vertical lines in the data and used a monospaced font to make sure everything lined up. We did look at using tab characters in the template to line up columns, but the complexity was judged to not be worth it.

Here is the code for the logic hook and the template file that was used. We hope that this information provides some inspiration for solving interesting client customization challenges.

<?php
if (!defined('sugarEntry') || !sugarEntry) define('sugarEntry', true);

class CollectMatchingLineItemsHook
{
    /**
     * before_save hook: collect other line items under the same parent Quote
     * with quantity == 100 and attach them to $bean->matching_line_items (non-persistent)
     */
    public function beforeSaveLineItemProcessing(&$bean, $event, $arguments)
    {
        $parentQuoteId = $this->getParentQuoteId($bean);
        if (empty($parentQuoteId)) {
            $bean->line_item_group_summary_c = '';
            $bean->save_flag_c = '';
            return;
        }

        $subChar = '^';
        $cpad = 6;
        $vpad = 7;
        $newRecordLine = '';
        if (empty($bean->fetched_row['id'])) {
            if($bean->scenario_key_value_c == '') {
                if(strval($bean->hide_line_item_c) !== '1') {
                    $newRecordLine = str_pad(strval($bean->year_text_c),$cpad)." |      ".sprintf("%{$vpad}s", number_format($bean->volume))." |  ".$this->formatDecimal($bean->base_unit_price)."|  ".$this->formatDecimal($bean->unit_surcharge)."|  ".$this->formatDecimal($bean->total_unit_price).$subChar;
                }
            }
        }

        if($bean->save_flag_c == 1) {
            if($bean->scenario_key_value_c == '') {
                $bean->line_item_group_summary_c = '';
            }
            else {
                $this->updateLineItemSummary($bean);
            }
            $bean->save_flag_c = '';
        }
        else {
            if($bean->scenario_key_value_c == '') {
                $bean->line_item_group_summary_c = '';
                $this->getAndSaveQuoteBeanKeyItems( $parentQuoteId, null, $newRecordLine, $bean->scenario_item_group_c );
            }
            else {
                $this->updateLineItemSummary($bean);
                $this->getAndSaveQuoteBeanKeyItems( $parentQuoteId, $bean->id );
            }
        }
        $bean->new_record_line_text_c = '';
    }


    /* Returns array of beans for the related items
    * The primary key $bean will always be the one in the first [0] position
    */
    protected function updateLineItemSummary( &$lineItemBean ) {
        $parentQuoteId = $this->getParentQuoteId($lineItemBean);
        if (empty($parentQuoteId)) {
            $lineItemBean->line_item_group_summary_c = '';
            return;
        }

        $newTextYear = '';
        if($lineItemBean->new_record_line_text_c !== '') {
            $newTextYear = substr($lineItemBean->new_record_line_text_c, 0, 4);
        }
        $lineArray = [];

        $itemBeansOnQuote = $this->getItemBeansForQBean($parentQuoteId, $lineItemBean->scenario_number, $lineItemBean->item_number);

        $subChar = '^';
        $cpad = 6;
        $vpad = 7;
        $lineItemSummaryNew = '';
        if(strval($lineItemBean->hide_line_item_c) !== '1') {
            $lineItemSummaryNew .= str_pad(strval($lineItemBean->year_text_c),$cpad)." |      ".sprintf("%{$vpad}s", number_format($lineItemBean->volume))." |  ".$this->formatDecimal($lineItemBean->base_unit_price)."|  ".$this->formatDecimal($lineItemBean->unit_surcharge)."| ".$this->formatDecimal($lineItemBean->total_unit_price).$subChar;
            $lineArray[$lineItemBean->year_text_c] = str_pad(strval($lineItemBean->year_text_c),$cpad)." |      ".sprintf("%{$vpad}s", number_format($lineItemBean->volume))." |  ".$this->formatDecimal($lineItemBean->base_unit_price)."|  ".$this->formatDecimal($lineItemBean->unit_surcharge)."|  ".$this->formatDecimal($lineItemBean->total_unit_price).$subChar;
        }
        $summaryRecordId = $lineItemBean->id;
        foreach ($itemBeansOnQuote as $r) {
            if(strval($r->hide_line_item_c) !== '1') {
                if($r->id == $lineItemBean->id) {
                    //nothing
                }
                else {
                    $lineItemSummaryNew .= str_pad(strval($r->year_text_c),$cpad)." |      ".sprintf("%{$vpad}s", number_format($r->volume))." |  ".$this->formatDecimal($r->base_unit_price)."|  ".$this->formatDecimal($r->unit_surcharge)."|  ".$this->formatDecimal($r->total_unit_price).$subChar;
                    $lineArray[$r->year_text_c] = str_pad(strval($r->year_text_c),$cpad)." |      ".sprintf("%{$vpad}s", number_format($r->volume))." |  ".$this->formatDecimal($r->base_unit_price)."|  ".$this->formatDecimal($r->unit_surcharge)."|  ".$this->formatDecimal($r->total_unit_price).$subChar;
                }                    
            }
        }
        $pos = strrpos($lineItemSummaryNew, $subChar);
        if($pos !== false)
        {
            $lineItemSummaryNew = substr_replace($lineItemSummaryNew, '', $pos, 1);
        }
        $lineItemSummaryNew .= "\n".$lineItemBean->new_record_line_text_c;

        $reassemblItemsSummaryNew = '';
        $extraLineInserted = false;
        foreach($lineArray as $k => $v) {
            if ($k > $newTextYear && !$extraLineInserted) {
                $reassemblItemsSummaryNew .= $lineItemBean->new_record_line_text_c;
                $extraLineInserted = true;
            }
            $reassemblItemsSummaryNew .= $v;
        }
        if($extraLineInserted == false) {
            if($lineItemBean->hide_line_item_c !== '1') {
                $reassemblItemsSummaryNew .= $lineItemBean->new_record_line_text_c;
            }
        }   
        $reassemblItemsSummaryNew = rtrim($reassemblItemsSummaryNew, "^"); 
        $reassemblItemsSummaryNew = str_replace($subChar, "\n", $reassemblItemsSummaryNew);
        $lineItemBean->line_item_group_summary_c = $reassemblItemsSummaryNew;
    }


    /* Returns array of beans for the related items
    * The primary key $bean will always be thte on ein the first [0] position
    */
    protected function getAndSaveQuoteBeanKeyItems( $quoteId, $omitBeanId = null, $newRecordTextLine = '', $newRecordKey = '' ) {
        $quoteBean = BeanFactory::retrieveBean('Quotes', $quoteId);
        if(!$quoteBean) {
            return false;
        }

        $quoteBean->load_relationship('id_li_quotes');
        $relatedBeans = $quoteBean->id_li_quotes->getBeans();    
        $filteredBeans = array();

        foreach($relatedBeans as $relatedBean) {
            if($relatedBean->scenario_key_value_c != '') {
                if($relatedBean->id !== $omitBeanId) {
                    $relatedBean->save_flag_c = 1;
                    $filteredBeans[] = $relatedBean;
                }
                else {
                    // continue;
                }
            }
        }

        foreach($filteredBeans as $b) {
            $b->save_flag_c = 1;

            if($newRecordKey == $b->scenario_key_value_c) {
                $b->new_record_line_text_c = $newRecordTextLine;
            }
            else {
                $b->new_record_line_text_c = '';
            }
            $b->save();
        }
    }


    /* Returns array of beans for the related items
    * The primary key $bean will always be thte on ein the first [0] position
    */
    protected function getItemBeansForQBean( $quoteId, $scenarioNumber, $itemNumber ) {
        $quoteBean = BeanFactory::retrieveBean('Quotes', $quoteId);
        if(!$quoteBean) {
            return false;
        }

        $quoteBean->load_relationship('id_li_quotes');
        $relatedBeans = $quoteBean->id_li_quotes->getBeans();    
        $filteredBeans = array();

        foreach($relatedBeans as $relatedBean) {
            if($relatedBean->scenario_number == $scenarioNumber && $relatedBean->item_number == $itemNumber ) {
                $filteredBeans[] = $relatedBean;
            }
        }

        //Bubble sort of relatedBeans by year_text_c
        $n = count($filteredBeans);
        for ($i = 0; $i < $n - 1; $i++) {
            for ($j = 0; $j < $n - $i - 1; $j++) {
                if (strcmp($filteredBeans[$j]->year_text_c, $filteredBeans[$j + 1]->year_text_c) > 0) {
                    $temp = $filteredBeans[$j];
                    $filteredBeans[$j] = $filteredBeans[$j + 1];
                    $filteredBeans[$j + 1] = $temp;
                }
            }
        }
        return $filteredBeans;
    }


    /**
     * Attempt to determine the parent Quote ID for a line-item bean.
     */
    protected function getParentQuoteId($bean)
    {
        try {
            if ($bean->load_relationship('id_li_quotes')) {
                $related = $bean->id_li_quotes->getBeans();
                if (!empty($related)) {
                    $ids = array_keys($related);
                    return reset($ids);
                }
            }
        } catch (Exception $e) {
            // ignore
        }
        return null;
    }

    protected function formatDecimal($number)
    {
        $formattedNumber = sprintf("%.5f", $number);
        $paddedString = str_pad($formattedNumber, 12, " ", STR_PAD_LEFT).' ';
        return $paddedString;
    }
}

?>

sugarclub.sugarai.com/.../SugarClubDocMergeTemplateEx.docx

Sugar 25.2 Customization Guide

Rafael Fernandes — Wed, 01 Oct 2025 18:31:31 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 10/1/2025 6:31:31 PM

The purpose of this document is to provide insight to Sugar Developers for upgrading custom Sugar code, extensions, and integrations to the Sugar 25.2 release. This guide focuses on changes in Sugar 25.2 that could cause an immediate impact on Sugar customizations and integrations built for earlier Sugar versions.

Please check out the Sugar 25.2 Developer Webinar recording for more developer highlights. For Admin and End User release notes, please visit the Sugar 25.2.0 Release Notes.

User Experience Updates

Modernized Dropdown Editor

In this release, we’ve modernized the Dropdown Editor UI, transitioning from BWC to Sidecar for a cleaner, more streamlined admin experience. Admins can now manage entire dropdown lists from a single view—no more editing one row at a time.

What’s new:

Redesigned Interface: New Sidecar layout with updated header, inline editing, and consistent list view styling. Supports dark mode.
Formatting Flow Fix & Toggle Control: Chart colors no longer drive dropdown styling; instead, formatting is now defined at the dropdown level and pushed to charts for consistency..
- New "Enable formatting in dropdown" toggle added per dropdown.
- Toggle is enabled by default for: sales_stage_dom, quote_stage_dom, case_status_dom, and lead_status_dom.
- When disabled, formatting is hidden in the UI but preserved and still used in charts.
- When enabled, users can customize styles (colors, fonts) via the conditional formatting panel.
- Chart colors fallback to the chart palette for items without formatting; white and black are excluded and replaced.
Conditional Formatting: New Conditional Format Options control panel that allows users to customize the appearance of dropdown values using styles, icons, and colors.
- The following stock/out-of-the-box dropdowns were predefined with conditional formatting for awareness and usability: sales_stage_dom, quote_stage_dom, case_status_dom, lead_status_dom
- Formatting will be reflected as soon as saved on List View, Record View, Focus Drawer, Reports, Other components using the dropdown values, All views in sugar
- Even if user selects RGB, we only reflect Hex number in the input
Add New Rows: Easily add multiple items with editable fields for Display Label and Classification (for sales_stage_dom). Only completed rows are saved.
Improved Search: Real-time search across Item Name and Display Label fields with partial match support.
Restore to Default: Revert dropdowns to their original out-of-the-box (OOTB) state, including default sort order. Available only for OOTB lists.
Bulk Editing & Reduced Clicks: Edit multiple rows at once and save all changes in one action.
Sort by Display Label: New sort button allows ascending/descending sort; order persists across sessions and is saved.
Inline Editing & Deletion: Edit Display Label and Classification fields directly; delete items with confirmation.
Drag-and-Drop Reordering: Rearrange items via drag-and-drop. Changes are saved on click.
Unsaved Change Warning: Users are prompted before navigating away from unsaved edits.

Note: Devs can still define custom styles (e.g., backgroundColor, textColor, icon, iconColor) for dropdown fields using extension framework (custom/application/Ext/DropdownsStyle/dropdowns_style.ext.php).

Adding support to Shared Drive files on Google Drive

The Google Drive connector for Sugar has been enhanced to support access to shared files. Users can now interact with files that are shared with them or located in Shared Drives. This includes the ability to set a Shared Drive as the root path, define variable file paths on record views, and seamlessly navigate through folders within Shared Drives. Additionally, users can switch between viewing files in "My Files," "Shared with me," and Shared Drives. If a user attempts to access a Shared Drive they do not have permission to view, a message will appear within the dashlet indicating the lack of access, with the option to navigate to an accessible area instead.

Enable Row-Level Actions in List View Dashlets

In this release, we've added row-level actions on List view dashlets, enabling users to take immediate action on records directly within dashboards and Focus Drawers. This improvement aligns with Sugar’s goal of UX efficiency, reducing clicks and streamlining workflows. The available actions now mirror those found in the standard module list views, using the familiar action menu design for consistency. The preview option has been intentionally excluded to suit the context of dashlets.

Note: This functionality has been implemented as a new plugin and integrated into relevant views. Custom or extended views that include inline editing may require a review to ensure compatibility with this update.

Opportunity Delta in List and Record Views

To improve visibility into how opportunities evolve over time, we've introduced a new Change Over Time dropdown labeling "Show changes" across Opportunity list views (module and subpanels), record views, and dashlets (LV & RV). This enables sellers and managers to quickly see cumulative changes without piecing together discrete audit log entries.

Key Features:

New Time-Based Comparison Dropdown with four options: None, Last 7 days, Last 14 days, Last 30 days.
Compares current opportunity data to its value at the end of the selected past day.
Highlights value changes in::
- Likely Amount
- Expected Close Date
- Sales Stage

Selection is sticky per view (e.g., list view and record view can maintain independent settings).
When navigating using the focus icon, the source view’s selection is respected and carried to the target dashlets.
If no prior context exists, the default selection is Last 7 days.

Note: This feature leverages historical data available through Sugar's Enhanced Forecasting and is only available to customers with the Opportunities dataset. For customers without this dataset, the feature will not be functional.

Add Transcription, Recording, and Summary fields on the Meetings module

We're improving Meetings module in this release by adding transcription, recording and summary fields to the record view in view/edit modes.

Dynamic Record View Dashlet Rendering for Flex Relate Fields in Focus Drawer

Enhanced the Focus Drawer experience by enabling dynamic rendering (new tab) of related records defined via flex relate ("Relate To") fields within a Record View Dashlet. Users can now configure a dashlet to automatically display the appropriate related record based on the selected module and record in the flex relate field without needing to manually toggle between module tabs. This improves context access and ensures only relevant record views are shown, improving usability and efficiency when working across related modules.

Sugar REST API updates

This Sugar release introduces REST v11_27.

Dropdown Editor

Set details of dropdown.

PUT <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Get details of dropdown that can be changed.

GET <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Create Dropdown DOM issue as a php-file in customer storage directory.

POST <sugar instance>/rest/v11_27/Administration/dropdownEditor/create

Enhancements to Package Builder APIs’ error handling

We have improved our Package Builder API for clear and consistent error codes that are returned for known failure scenarios.

For Example: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error.

Error messages include actionable context (e.g., missing fields, invalid formats, unsupported package types)

All existing error-prone areas are covered (e.g., input validation, external service failures, internal exceptions)

Fallbacks or default behaviors are implemented where appropriate

Errors follow our API error response standard (e.g., HTTP status codes, message structure)

The following endpoints were improved:

POST <sugar instance>/rest/v11_27/Administration/package/customizations

POST <sugar instance>/rest/v11_27/Administration/package

GET <sugar instance>/rest/v11_27/Administration/package/id

POST <sugar instance>/rest/v11_27/Administration/package/remote

POST <sugar instance>/rest/v11_27/Administration/package/data

POST <sugar instance>/rest/v11_27/Administration/package/getRemotePackages

Historical Deltas API

Retrieves historical delta changes for a module based on a timestamp and list of records.

POST <sugar instance>/rest/v11_27/historically/delta

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

In this release, we've updated all minor and patch versions of our PHP libraries as declared in the composer. Since these are minor and patch updates, no breaking changes are expected. The updates primarily include newly generated models and improved PHP version compatibility.

aws/aws-sdk-php             3.342.19 AWS SDK for PHP - Use Amazon Web Services in your PHP project
doctrine/dbal               3.9.4    Powerful PHP database abstraction layer (DBAL) with many features for da...
egulias/email-validator     4.0.4    A library for validating emails against several RFCs
guzzlehttp/guzzle           7.9.3    Guzzle is a PHP HTTP client library
laminas/laminas-escaper     2.16.0   Securely and safely escape HTML, HTML attributes, JavaScript, CSS, and URLs
league/oauth2-client        2.8.1    OAuth 2.0 Client Library
microsoft/microsoft-graph   2.29.0   The Microsoft Graph SDK for PHP
rector/rector               2.0.11   Instant Upgrade and Automated Refactoring of any PHP code
rlanvin/php-rrule           2.5.2    Lightweight and fast recurrence rules for PHP (RFC 5545)

PHP-Parser

Sugar utilizes a PHP library called PHP-Parser Its purpose is to simplify static code analysis and manipulation.

There are major internal changes in this library, if you use them, please refer to this library’s upgrade procedure here.

nikic/php-parser → ^v5.4.0

JS Library Upgrades

Low to Minimum Impact Upgrade on various JS libraries

We have performed a patch upgrade on several JavaScript libraries used within our codebase. These upgrades are considered low to minimum impact and should not affect Sugar developers in any meaningful way. Most of the components upgraded are used for internal build processes or tooling.

There are no known breaking changes associated with these updates.

@babel/core -> 7.27.4
@sugarcrm/ventana -> 1.1.19
handlebars -> 4.7.8-sugarcrm
babel-loader -> 9.2.1
bootstrap  -> 5.3.7
gulp -> 5.0.1
jquery-migrate -> 3.5.2
sinon -> 21.0.0
tailwindcss -> 3.4.17
underscore -> 1.13.7
webpack -> 5.99.9
eslint-plugin-import -> 2.31.0
cure53/DOMPurify -> 3.2.6
stylelint-config-standard -> 38.0.0

DOMPurify JS Library

The DOMPurify library is now integrated as a standard dependency, replacing the previously used forked version. This update improves the maintainability and transparency of the codebase by aligning with standard package management practices. Functionality that relies on DOMPurify remains unchanged, and the library is properly bundled and referenced throughout the application.

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Sugar now supports sending emails via Microsoft Exchange Online using OAuth 2.0, in alignment with Microsoft’s announcement to permanently disable Basic Authentication for SMTP AUTH in Exchange Online starting September 2025. This enhancement ensures continued compatibility and improved security by allowing outbound email functionality to operate without relying on SMTP when using Microsoft OAuth 2.0.

With this update, when an outbound email account is configured using Microsoft OAuth 2.0, Sugar will send emails through the Microsoft Graph API instead of SMTP. This change is specific to Exchange Online accounts using Microsoft OAuth and does not impact other connection types, such as username/password or Google OAuth.

To enable this functionality, administrators must register an application in Azure with the necessary API permissions (Mail.Send, Mail.Read, IMAP.AccessAsUser.All, offline_access) and configure the Microsoft connector in Sugar with the application's client ID and secret. Once authorized, the email status will indicate successful authentication, allowing emails to be sent using the new method.

This transition will occur automatically, requiring no action from customers. However, the shift to the Microsoft Graph API will require adjusting OAuth scopes, necessitating users to re-authorize their email accounts in Sugar.

Note: This improvement has been backported to Sugar 25.1.x.

Configurability updates

Improved Control Over Field Updates by Process Definitions

We are enhancing the control over the fields that can be modified by Process Definitions. By default, only fields that are visible in the user interface will be eligible for updates. Fields not exposed on the frontend will no longer be modified automatically by these processes, in other words, if the field is available to be added to any UI it means it is exposed, doesn't necessarily mean it has be in a Record View for example.

For teams needing more specific behavior, it’s now possible to configure a denylist of fields that should not be updated by Process Definitions. This provides greater flexibility and precision in how automation interacts with your data. You can define this using a new $sugar_config setting. For example, the configuration below prevents field_to_block_1 and field_to_block_2 in ModuleName1 from being updated by Process Definitions:

$sugar_config['bpm_denylisted_fields'] = [
  'ModuleName1' => ['field_to_block_1', 'field_to_block_2'],
  'ModuleName2' => ['another_field_to_block'],
];

Note: When this sugar_config is set, only the specified fields will be blocked — regardless of their visibility in the user interface.

Sugar Config Settings

Setting Name	Default	Override Example	Description
bpm_denylisted_fields	[]	$sugar_config['bpm_denylisted_fields'] = [ 'ModuleName1' => ['field_to_block_1', 'field_to_block_2'], 'ModuleName2' => ['another_field_to_block']];	This new config will be used to include specific fields in the 'allowed fields to be modified by BPM'.
features.enableStrictContentSecurityPolicy	false	$sugar_config['features']['enableStrictContentSecurityPolicy'] = true;	If enabled, the application will enforce a strict Content Security Policy (CSP)

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

As part of our ongoing efforts to modernize Sugar Core, this release removes support for the legacy include/modules_override.php file path used for module metadata customizations. This path was used in versions prior to Sugar 6.3.x but is no longer recommended or necessary. You should be using the supported Extensions Framework with the Include extension for all metadata customizations.

A new healthcheck bucket 'F' (manual customization) has been added to ensure compatibility to this version.

Removal of Unused Platform

As part of ongoing SugarCore cleanup efforts, the kiosk platform has been removed to streamline with our products and services.

Removing gulp-filter JS lib

The gulp-filter library has been removed from the project after verifying it was only used in a single instance within a Gulp task. Its functionality has been replaced with a native filter function applied directly within the stream. This change retains the original filtering logic and preserves the existing behavior and output of the task.

Removing uglify-js and socket.io JS lib

Removed the legacy socket.io dependency from package.json as it was no longer used anywhere in the codebase. This also removed its transitive dependency uglify-js.

Data Changes

New Indexes for Calls and Meetings

To enhance the performance of queries involving Calls and Meetings using our FilterApi, we’ve added new indexes to the corresponding module definitions (vardefs). These indexes are designed to optimize data retrieval on such modules by our FilterApi:

idx_calls_series_event_deleted
- 'series_deleted', 'event_type', 'deleted
idx_calls_date_mod_rep_parent_id -
- 'date_modified', 'repeat_parent_id

Platform Updates

Scheduler Jobs Now Run on a Consistent Timezone

We’ve updated the Scheduler UI to make it easier to see exactly when jobs will run—based on your local timezone. No more mental math or guesswork.

While this improves clarity in the interface, the underlying execution behavior hasn’t changed yet: jobs still run based on the timezone of the system user (ID = 1). We’re actively working to align the backend behavior with UTC-based scheduling in a future release.

For full details or clarification, read the retraction here.

Enhanced SystemProcessLock Handling to Prevent Redundant Execution During Admin QRR

Resolved an issue where regular user requests could unintentionally trigger cascading expensive operations, such as metadata and language cache rebuilds, during or immediately after an admin-initiated Quick Repair & Rebuild (QRR). Previously, when cache files were deleted by an admin QRR, regular users encountering missing cache would queue behind a system-level lock and subsequently attempt to perform the same rebuild operations once the lock was released. This behavior caused unnecessary server load, timeouts, and a degraded user experience.

With this enhancement, the lock handling logic has been updated to prevent non-admin users from executing expensive operations when the lock cannot be acquired. Instead, such requests will now safely return without action, ensuring that only admin users can initiate these processes. This significantly reduces server load and improves system responsiveness during cache rebuilding scenarios.

Note: This improvement has been backported to Sugar 25.1.x.

Improved Deep Linking Support for SugarCRM on Mobile Devices

In this release, we have implemented improvements to the experience of opening Sugar links from mobile devices. This update addresses inconsistent behaviors when accessing CRM links from email or messages, ensuring a more predictable and seamless user journey on both Android and iOS platforms.

What's new:

Universal Link Support: SugarCRM mobile app now uses Universal Links (iOS) and App Links (Android) to seamlessly redirect users from supported emails/messages directly into the app—bypassing the mobile browser when possible.
Smart App Prompts: Users without the SugarCRM mobile app installed are now prompted to download it from the App Store or Google Play when tapping a SugarCRM link.
Improved Workflow Link Behavior: Links generated from workflows (e.g., SugarBPM) now attempt to open in the app rather than defaulting to the mobile browser.
Browser Consistency Fixes: Addressed inconsistent behavior across third-party browsers (e.g., Edge, Chrome) especially on iPhone, ensuring reliable app-switch prompts.

Note: Support for this feature on custom or on-premise domains requires configuration changes and updates to the Mobile App to include those domains. Customers should contact support for implementation guidance.

Enhanced Content Security Policy (CSP) for Improved Application Security

As part of our ongoing commitment to application security, we are introducing Strict Content Security Policy (CSP). This policy significantly reduces the risk of malicious script execution by restricting the sources from which scripts can be loaded.

To support this enhancement, we’ve refactored the frontend code to:

Remove inline event handlers and javascript: URIs
Add nonce attributes to all <script> elements

These changes ensure that only trusted scripts are executed in the browser.

This feature is configurable via App.config ($sugar_config['features']['enableStrictContentSecurityPolicy']) and requires a QRR after being toggled.

The rollout will follow a phased approach, beginning in report-only mode to monitor violations, with full enforcement to follow in both core and customization layers in future releases.

Declarative Metadata Refactoring

As part of our ongoing efforts to make Sugar's metadata fully declarative and serializable, this release includes the first phase of refactoring non-declarative components within Sugar Core. Previously, some metadata included conditional logic that needed refactoring. We’ve begun restructuring some areas to align with a declarative format, laying the groundwork for the new Metadata generation we've discussed here.

Replace the TCPDF with SugarPdf in MapsGenerator

In this release, we've updated MapsGenerator.php::createPDF() to use SugarPDF instead of directly using TCPDF.

Added Backend Framework for Dropdown Classifications

In this release, we've introduced backend support for a generic dropdown classification framework as part of the Dropdown Editor enhancements. This replaces hardcoded logic (e.g., sales_stage_dom) with a scalable, metadata-driven approach, enabling configurable mappings between dropdown values and classification categories..

Key details:

Classifications are defined using metadata and stored via the extension framework.
A classification includes:
- A unique identifier
- Translatable classification options (app_list_strings)
- Mappings between dropdown values and classification categories
No API or UI changes in this implementation — a helper class is provided to handle loading and saving classification data.
Designed to support future use with multiple classifications per dropdown.

Note: This implementation does not expand classifications to all dropdowns yet, sales_stage_dom only

Prevent Data Loss on Market MLP Uninstallation and upgrade

In this release, we're addressing a critical issue where upgrading to Market MLP version 25.1 resulted in unintended data loss, specifically affecting connector setting configurations that were expected to persist through the uninstallation process. Additionally, the upgrade mechanism has been improved to ensure proper cleanup of residual files and directories from previous installations, which previously caused version conflicts, broken dependencies, and unexpected behavior in the new version. These enhancements ensure a smoother and more reliable upgrade experience..

Note: If on upgrade customer does not have active market license then the features would not show up after upgrade even if they have MLP installed.

SugarLive compatibility with the V2 console for Amazon Connect

For SugarLive, Sugar provides SugarServeSampleBot.zip which was only compatible with the Amazon Lex V1 console. However, in Amazon Connect, there is a warning about the Lex V1 console being discontinued after September 15, 2025. We have now implemented and updated the SugarServeSampleBot.zip file to make it compatible with the V2 console.

Bug Fixes

Fixed an issue with the FilterApi that was returning extra fields in the response payload even when filtering by using args fields.
Fixed QRR Occasionally Fails to Rebuild Module/Class Cache, Causing Outages and UI Errors caused by race conditions during concurrent or overlapping QRR executions or user requests during cache rebuild.
Fixed an issue for a specific scenario where user licenses were failing to update
Fixed an issue that a calculated field using the countConditional function in combination with a relate field (e.g. countConditional($notes,"name",createList("test"))) caused a “Too many tables” error when a large number of one-to-one relationships were created between modules
Fixed an issue on Uncaught TypeError: Sugarcrm\\Sugarcrm\\Security\\Escaper\\Escape::html() caught on upgrade from 14.0.1 to 25.1
Fixed an issue where Sugar Automate licenses and UI elements disappear after manual license validation and only reappear when an online validation is performed.
Fixed an issue with our silentUpgrader that, in some cases, the healthcheck was still executed during the upgrade even if the instance was configured with “Bypass Healthcheck” option enabled.
Fixed an issue where People names (Contacts, Leads, Users) currently do not have a display option for how names are traditionally written in Chinese. The LastFirst name format has been added to the default list to support proper name display across the product (e.g., Contacts list view, record view, Lead, and Assigned To fields)
Fixed an issue on the Case Summary Chart and Opportunity Metrics Chart (migrated from Sucrose to Chart.JS) where, if only one label was present, it displayed at the bottom of the chart in a space too small to display it properly
Fixed an issue where Users were receiving a permission error when trying to use Doc Merge for Quote records and have {currency_name.iso4217} in the template.
Fixed an issue where regular users triggered redundant rebuilds after admin QRR due to SystemProcessLock, causing server overload due to multiple expensive operations running simultaneously.
Fixed an issue where Generating a Quote from the Revenue Line Item detail view doesn't allow the generated Quote to be saved.
Fixed an issue where Update Momentum of In-Progress Smart Guides' scheduler fails on NULL score or point values.
Fixed an issue where a single email failure due to a Laminas error could halt the entire import scheduler, leaving the email unread and causing repeated failures.
Fixed an issue where Developer user encounters error when editing Timeline. Developer only users will not see this option but users with Admin and Developer access will.
Fixed an issue when a user has a profile date format that is not ISO compliant, the date outputted into a PDF is not valid in ISO format, Sugar was using current date but should interpret that date correctly.

Sugar Core Security Updates

As part of our ongoing efforts to keep Sugar clean, fast, reliable, and most importantly secure, we have updated Sugar Core code in different areas of the application such as Package Scanner, Studio, Module Installer, UI rendering, API endpoints, Legacy SOAP API, File Uploads, Portal, PII Fields, ACL rules, Legacy Workflows, Smart Guides, HTTP Headers and BWC modules. Not only those changes but we've cleaned up and improve our logging messages around deprecations.

Note: Some of those security improvements were backported to Sugar 25.1.x.

Healthcheck Updates

Built a health scanner tool to detect cloud instances using SugarMarket MLP versions < 2.2 and send it to bucket F
Built a healthcheck to detect and support the removal of the legacy include/modules_override.php file path and send it to bucket F

Tags: Sugar 25.2

Sugar 25.2 Customization Guide

Rafael Fernandes — Mon, 29 Sep 2025 13:40:54 GMT

Revision 3 posted to Dev Tutorials by Rafael Fernandes on 9/29/2025 1:40:54 PM

Please check out the Sugar 25.2 Developer Webinar recording for more developer highlights. For Admin and End User release notes, please visit the Sugar 25.2.0 Release Notes.

User Experience Updates

Modernized Dropdown Editor

What’s new:

Redesigned Interface: New Sidecar layout with updated header, inline editing, and consistent list view styling. Supports dark mode.
Formatting Flow Fix & Toggle Control: Chart colors no longer drive dropdown styling; instead, formatting is now defined at the dropdown level and pushed to charts for consistency..
- New "Enable formatting in dropdown" toggle added per dropdown.
- Toggle is enabled by default for: sales_stage_dom, quote_stage_dom, case_status_dom, and lead_status_dom.
- When disabled, formatting is hidden in the UI but preserved and still used in charts.
- When enabled, users can customize styles (colors, fonts) via the conditional formatting panel.
- Chart colors fallback to the chart palette for items without formatting; white and black are excluded and replaced.
Conditional Formatting: New Conditional Format Options control panel that allows users to customize the appearance of dropdown values using styles, icons, and colors.
- The following stock/out-of-the-box dropdowns were predefined with conditional formatting for awareness and usability: sales_stage_dom, quote_stage_dom, case_status_dom, lead_status_dom
- Formatting will be reflected as soon as saved on List View, Record View, Focus Drawer, Reports, Other components using the dropdown values, All views in sugar
- Even if user selects RGB, we only reflect Hex number in the input
Add New Rows: Easily add multiple items with editable fields for Display Label and Classification (for sales_stage_dom). Only completed rows are saved.
Improved Search: Real-time search across Item Name and Display Label fields with partial match support.
Restore to Default: Revert dropdowns to their original out-of-the-box (OOTB) state, including default sort order. Available only for OOTB lists.
Bulk Editing & Reduced Clicks: Edit multiple rows at once and save all changes in one action.
Sort by Display Label: New sort button allows ascending/descending sort; order persists across sessions and is saved.
Inline Editing & Deletion: Edit Display Label and Classification fields directly; delete items with confirmation.
Drag-and-Drop Reordering: Rearrange items via drag-and-drop. Changes are saved on click.
Unsaved Change Warning: Users are prompted before navigating away from unsaved edits.

Adding support to Shared Drive files on Google Drive

Enable Row-Level Actions in List View Dashlets

Opportunity Delta in List and Record Views

Key Features:

New Time-Based Comparison Dropdown with four options: None, Last 7 days, Last 14 days, Last 30 days.
Compares current opportunity data to its value at the end of the selected past day.
Highlights value changes in::
- Likely Amount
- Expected Close Date
- Sales Stage

Selection is sticky per view (e.g., list view and record view can maintain independent settings).
When navigating using the focus icon, the source view’s selection is respected and carried to the target dashlets.
If no prior context exists, the default selection is Last 7 days.

Add Transcription, Recording, and Summary fields on the Meetings module

We're improving Meetings module in this release by adding transcription, recording and summary fields to the record view in view/edit modes.

Dynamic Record View Dashlet Rendering for Flex Relate Fields in Focus Drawer

Sugar REST API updates

This Sugar release introduces REST v11_27.

Dropdown Editor

Set details of dropdown.

PUT <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Get details of dropdown that can be changed.

GET <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Create Dropdown DOM issue as a php-file in customer storage directory.

POST <sugar instance>/rest/v11_27/Administration/dropdownEditor/create

Enhancements to Package Builder APIs’ error handling

We have improved our Package Builder API for clear and consistent error codes that are returned for known failure scenarios.

For Example: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error.

Error messages include actionable context (e.g., missing fields, invalid formats, unsupported package types)

All existing error-prone areas are covered (e.g., input validation, external service failures, internal exceptions)

Fallbacks or default behaviors are implemented where appropriate

Errors follow our API error response standard (e.g., HTTP status codes, message structure)

The following endpoints were improved:

POST <sugar instance>/rest/v11_27/Administration/package/customizations

POST <sugar instance>/rest/v11_27/Administration/package

GET <sugar instance>/rest/v11_27/Administration/package/id

POST <sugar instance>/rest/v11_27/Administration/package/remote

POST <sugar instance>/rest/v11_27/Administration/package/data

POST <sugar instance>/rest/v11_27/Administration/package/getRemotePackages

Historical Deltas API

Retrieves historical delta changes for a module based on a timestamp and list of records.

POST <sugar instance>/rest/v11_27/historically/delta

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

aws/aws-sdk-php             3.342.19 AWS SDK for PHP - Use Amazon Web Services in your PHP project
doctrine/dbal               3.9.4    Powerful PHP database abstraction layer (DBAL) with many features for da...
egulias/email-validator     4.0.4    A library for validating emails against several RFCs
guzzlehttp/guzzle           7.9.3    Guzzle is a PHP HTTP client library
laminas/laminas-escaper     2.16.0   Securely and safely escape HTML, HTML attributes, JavaScript, CSS, and URLs
league/oauth2-client        2.8.1    OAuth 2.0 Client Library
microsoft/microsoft-graph   2.29.0   The Microsoft Graph SDK for PHP
rector/rector               2.0.11   Instant Upgrade and Automated Refactoring of any PHP code
rlanvin/php-rrule           2.5.2    Lightweight and fast recurrence rules for PHP (RFC 5545)

PHP-Parser

Sugar utilizes a PHP library called PHP-Parser Its purpose is to simplify static code analysis and manipulation.

There are major internal changes in this library, if you use them, please refer to this library’s upgrade procedure here.

nikic/php-parser → ^v5.4.0

JS Library Upgrades

Low to Minimum Impact Upgrade on various JS libraries

There are no known breaking changes associated with these updates.

@babel/core -> 7.27.4
@sugarcrm/ventana -> 1.1.19
handlebars -> 4.7.8-sugarcrm
babel-loader -> 9.2.1
bootstrap  -> 5.3.7
gulp -> 5.0.1
jquery-migrate -> 3.5.2
sinon -> 21.0.0
tailwindcss -> 3.4.17
underscore -> 1.13.7
webpack -> 5.99.9
eslint-plugin-import -> 2.31.0
cure53/DOMPurify -> 3.2.6
stylelint-config-standard -> 38.0.0

DOMPurify JS Library

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Note: This improvement has been backported to Sugar 25.1.x.

Configurability updates

Improved Control Over Field Updates by Process Definitions

$sugar_config['bpm_denylisted_fields'] = [
  'ModuleName1' => ['field_to_block_1', 'field_to_block_2'],
  'ModuleName2' => ['another_field_to_block'],
];

Note: When this sugar_config is set, only the specified fields will be blocked — regardless of their visibility in the user interface.

Sugar Config Settings

Setting Name	Default	Override Example	Description
bpm_denylisted_fields	[]	$sugar_config['bpm_denylisted_fields'] = [ 'ModuleName1' => ['field_to_block_1', 'field_to_block_2'], 'ModuleName2' => ['another_field_to_block']];	This new config will be used to include specific fields in the 'allowed fields to be modified by BPM'.
features.enableStrictContentSecurityPolicy	false	$sugar_config['features']['enableStrictContentSecurityPolicy'] = true;	If enabled, the application will enforce a strict Content Security Policy (CSP)

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

A new healthcheck bucket 'F' (manual customization) has been added to ensure compatibility to this version.

Removal of Unused Platform

As part of ongoing SugarCore cleanup efforts, the kiosk platform has been removed to streamline with our products and services.

Removing gulp-filter JS lib

Removing uglify-js and socket.io JS lib

Removed the legacy socket.io dependency from package.json as it was no longer used anywhere in the codebase. This also removed its transitive dependency uglify-js.

Data Changes

New Indexes for Calls and Meetings

idx_calls_series_event_deleted
- 'series_deleted', 'event_type', 'deleted
idx_calls_date_mod_rep_parent_id -
- 'date_modified', 'repeat_parent_id

Platform Updates

Scheduler Jobs Now Run on a Consistent Timezone

In this release, we've implemented a long-awaited enhancement that brings consistency to scheduler job execution times. Previously, job execution depended on the timezone of the scheduler's assigned user. As Sugar automatically updates user timezones—and admin users might share credentials across different locations—this led to jobs running at different times.

With this update, scheduler jobs now run based on a centralized (UTC), consistent timezone, eliminating timezone-related surprises and ensuring reliable, predictable behavior.

In the Scheduler UI, execution times are shown in your local timezone, so you always know exactly when it will trigger—no mental math required.
Existing schedulers remain unchanged, but we now clearly display their scheduled times based on your profile’s timezone.

Enhanced SystemProcessLock Handling to Prevent Redundant Execution During Admin QRR

Note: This improvement has been backported to Sugar 25.1.x.

Improved Deep Linking Support for SugarCRM on Mobile Devices

What's new:

Universal Link Support: SugarCRM mobile app now uses Universal Links (iOS) and App Links (Android) to seamlessly redirect users from supported emails/messages directly into the app—bypassing the mobile browser when possible.
Smart App Prompts: Users without the SugarCRM mobile app installed are now prompted to download it from the App Store or Google Play when tapping a SugarCRM link.
Improved Workflow Link Behavior: Links generated from workflows (e.g., SugarBPM) now attempt to open in the app rather than defaulting to the mobile browser.
Browser Consistency Fixes: Addressed inconsistent behavior across third-party browsers (e.g., Edge, Chrome) especially on iPhone, ensuring reliable app-switch prompts.

Enhanced Content Security Policy (CSP) for Improved Application Security

To support this enhancement, we’ve refactored the frontend code to:

Remove inline event handlers and javascript: URIs
Add nonce attributes to all <script> elements

These changes ensure that only trusted scripts are executed in the browser.

This feature is configurable via App.config ($sugar_config['features']['enableStrictContentSecurityPolicy']) and requires a QRR after being toggled.

The rollout will follow a phased approach, beginning in report-only mode to monitor violations, with full enforcement to follow in both core and customization layers in future releases.

Declarative Metadata Refactoring

Replace the TCPDF with SugarPdf in MapsGenerator

In this release, we've updated MapsGenerator.php::createPDF() to use SugarPDF instead of directly using TCPDF.

Added Backend Framework for Dropdown Classifications

Key details:

Classifications are defined using metadata and stored via the extension framework.
A classification includes:
- A unique identifier
- Translatable classification options (app_list_strings)
- Mappings between dropdown values and classification categories
No API or UI changes in this implementation — a helper class is provided to handle loading and saving classification data.
Designed to support future use with multiple classifications per dropdown.

Note: This implementation does not expand classifications to all dropdowns yet, sales_stage_dom only

Prevent Data Loss on Market MLP Uninstallation and upgrade

Note: If on upgrade customer does not have active market license then the features would not show up after upgrade even if they have MLP installed.

SugarLive compatibility with the V2 console for Amazon Connect

Bug Fixes

Fixed an issue with the FilterApi that was returning extra fields in the response payload even when filtering by using args fields.
Fixed QRR Occasionally Fails to Rebuild Module/Class Cache, Causing Outages and UI Errors caused by race conditions during concurrent or overlapping QRR executions or user requests during cache rebuild.
Fixed an issue for a specific scenario where user licenses were failing to update
Fixed an issue that a calculated field using the countConditional function in combination with a relate field (e.g. countConditional($notes,"name",createList("test"))) caused a “Too many tables” error when a large number of one-to-one relationships were created between modules
Fixed an issue on Uncaught TypeError: Sugarcrm\\Sugarcrm\\Security\\Escaper\\Escape::html() caught on upgrade from 14.0.1 to 25.1
Fixed an issue where Sugar Automate licenses and UI elements disappear after manual license validation and only reappear when an online validation is performed.
Fixed an issue with our silentUpgrader that, in some cases, the healthcheck was still executed during the upgrade even if the instance was configured with “Bypass Healthcheck” option enabled.
Fixed an issue where People names (Contacts, Leads, Users) currently do not have a display option for how names are traditionally written in Chinese. The LastFirst name format has been added to the default list to support proper name display across the product (e.g., Contacts list view, record view, Lead, and Assigned To fields)
Fixed an issue on the Case Summary Chart and Opportunity Metrics Chart (migrated from Sucrose to Chart.JS) where, if only one label was present, it displayed at the bottom of the chart in a space too small to display it properly
Fixed an issue where Users were receiving a permission error when trying to use Doc Merge for Quote records and have {currency_name.iso4217} in the template.
Fixed an issue where regular users triggered redundant rebuilds after admin QRR due to SystemProcessLock, causing server overload due to multiple expensive operations running simultaneously.
Fixed an issue where Generating a Quote from the Revenue Line Item detail view doesn't allow the generated Quote to be saved.
Fixed an issue where Update Momentum of In-Progress Smart Guides' scheduler fails on NULL score or point values.
Fixed an issue where a single email failure due to a Laminas error could halt the entire import scheduler, leaving the email unread and causing repeated failures.
Fixed an issue where Developer user encounters error when editing Timeline. Developer only users will not see this option but users with Admin and Developer access will.
Fixed an issue when a user has a profile date format that is not ISO compliant, the date outputted into a PDF is not valid in ISO format, Sugar was using current date but should interpret that date correctly.

Sugar Core Security Updates

Note: Some of those security improvements were backported to Sugar 25.1.x.

Healthcheck Updates

Built a health scanner tool to detect cloud instances using SugarMarket MLP versions < 2.2 and send it to bucket F
Built a healthcheck to detect and support the removal of the legacy include/modules_override.php file path and send it to bucket F

Tags: Sugar 25.2

Sugar 25.2 Customization Guide

Rafael Fernandes — Mon, 29 Sep 2025 13:40:36 GMT

Revision 2 posted to Dev Tutorials by Rafael Fernandes on 9/29/2025 1:40:36 PM

Please check out the Sugar 25.2 Developer Webinar recording for more developer highlights. For Admin and End User release notes, please visit the Sugar 25.2.0 Release Notes.

User Experience Updates

Modernized Dropdown Editor

What’s new:

Redesigned Interface: New Sidecar layout with updated header, inline editing, and consistent list view styling. Supports dark mode.
Formatting Flow Fix & Toggle Control: Chart colors no longer drive dropdown styling; instead, formatting is now defined at the dropdown level and pushed to charts for consistency..
- New "Enable formatting in dropdown" toggle added per dropdown.
- Toggle is enabled by default for: sales_stage_dom, quote_stage_dom, case_status_dom, and lead_status_dom.
- When disabled, formatting is hidden in the UI but preserved and still used in charts.
- When enabled, users can customize styles (colors, fonts) via the conditional formatting panel.
- Chart colors fallback to the chart palette for items without formatting; white and black are excluded and replaced.
Conditional Formatting: New Conditional Format Options control panel that allows users to customize the appearance of dropdown values using styles, icons, and colors.
- The following stock/out-of-the-box dropdowns were predefined with conditional formatting for awareness and usability: sales_stage_dom, quote_stage_dom, case_status_dom, lead_status_dom
- Formatting will be reflected as soon as saved on List View, Record View, Focus Drawer, Reports, Other components using the dropdown values, All views in sugar
- Even if user selects RGB, we only reflect Hex number in the input
Add New Rows: Easily add multiple items with editable fields for Display Label and Classification (for sales_stage_dom). Only completed rows are saved.
Improved Search: Real-time search across Item Name and Display Label fields with partial match support.
Restore to Default: Revert dropdowns to their original out-of-the-box (OOTB) state, including default sort order. Available only for OOTB lists.
Bulk Editing & Reduced Clicks: Edit multiple rows at once and save all changes in one action.
Sort by Display Label: New sort button allows ascending/descending sort; order persists across sessions and is saved.
Inline Editing & Deletion: Edit Display Label and Classification fields directly; delete items with confirmation.
Drag-and-Drop Reordering: Rearrange items via drag-and-drop. Changes are saved on click.
Unsaved Change Warning: Users are prompted before navigating away from unsaved edits.

Adding support to Shared Drive files on Google Drive

Enable Row-Level Actions in List View Dashlets

Opportunity Delta in List and Record Views

Key Features:

New Time-Based Comparison Dropdown with four options: None, Last 7 days, Last 14 days, Last 30 days.
Compares current opportunity data to its value at the end of the selected past day.
Highlights value changes in::
- Likely Amount
- Expected Close Date
- Sales Stage

Selection is sticky per view (e.g., list view and record view can maintain independent settings).
When navigating using the focus icon, the source view’s selection is respected and carried to the target dashlets.
If no prior context exists, the default selection is Last 7 days.

Add Transcription, Recording, and Summary fields on the Meetings module

We're improving Meetings module in this release by adding transcription, recording and summary fields to the record view in view/edit modes.

Dynamic Record View Dashlet Rendering for Flex Relate Fields in Focus Drawer

Sugar REST API updates

This Sugar release introduces REST v11_27.

Dropdown Editor

Set details of dropdown.

PUT <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Get details of dropdown that can be changed.

GET <sugar instance>/rest/v11_27/Administration/dropdownEditor/:dropdownName

Create Dropdown DOM issue as a php-file in customer storage directory.

POST <sugar instance>/rest/v11_27/Administration/dropdownEditor/create

Enhancements to Package Builder APIs’ error handling

We have improved our Package Builder API for clear and consistent error codes that are returned for known failure scenarios.

For Example: 200 OK, 201 Created, 400 Bad Request, 404 Not Found, 500 Internal Server Error.

Error messages include actionable context (e.g., missing fields, invalid formats, unsupported package types)

All existing error-prone areas are covered (e.g., input validation, external service failures, internal exceptions)

Fallbacks or default behaviors are implemented where appropriate

Errors follow our API error response standard (e.g., HTTP status codes, message structure)

The following endpoints were improved:

POST <sugar instance>/rest/v11_27/Administration/package/customizations

POST <sugar instance>/rest/v11_27/Administration/package

GET <sugar instance>/rest/v11_27/Administration/package/id

POST <sugar instance>/rest/v11_27/Administration/package/remote

POST <sugar instance>/rest/v11_27/Administration/package/data

POST <sugar instance>/rest/v11_27/Administration/package/getRemotePackages

Historical Deltas API

Retrieves historical delta changes for a module based on a timestamp and list of records.

POST <sugar instance>/rest/v11_27/historically/delta

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

aws/aws-sdk-php             3.342.19 AWS SDK for PHP - Use Amazon Web Services in your PHP project
doctrine/dbal               3.9.4    Powerful PHP database abstraction layer (DBAL) with many features for da...
egulias/email-validator     4.0.4    A library for validating emails against several RFCs
guzzlehttp/guzzle           7.9.3    Guzzle is a PHP HTTP client library
laminas/laminas-escaper     2.16.0   Securely and safely escape HTML, HTML attributes, JavaScript, CSS, and URLs
league/oauth2-client        2.8.1    OAuth 2.0 Client Library
microsoft/microsoft-graph   2.29.0   The Microsoft Graph SDK for PHP
rector/rector               2.0.11   Instant Upgrade and Automated Refactoring of any PHP code
rlanvin/php-rrule           2.5.2    Lightweight and fast recurrence rules for PHP (RFC 5545)

PHP-Parser

Sugar utilizes a PHP library called PHP-Parser Its purpose is to simplify static code analysis and manipulation.

There are major internal changes in this library, if you use them, please refer to this library’s upgrade procedure here.

nikic/php-parser → ^v5.4.0

JS Library Upgrades

Low to Minimum Impact Upgrade on various JS libraries

There are no known breaking changes associated with these updates.

@babel/core -> 7.27.4
@sugarcrm/ventana -> 1.1.19
handlebars -> 4.7.8-sugarcrm
babel-loader -> 9.2.1
bootstrap  -> 5.3.7
gulp -> 5.0.1
jquery-migrate -> 3.5.2
sinon -> 21.0.0
tailwindcss -> 3.4.17
underscore -> 1.13.7
webpack -> 5.99.9
eslint-plugin-import -> 2.31.0
cure53/DOMPurify -> 3.2.6
stylelint-config-standard -> 38.0.0

DOMPurify JS Library

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Note: This improvement has been backported to Sugar 25.1.x.

Configurability updates

Improved Control Over Field Updates by Process Definitions

$sugar_config['bpm_denylisted_fields'] = [
  'ModuleName1' => ['field_to_block_1', 'field_to_block_2'],
  'ModuleName2' => ['another_field_to_block'],
];

Note: When this sugar_config is set, only the specified fields will be blocked — regardless of their visibility in the user interface.

Sugar Config Settings

Setting Name	Default	Override Example	Description
bpm_denylisted_fields	[]	$sugar_config['bpm_denylisted_fields'] = [ 'ModuleName1' => ['field_to_block_1', 'field_to_block_2'], 'ModuleName2' => ['another_field_to_block']];	This new config will be used to include specific fields in the 'allowed fields to be modified by BPM'.
features.enableStrictContentSecurityPolicy	false	$sugar_config['features']['enableStrictContentSecurityPolicy'] = true;	If enabled, the application will enforce a strict Content Security Policy (CSP)

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

A new healthcheck bucket 'F' (manual customization) has been added to ensure compatibility to this version.

Removal of Unused Platform

As part of ongoing SugarCore cleanup efforts, the kiosk platform has been removed to streamline with our products and services.

Removing gulp-filter JS lib

Removing uglify-js and socket.io JS lib

Removed the legacy socket.io dependency from package.json as it was no longer used anywhere in the codebase. This also removed its transitive dependency uglify-js.

Data Changes

New Indexes for Calls and Meetings

idx_calls_series_event_deleted
- 'series_deleted', 'event_type', 'deleted
idx_calls_date_mod_rep_parent_id -
- 'date_modified', 'repeat_parent_id

Platform Updates

Scheduler Jobs Now Run on a Consistent Timezone

With this update, scheduler jobs now run based on a centralized (UTC), consistent timezone, eliminating timezone-related surprises and ensuring reliable, predictable behavior.

In the Scheduler UI, execution times are shown in your local timezone, so you always know exactly when it will trigger—no mental math required.
Existing schedulers remain unchanged, but we now clearly display their scheduled times based on your profile’s timezone.

Enhanced SystemProcessLock Handling to Prevent Redundant Execution During Admin QRR

Note: This improvement has been backported to Sugar 25.1.x.

Improved Deep Linking Support for SugarCRM on Mobile Devices

What's new:

Universal Link Support: SugarCRM mobile app now uses Universal Links (iOS) and App Links (Android) to seamlessly redirect users from supported emails/messages directly into the app—bypassing the mobile browser when possible.
Smart App Prompts: Users without the SugarCRM mobile app installed are now prompted to download it from the App Store or Google Play when tapping a SugarCRM link.
Improved Workflow Link Behavior: Links generated from workflows (e.g., SugarBPM) now attempt to open in the app rather than defaulting to the mobile browser.
Browser Consistency Fixes: Addressed inconsistent behavior across third-party browsers (e.g., Edge, Chrome) especially on iPhone, ensuring reliable app-switch prompts.

Enhanced Content Security Policy (CSP) for Improved Application Security

To support this enhancement, we’ve refactored the frontend code to:

Remove inline event handlers and javascript: URIs
Add nonce attributes to all <script> elements

These changes ensure that only trusted scripts are executed in the browser.

This feature is configurable via App.config ($sugar_config['features']['enableStrictContentSecurityPolicy']) and requires a QRR after being toggled.

The rollout will follow a phased approach, beginning in report-only mode to monitor violations, with full enforcement to follow in both core and customization layers in future releases.

Declarative Metadata Refactoring

Replace the TCPDF with SugarPdf in MapsGenerator

In this release, we've updated MapsGenerator.php::createPDF() to use SugarPDF instead of directly using TCPDF.

Added Backend Framework for Dropdown Classifications

Key details:

Classifications are defined using metadata and stored via the extension framework.
A classification includes:
- A unique identifier
- Translatable classification options (app_list_strings)
- Mappings between dropdown values and classification categories
No API or UI changes in this implementation — a helper class is provided to handle loading and saving classification data.
Designed to support future use with multiple classifications per dropdown.

Note: This implementation does not expand classifications to all dropdowns yet, sales_stage_dom only

Prevent Data Loss on Market MLP Uninstallation and upgrade

Note: If on upgrade customer does not have active market license then the features would not show up after upgrade even if they have MLP installed.

SugarLive compatibility with the V2 console for Amazon Connect

Bug Fixes

Fixed an issue with the FilterApi that was returning extra fields in the response payload even when filtering by using args fields.
Fixed QRR Occasionally Fails to Rebuild Module/Class Cache, Causing Outages and UI Errors caused by race conditions during concurrent or overlapping QRR executions or user requests during cache rebuild.
Fixed an issue for a specific scenario where user licenses were failing to update
Fixed an issue that a calculated field using the countConditional function in combination with a relate field (e.g. countConditional($notes,"name",createList("test"))) caused a “Too many tables” error when a large number of one-to-one relationships were created between modules
Fixed an issue on Uncaught TypeError: Sugarcrm\\Sugarcrm\\Security\\Escaper\\Escape::html() caught on upgrade from 14.0.1 to 25.1
Fixed an issue where Sugar Automate licenses and UI elements disappear after manual license validation and only reappear when an online validation is performed.
Fixed an issue with our silentUpgrader that, in some cases, the healthcheck was still executed during the upgrade even if the instance was configured with “Bypass Healthcheck” option enabled.
Fixed an issue where People names (Contacts, Leads, Users) currently do not have a display option for how names are traditionally written in Chinese. The LastFirst name format has been added to the default list to support proper name display across the product (e.g., Contacts list view, record view, Lead, and Assigned To fields)
Fixed an issue on the Case Summary Chart and Opportunity Metrics Chart (migrated from Sucrose to Chart.JS) where, if only one label was present, it displayed at the bottom of the chart in a space too small to display it properly
Fixed an issue where Users were receiving a permission error when trying to use Doc Merge for Quote records and have {currency_name.iso4217} in the template.
Fixed an issue where regular users triggered redundant rebuilds after admin QRR due to SystemProcessLock, causing server overload due to multiple expensive operations running simultaneously.
Fixed an issue where Generating a Quote from the Revenue Line Item detail view doesn't allow the generated Quote to be saved.
Fixed an issue where Update Momentum of In-Progress Smart Guides' scheduler fails on NULL score or point values.
Fixed an issue where a single email failure due to a Laminas error could halt the entire import scheduler, leaving the email unread and causing repeated failures.
Fixed an issue where Developer user encounters error when editing Timeline. Developer only users will not see this option but users with Admin and Developer access will.
Fixed an issue when a user has a profile date format that is not ISO compliant, the date outputted into a PDF is not valid in ISO format, Sugar was using current date but should interpret that date correctly.

Sugar Core Security Updates

Note: Some of those security improvements were backported to Sugar 25.1.x.

Healthcheck Updates

Built a health scanner tool to detect cloud instances using SugarMarket MLP versions < 2.2 and send it to bucket F
Built a healthcheck to detect and support the removal of the legacy include/modules_override.php file path and send it to bucket F

Tags: Sugar 25.2

PHP 7.4 Warnings to PHP8.x Errors

Rafael Fernandes — Wed, 10 Sep 2025 18:25:36 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:25:36 PM

PHP Warnings to Runtime Errors

In the transition from PHP 7.4 to PHP 8.x, notable changes have occurred with certain runtime errors that were previously treated as warnings by PHP. As of PHP 8.x, these errors have been elevated to runtime errors.

Automated tools like Rector can do a lot when it comes to lexical scanning but runtime (non-lexical and more closely tied to the logic and data aspects of code execution) its help is limited.

Defensive coding techniques serve as a robust shield against runtime errors, empowering you to anticipate and prevent such issues.

In our research, we've identified several of these techniques designed to assist you in addressing and rectifying potential errors.

Importance of Sugar logs

Logs are crucial to help you understand the services and customizations you develop and operate. Not only can logs help you troubleshoot problems, but they can also help you understand your customizations better, and sometimes provide you with unforeseen logic errors that your code might not expect. Even after applying defensive coding, you may end up with errors in your logs that will not propagate to the requestor, that being a UI trigger or a cron job, so it is important to keep an eye on your logs.

Some Sugar errors will not be noticeable by users but they'll be logged in the sugarcrm.log. It is your responsibility as Sugar instance's administrator to check the logs, understand the causes, and possibly provide fixes.

Enable PHP logs

The starting point to identify such errors is to enable PHP logs. This foundational step will provide the necessary data (warnings/errors) so you can implement effective defensive coding to prevent them from happening.

Enable E_WARNING and E_DEPRECATION Log in to the PHP error log and test your code.

Locate your php.ini file. The location can vary based on your operating system and PHP installation. Common paths include:
- Windows: C:\Program Files\PHP\php.ini
- Linux: /etc/php/{version}/apache2/php.ini
Open the php.ini file in a text editor with administrative privileges.
Search for the error_reporting directive.
Update the directive to include E_WARNING and E_DEPRECATED:

error_reporting = E_ALL & ~E_NOTICE | E_WARNING | E_DEPRECATED

Understanding Rector's Limitations

While Rector serves as a valuable tool for scanning code and conducting lexical analysis, it's important to note its limitations regarding Sugar expressions used in calculated fields, SugarBPM, and similar contexts.

During runtime, Sugar evaluates expressions using various methods, including PHP evaluation. This introduces the possibility of encountering exceptions similar to those in native PHP code. Therefore, developers must review their expressions to ensure they are "code safe" for Sugar interpreter, for example, by checking if a variable is not empty before applying a function to it.

Exceptions occurring during expression evaluation are logged in the sugarcrm.log file. This log serves as a valuable resource for developers, facilitating the analysis and resolution of runtime issues within Sugar.

Applying defensive code to avoid Runtime Errors

PHP Warning: count(): Parameter must be an array or an object that implements Countable in *

safeCount will take care of it
For Sugar, the best practice is to use safeCount() instead of count()!

PHP Warning: A non-numeric value encountered*

Occurs when invalid strings are coerced using operators expecting numbers (+ - * / ** % << >> | & ^) or their assignment equivalents.
Cast the values to int or float before the arithmetic operation.
Check the values for is_numeric($value) and skip the calculation if the values are not numeric.

PHP Warning: sizeof(): Parameter must be an array or an object that implements Countable in*

if you have code like $a = sizeof($b) + 1;
replace sizeof with safeCount

PHP Warning: strlen() expects parameter 1 to be string, array given in*

Add defensive for example:

if (is_string($some_value)) {
  $len = strlen($some_value);
} else { 
  // throw error or deal with your data
}

PHP Warning: array_key_exists(): The first argument should be either a string or an integer in*

Add defensive for example:

if ((is_string($haystack) || is_numeric($haystack)) && array_key_exists($haystack, $myArray)) {
    // continue with your logic  
} else { 
    // throw error or deal with your data;
}

PHP Warning: strpos(): Empty needle in*

Add defensive code, for example:

if (isset($haystack) && !empty($haystack) && isset($needle) && !empty($needle) && strpos($haystack, $needle, $offset)) {
   // continue with your logic
} else { 
   // throw error or deal with your data;
}

PHP Warning: array_intersect(): Expected parameter 1 to be an array, null given in*

Add defensive for example:

if (is_array($array) && is_array($arrays)) {
   $intersect = array_intersect($array, $arrays);
} else { 
   // throw error or deal with your data;
}

PHP Warning: Creating default object from empty value*

Add defensive for example:

// Option 1: Skip execution branch if the value is not an object
$a = BeanFactory::newBean('someweirdstuff');
if (!($a instanceof SugarBean)) {
  return;
}
$a->b = 'c';

// Option 2: In cases when the variable is used without being initialized - initialize it first
$a = new stdClass();
$a-> b = ‘c’;

PHP Warning: DateTime::diff() expects parameter 1 to be DateTimeInterface, null given*

PHP Warning: DateTime::setTimezone() expects parameter 1 to be DateTimeZone, string given

Add defensive for example:

$date = new \DateTime();
if ($otherDate instanceof \DateTimeInterface) {
  $diff = $date->diff($otherDate);
}

PHP Warning: Division by zero

Add defensive for example:

if ($rate != 0) {
  $result = $amount / $rate;
}

PHP Warning: Illegal offset type in isset or empty; PHP Warning: Illegal offset type

Array keys can only be int or string. Float, boolean and null get converted transparently (though it may be signal that something went wrong), but arrays, objects and resources don’t.
The solution is also defensive coding::

if (is_string($key) || is_int($key)) {
  $map[$key] = $value;
}

PHP Warning: Illegal string offset

Array keys can only be int or string. Float, boolean and null get converted transparently (though it may be signal that something went wrong), but arrays, objects and resources don’t.
The solution is also defensive coding::

$a = ‘some_string’;
if (is_array($a)) {
  var_dump($a[‘key’]);
}

PHP Warning: Use of undefined constant SOME_NAME - assumed 'SOME_NAME'

This may have multiple causes, the most common is string literal, not wrapped in quotes.
The solution is to wrap these to quotes:

$status = $row['status'];
$duration = $n . 'hours';

PHP Warning: fclose() expects parameter 1 to be resource, bool given

The solution is defensive coding, but in case of resources it should be applied as close as possible to the place of its initialization

$file = fopen($name, 'r');
if ($file === false) {
    // handle error, interrupt execution - whatever appropriate
}
// do something
fclose($file);

PHP Warning: call_user_func() expects parameter 1 to be a valid callback, function 'my_func_name' not found or invalid function name

The solution is also defensive coding:

if (is_callable('my_func_name')) {
    call_user_func('my_func_name');
} else {
    // handle error
}

PHP Warning: implode(): Invalid arguments passed

Happens when the second argument is not array:
The solution is also defensive coding:

if (is_array($names)) {
    var_dump(implode(', ', $names));
}

// or

$pieces = is_array($names) ? $names : [];
var_dump(implode(', ', $pieces));

PHP Warning: max(): Array must contain at least one element

The solution is also defensive coding:

if (safeCount($items) > 0) {
    $best = max($items);
} else {
    // handle error, assign some defaults, etc.
}

PHP Warning: Attempt to assign property 'team_id' of non-object

Defensive coding - check if the object is really an instance of the class you assuming. Makes sense to perform this check as close to object initialization as possible (or at the beginning of the function if the object is passed as an argument)

if (!($a instanceof SomeClass)) {
    // handle error, interrupt execution, etc.
}
$a->b = 1;

PHP Warning: array_multisort(): Array sizes are inconsistent*

PHP Warning: array_combine(): Both parameters should have an equal number of elements

These warnings have similar cause and solution. Make sure, that sorted arrays are of the same size

if (safeCount($apples) !== safeCount($oranges)) {
    // handle error
}
array_multisort($apples, $oranges);

PHP Warning: array_multisort(): Argument #1 is expected to be an array or a sort flag

Defensive coding. Assuming here that sorting flags and order are hardcoded, otherwise, check them with is_integer

if (!is_array($apples) || !is_array($oranges)) {
    // handle error
}
array_multisort($apples, SORT_ASC, SORT_STRING, $oranges, SORT_ASC, SORT_STRING);

PHP Warning: sprintf(): Too few arguments

Carefully check that number of arguments to sprintf corresponds to number of placeholders in format string

echo sprintf('%s is the capital of %s', 'London'); // error - 2 placeholders but 1 argument

Executing Rector

Rafael Fernandes — Wed, 10 Sep 2025 18:23:34 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:23:34 PM

Now that you have your Rector properly configured with your customization, either via MLP or custom code you can continue with a dry-run or run rector automatically.

Dry-run Rector

Dry-run gives you the opportunity to see what Rector has found and will execute/change before it actually does it on your behalf.

it's time to dry-run rector by executing the following command.

/path/to/RECTOR/vendor/rector/rector/bin/rector/bin/rector process --clear-cache --dry-run > php83.diff

Dry run produces a very detailed output file (if you spooled it off to a file) containing the diff and the list of rector rules that were applied to make your code compatible with PHP 8.3 (which we configured it to)

1 file with changes
===================

1) custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php:0

    ---------- begin diff ----------
@@ @@
 <?php 
  //WARNING: The contents of this file are auto-generated
- $this->ss->assign("current_users", count($active_users));
- $this->ss->assign("user_count_param", "user_count: '".count($active_users)."'");
+ $this->ss->assign("current_users", is_countable($active_users) ? count($active_users) : 0);
+ $this->ss->assign("user_count_param", "user_count: '".(is_countable($active_users) ? count($active_users) : 0)."'");
  
 ?>
    ----------- end diff -----------

Applied rules:
 * AddDefaultValueForUndefinedVariableRector (https://github.com/vimeo/psalm/blob/29b70442b11e3e66113935a2ee22e165a70c74a4/docs/fixing_code.md#possiblyundefinedvariable)
 * CountOnNullRector (https://3v4l.org/Bndc9)

 [OK] 1 file would have changed (dry-run) by Rector

Execute Rector

If your dry-run is clear or you are ready to let Rector auto-update your code, now it's time to get a second git commit to "clear" the system so we know exactly what rector has done to our system.

Prepare Git

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   config_override.php
        modified:   custom/application/Ext/Include/modules.ext.php

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php
        custom/Extension/application/Ext/Include/orderMapping.php
        custom/clients/
        custom/modules/ActivityStream/
        custom/modules/Forecasts/Ext/clients/
        custom/modules/pmse_Project/

no changes added to commit (use "git add" and/or "git commit -a")

Commit

sh-3.2$ git add . && git commit -am "Before Rector"
[master 33a18416] Before Rector
 422 files changed, 96500 insertions(+)

Execute

Run the rector process once again, but without --dry-run and --clear-cache options as the cache is up to date (the process should look like this):

➜  sugar git:(master) /path/to/RECTOR/vendor/rector/rector/bin/rector/bin/rector process                                           
 10/30 [▓▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░░░]  33%

* This may take time, depending on the complexity of the code. In some cases, this can take more than an hour.

After Execution (Git diff)

Once finished, Rector will provide a similar report to the dry-run, but now those files have actually been modified in the filesystem.

By executing git status you should see all the changes ready to work on PHP 8.3 (or depending on the config you specified)

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php

no changes added to commit (use "git add" and/or "git commit -a")

Congratulations, you now have your code compatible with PHP 8.3.

You can now commit your new code as follows:

sh-3.2$ git add . && git commit -am "PHP 8.3 upgrade refactor"
[master 7ad3bf22] PHP 8.3 upgrade refactor
 1 files changed, 1 insertions(+), 1 deletions(-)

You can move on to the Keeping Compatibility Phase:

Keeping Compatibility

Prepare Rector for Customizations

Rafael Fernandes — Wed, 10 Sep 2025 18:21:05 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:21:05 PM

If you are looking to make your customizations, not packaged in an MLP, compatible with different versions of PHP, this guide is for you.

You will take your customization code and add to the Sugar instance where Rector is and git has been initialized.

You need to have a inventory of your assets to create your git/rector config.

Prerequisites:

Basic Setup
Customization Assets Inventory (file path of your assets)
A vanilla instance if you don't have an inventory

Create your Customization Inventory

If you already have your customization inventory, great! you can skip this section.

There are a few different ways of achieving the same result, we are going to use a vanilla instance as our basis for git comparison, and your current "deployed" instance with your code installed in the filesystem.

In your vanilla instance, you will follow the steps from our Basic Setup and have git init and commit.

Once you have that in place, (git status should return empty results), you are good to go on copying all the files from your deployed instance to the vanilla one.

sh-3.2$ cp -rf /path/to/current/sugar/* /path/to/vanila/sugar/

* it is important to have the exact same version of Sugar, otherwise, you'll have "noise" in the vendors folder and other files that aren't necessarily your custom code but Sugar release-related files and those can be ignored if found.

After it has been copied over, execute git status commands to get your customization inventory:

sh-3.2$ git status
On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        modules/FD_SignupFraudDetection/
        modules/FD_TransactionFraudDetect/

nothing added to commit but untracked files present (use "git add" to track)

Prepare your Rector config

Copy the paths, and paste them into the rector.php config file that was generated in the previous step, replacing the default paths in $rectorConfig->paths([ array like this (you can ignore some of the files, like *ext.php and *orderMapping.php):

    $rectorConfig->paths([
        '/path/to/sugar/modules/FD_SignupFraudDetection/',
        '/path/to/sugar/modules/FD_TransactionFraudDetect/',
    ]);

Note: Rector will generate a sample code with __DIR__, that, however, translates to "current folder" which can be different than your Sugar install. As a rule of thumb, always use fully qualified names without the __DIR__.

Modify the rector.php config file to upgrade the code to the newest supported PHP version (in our case, 8.3):

Specify PHP 8.3 as your phpVersion:

$rectorConfig->phpVersion(PhpVersion::PHP_83);

If you'd like to have only the incompatible rules between PHP 7.4 to PHP 8.3, you can use the following:

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);

Add safeCount rule to your config if you are in a supported Sugar version

<?php
...
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
...
return static function (RectorConfig $rectorConfig): void {
...
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
...

Full config file example (incompatibilities only)

By following those steps, you should have a rector.php similar to this to run incompatible rules between PHP 7.4 to PHP 8.3:

<?php
declare(strict_types=1);

use Rector\CodingStyle\Rector\FuncCall\ConsistentImplodeRector;
use Rector\Php72\Rector\Assign\ListEachRector;
use Rector\Php72\Rector\Assign\ReplaceEachAssignmentWithKeyCurrentRector;
use Rector\Php72\Rector\FuncCall\GetClassOnNullRector;
use Rector\Php72\Rector\FuncCall\ParseStrWithResultArgumentRector;
use Rector\Php72\Rector\FuncCall\StringifyDefineRector;
use Rector\Php72\Rector\While_\WhileEachToForeachRector;
use Rector\Php73\Rector\FuncCall\StringifyStrNeedlesRector;
use Rector\Php74\Rector\Double\RealToFloatTypeCastRector;
use Rector\Php74\Rector\FuncCall\ArrayKeyExistsOnPropertyRector;
use Rector\Php74\Rector\FuncCall\FilterVarToAddSlashesRector;
use Rector\Php74\Rector\FuncCall\MbStrrposEncodingArgumentPositionRector;
use Rector\Php74\Rector\FuncCall\MoneyFormatToNumberFormatRector;
use Rector\Php74\Rector\Property\RestoreDefaultNullToNullableTypePropertyRector;
use Rector\Php74\Rector\StaticCall\ExportToReflectionFunctionRector;
use Rector\Php80\Rector\ClassMethod\AddParamBasedOnParentClassMethodRector;
use Rector\Php80\Rector\ClassMethod\SetStateToStaticRector;
use Rector\Config\RectorConfig;
use Rector\ValueObject\PhpVersion;
use Rector\Php74\Rector\ArrayDimFetch\CurlyToSquareBracketArrayStringRector;
use Rector\Caching\ValueObject\Storage\MemoryCacheStorage;
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
use Rector\Php70\Rector\StaticCall\StaticCallOnNonStaticToInstanceCallRector;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->paths([
        '/path/to/sugar/modules/FD_SignupFraudDetection/',
        '/path/to/sugar/modules/FD_TransactionFraudDetect/',
    ]);

    $rectorConfig->cacheClass(MemoryCacheStorage::class);
    $rectorConfig->disableParallel();
    $rectorConfig->phpVersion(PhpVersion::PHP_83);

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
};

You can move on to the Execution Phase:

Execute Rector

Prepare Rector for MLP/Addon

Rafael Fernandes — Wed, 10 Sep 2025 18:20:03 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:20:03 PM

If you are looking to make your Module Loadable Package (MLP), a.k.a Addon, compatible with different versions of PHP, this guide is for you.

You will install an MLP zip file into Sugar's instance where Rector is and git has been initialized, by doing that, Sugar will add the MLP in the filesystem and git will let us know what has changed.

Prerequisites:

Basic Setup
A module loadable package (zip file)

Upload and Install your MLP

Upload and install your MLP as you normally would through Sugar's UI or API. Sugar will copy your files per manifest definition and perform the database operations as well (which are irrelevant for Rector).

After it has been installed, execute git status commands to see which files were updated/added by Sugar:

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   config_override.php
        modified:   custom/application/Ext/Include/modules.ext.php

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        custom/Extension/application/Ext/Include/xxxx.php
        custom/Extension/application/Ext/Include/orderMapping.php
        custom/modules/ActivityStream/
        custom/modules/Forecasts/Ext/clients/
        custom/modules/pmse_Project/

no changes added to commit (use "git add" and/or "git commit -a")

Prepare your Rector config

Copy the fully qualified paths, and paste them into the rector.php config file that was generated in the previous step, replacing the default paths in $rectorConfig->paths([ array like this (you can ignore some of the files, like *ext.php and *orderMapping.php):

    $rectorConfig->paths([
        '/path/to/sugar/custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php',
        '/path/to/sugar/custom/clients/',
        '/path/to/sugar/custom/modules/ActivityStream/',
        '/path/to/sugar/custom/modules/Forecasts/Ext/clients/',
        '/path/to/sugar/custom/modules/pmse_Project/',
    ]);

Modify the rector.php config file to upgrade the code to the newest supported PHP version (in our case, 8.3):

Remove/Comment:

// register a single rule
$rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);

Specify PHP 8.3 as your phpVersion:

$rectorConfig->phpVersion(PhpVersion::PHP_83);

If you'd like to have only the incompatible rules between PHP 7.4 to PHP 8.3, you can use the following:

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);

Add safeCount rule to your config if you are in a supported Sugar version

<?php
...
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
...
return static function (RectorConfig $rectorConfig): void {
...
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
...

Full config file example (incompatibilities only)

By following those steps, you should have a rector.php similar to this to run incompatible rules between PHP 7.4 to PHP 8.3:

<?php
declare(strict_types=1);

use Rector\CodingStyle\Rector\FuncCall\ConsistentImplodeRector;
use Rector\Php72\Rector\Assign\ListEachRector;
use Rector\Php72\Rector\Assign\ReplaceEachAssignmentWithKeyCurrentRector;
use Rector\Php72\Rector\FuncCall\GetClassOnNullRector;
use Rector\Php72\Rector\FuncCall\ParseStrWithResultArgumentRector;
use Rector\Php72\Rector\FuncCall\StringifyDefineRector;
use Rector\Php72\Rector\While_\WhileEachToForeachRector;
use Rector\Php73\Rector\FuncCall\StringifyStrNeedlesRector;
use Rector\Php74\Rector\Double\RealToFloatTypeCastRector;
use Rector\Php74\Rector\FuncCall\ArrayKeyExistsOnPropertyRector;
use Rector\Php74\Rector\FuncCall\FilterVarToAddSlashesRector;
use Rector\Php74\Rector\FuncCall\MbStrrposEncodingArgumentPositionRector;
use Rector\Php74\Rector\FuncCall\MoneyFormatToNumberFormatRector;
use Rector\Php74\Rector\Property\RestoreDefaultNullToNullableTypePropertyRector;
use Rector\Php74\Rector\StaticCall\ExportToReflectionFunctionRector;
use Rector\Php80\Rector\ClassMethod\AddParamBasedOnParentClassMethodRector;
use Rector\Php80\Rector\ClassMethod\SetStateToStaticRector;
use Rector\Config\RectorConfig;
use Rector\ValueObject\PhpVersion;
use Rector\Php74\Rector\ArrayDimFetch\CurlyToSquareBracketArrayStringRector;
use Rector\Caching\ValueObject\Storage\MemoryCacheStorage;
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
use Rector\Php70\Rector\StaticCall\StaticCallOnNonStaticToInstanceCallRector;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->cacheClass(MemoryCacheStorage::class);
    $rectorConfig->disableParallel();
    $rectorConfig->phpVersion(PhpVersion::PHP_83);

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
};

You can move on to the Execution Phase:

Execute Rector

Prepare Rector for MLP/Addon

Rafael Fernandes — Wed, 10 Sep 2025 18:16:46 GMT

Revision 20 posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:16:46 PM

If you are looking to make your Module Loadable Package (MLP), a.k.a Addon, compatible with different versions of PHP, this guide is for you.

You will install an MLP zip file into Sugar's instance where Rector is and git has been initialized, by doing that, Sugar will add the MLP in the filesystem and git will let us know what has changed.

Prerequisites:

Basic Setup
A module loadable package (zip file)

Upload and Install your MLP

After it has been installed, execute git status commands to see which files were updated/added by Sugar:

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   config_override.php
        modified:   custom/application/Ext/Include/modules.ext.php

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        custom/Extension/application/Ext/Include/xxxx.php
        custom/Extension/application/Ext/Include/orderMapping.php
        custom/modules/ActivityStream/
        custom/modules/Forecasts/Ext/clients/
        custom/modules/pmse_Project/

no changes added to commit (use "git add" and/or "git commit -a")

Prepare your Rector config

    $rectorConfig->paths([
        '/path/to/sugar/custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php',
        '/path/to/sugar/custom/clients/',
        '/path/to/sugar/custom/modules/ActivityStream/',
        '/path/to/sugar/custom/modules/Forecasts/Ext/clients/',
        '/path/to/sugar/custom/modules/pmse_Project/',
    ]);

Modify the rector.php config file to upgrade the code to the newest supported PHP version (in our case, 8.3):

Remove/Comment:

// register a single rule
$rectorConfig->rule(InlineConstructorDefaultToPropertyRector::class);

Specify PHP 8.3 as your phpVersion:

$rectorConfig->phpVersion(PhpVersion::PHP_83);

If you'd like to have only the incompatible rules between PHP 7.4 to PHP 8.3, you can use the following:

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);

Add safeCount rule to your config if you are in a supported Sugar version

<?php
...
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
...
return static function (RectorConfig $rectorConfig): void {
...
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
...

Full config file example (incompatibilities only)

By following those steps, you should have a rector.php similar to this to run incompatible rules between PHP 7.4 to PHP 8.3:

<?php
declare(strict_types=1);

use Rector\CodingStyle\Rector\FuncCall\ConsistentImplodeRector;
use Rector\Php72\Rector\Assign\ListEachRector;
use Rector\Php72\Rector\Assign\ReplaceEachAssignmentWithKeyCurrentRector;
use Rector\Php72\Rector\FuncCall\GetClassOnNullRector;
use Rector\Php72\Rector\FuncCall\ParseStrWithResultArgumentRector;
use Rector\Php72\Rector\FuncCall\StringifyDefineRector;
use Rector\Php72\Rector\While_\WhileEachToForeachRector;
use Rector\Php73\Rector\FuncCall\StringifyStrNeedlesRector;
use Rector\Php74\Rector\Double\RealToFloatTypeCastRector;
use Rector\Php74\Rector\FuncCall\ArrayKeyExistsOnPropertyRector;
use Rector\Php74\Rector\FuncCall\FilterVarToAddSlashesRector;
use Rector\Php74\Rector\FuncCall\MbStrrposEncodingArgumentPositionRector;
use Rector\Php74\Rector\FuncCall\MoneyFormatToNumberFormatRector;
use Rector\Php74\Rector\Property\RestoreDefaultNullToNullableTypePropertyRector;
use Rector\Php74\Rector\StaticCall\ExportToReflectionFunctionRector;
use Rector\Php80\Rector\ClassMethod\AddParamBasedOnParentClassMethodRector;
use Rector\Php80\Rector\ClassMethod\SetStateToStaticRector;
use Rector\Config\RectorConfig;
use Rector\ValueObject\PhpVersion;
use Rector\Php74\Rector\ArrayDimFetch\CurlyToSquareBracketArrayStringRector;
use Rector\Caching\ValueObject\Storage\MemoryCacheStorage;
use Rector\Renaming\Rector\FuncCall\RenameFunctionRector;
use Rector\Php70\Rector\StaticCall\StaticCallOnNonStaticToInstanceCallRector;

return static function (RectorConfig $rectorConfig): void {
    $rectorConfig->cacheClass(MemoryCacheStorage::class);
    $rectorConfig->disableParallel();
    $rectorConfig->phpVersion(PhpVersion::PHP_83);

    $rectorConfig->rules([
        AddParamBasedOnParentClassMethodRector::class,
        SetStateToStaticRector::class,
        ArrayKeyExistsOnPropertyRector::class,
        ExportToReflectionFunctionRector::class,
        FilterVarToAddSlashesRector::class,
        MbStrrposEncodingArgumentPositionRector::class,
        MoneyFormatToNumberFormatRector::class,
        RealToFloatTypeCastRector::class,
        RestoreDefaultNullToNullableTypePropertyRector::class,
        StringifyStrNeedlesRector::class,
        GetClassOnNullRector::class,
        ListEachRector::class,
        ReplaceEachAssignmentWithKeyCurrentRector::class,
        ParseStrWithResultArgumentRector::class,
        StringifyDefineRector::class,
        WhileEachToForeachRector::class,
        ConsistentImplodeRector::class,
        CurlyToSquareBracketArrayStringRector::class,
        StaticCallOnNonStaticToInstanceCallRector::class,
    ]);
    $rectorConfig->ruleWithConfiguration(RenameFunctionRector::class, [
        'count' => 'safeCount',
    ]);
};

You can move on to the Execution Phase:

Execute Rector

Rector Basic Setup

Rafael Fernandes — Wed, 10 Sep 2025 18:08:36 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:08:36 PM

Refactoring your code required a very basic setup to make your life easier to track what Rector does to your code (if you use its auto-fix mode).

Basic setup means installing software you will need such as Rector and Git. Git will help us to keep track of changes in your Sugar instance folder after we initialize it.

Keep that info in mind if you are planing to use a pre-existing instance for this work, it will add a lot of extra files to it.

Step by Step

Download a build of SugarCRM. Please use the one that is compatible with your MPL.
Install the build locally or use your own Sugar instance if you have one local
If you are using Sugar >= 25.1
- You must use Rector that is shipped with Sugar and located at vendor lib in your Sugar Instance folder. ex: /path/to/sugar/vendor/rector/rector/bin/rector
  - You might need to give +x permissions to execute rector.
    - chmod +x /path/to/sugar/vendor/rector/rector/bin/rector
  - You may still use newer Rector version for your convenience, just make sure you use composer in a different directory (see below) to avoid incompatibilities.

If you are using Sugar < 25

You should leverage composer to install rector and its dependencies.
It is important that you DO NOT install it in the Sugar's directory, if you do you will get errors due to libraries incompatibilities, see Troubleshooting Rector.
You can use the following commands to prepare rector to be used.

# install composer if you dont have it
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# create a temp rector folder
mkdir /tmp/rector
cd /tmp/rector

# let composer decide which version works on your system
composer require rector/rector --dev

# or specify a specific version (if you need to)
composer require rector/rector:^1.2.3 --dev

Initialize a git repository inside the instance folder: cd /path/to/sugar && git init. It’s just convenient to use git to track the list of files and some other things.
Create /path/to/sugar/.gitignore file to skip the unneeded changes with the following contents:

cache
vendor
portal2
upload
upgrades
*.log
rector.php

Commit the initial repository state

git add . && git commit -am 'init'

You might wanna keep your initial commit hash in case you need to reset

sh-3.2$ git log
commit 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f (HEAD -> main)
Author: Rafael Fernandes <rafael.fernandes@sugarcrm.com>
Date:   Mon Apr 17 10:40:56 2023 -0400

Initialize Rector config (rector.php)

If you are using rector 0.15.x or less, you can use the following:

rector-0.15.20/bin/rector init

If you are using newer versions of Rector, you can use:

/path/to/rector/bin/rector

 No "rector.php" config found. Should we generate it for you? [yes]:
 > yes

 [OK] The config is added now. Re-run command to make Rector do the work!

Agree to create a rector.php file with the dummy config. It should generate a template file similar to this:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
    ])
    // uncomment to reach your current PHP version
    // ->withPhpSets()
    ->withTypeCoverageLevel(0)
    ->withDeadCodeLevel(0)
    ->withCodeQualityLevel(0);

Reset your Repo to start over

You can always start over at your initial Git commit and undo all changes by Rector or yourself after that point.
Take the initial commit hash from git log and reset as follows:

sh-3.2$ git log
commit 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f (HEAD -> main)
Author: Rafael Fernandes <rafael.fernandes@sugarcrm.com>
Date:   Mon Apr 17 10:40:56 2023 -0400

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   vCard.php

no changes added to commit (use "git add" and/or "git commit -a")

sh-3.2$ git reset --hard 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f
HEAD is now at 0ac2bd9c init

sh-3.2$ git clean -fd
Removing custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php
Removing custom/Extension/application/Ext/Include/orderMapping.php
Removing custom/modules/ActivityStream/
Removing custom/modules/Forecasts/Ext/clients/
Removing custom/modules/pmse_Project/

sh-3.2$ git status
On branch main
nothing to commit, working tree clean

You can move on to the Prepare Phase:

Rector Basic Setup

Rafael Fernandes — Wed, 10 Sep 2025 18:06:28 GMT

Revision 21 posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 6:06:28 PM

Refactoring your code required a very basic setup to make your life easier to track what Rector does to your code (if you use its auto-fix mode).

Basic setup means installing software you will need such as Rector and Git. Git will help us to keep track of changes in your Sugar instance folder after we initialize it.

Keep that info in mind if you are planing to use a pre-existing instance for this work, it will add a lot of extra files to it.

Step by Step

Download a build of SugarCRM. Please use the one that is compatible with your MPL.
Install the build locally or use your own Sugar instance if you have one local
If you are using Sugar >= 25.1
- You must use Rector that is shipped with Sugar and located at vendor lib in your Sugar Instance folder. ex: /path/to/sugar/vendor/rector/rector/bin/rector
  - You might need to give +x permissions to execute rector.
    - chmod +x /path/to/sugar/vendor/rector/rector/bin/rector
  - You may still download newer versions of Rector from its release repository, however, you'd need to follow their installation instructions

If you are using Sugar < 25

You should leverage composer to install rector and its dependencies.
It is important that you DO NOT install it in the Sugar's directory, if you do you will get errors due to libraries incompatibilities, see Troubleshooting Rector.
You can use the following commands to prepare rector to be used.

# install composer if you dont have it
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer

# create a temp rector folder
mkdir /tmp/rector
cd /tmp/rector

# let composer decide which version works on your system
composer require rector/rector --dev

# or specify a specific version (if you need to)
composer require rector/rector:^1.2.3 --dev

Initialize a git repository inside the instance folder: cd /path/to/sugar && git init. It’s just convenient to use git to track the list of files and some other things.
Create /path/to/sugar/.gitignore file to skip the unneeded changes with the following contents:

cache
vendor
portal2
upload
upgrades
*.log
rector.php

Commit the initial repository state

git add . && git commit -am 'init'

You might wanna keep your initial commit hash in case you need to reset

sh-3.2$ git log
commit 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f (HEAD -> main)
Author: Rafael Fernandes <rafael.fernandes@sugarcrm.com>
Date:   Mon Apr 17 10:40:56 2023 -0400

Initialize Rector config (rector.php)

If you are using rector 0.15.x or less, you can use the following:

rector-0.15.20/bin/rector init

If you are using newer versions of Rector, you can use:

/path/to/rector/bin/rector

 No "rector.php" config found. Should we generate it for you? [yes]:
 > yes


 [OK] The config is added now. Re-run command to make Rector do the work!

Agree to create a rector.php file with the dummy config. It should generate a template file similar to this:

<?php

declare(strict_types=1);

use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths([
        __DIR__ . '/src',
    ])
    // uncomment to reach your current PHP version
    // ->withPhpSets()
    ->withTypeCoverageLevel(0)
    ->withDeadCodeLevel(0)
    ->withCodeQualityLevel(0);

Reset your Repo to start over

You can always start over at your initial Git commit and undo all changes by Rector or yourself after that point.
Take the initial commit hash from git log and reset as follows:

sh-3.2$ git log
commit 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f (HEAD -> main)
Author: Rafael Fernandes <rafael.fernandes@sugarcrm.com>
Date:   Mon Apr 17 10:40:56 2023 -0400

sh-3.2$ git status
On branch main
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        modified:   vCard.php

no changes added to commit (use "git add" and/or "git commit -a")

sh-3.2$ git reset --hard 0ac2bd9c175f7bff9842dcd8179fc9ec67b7002f
HEAD is now at 0ac2bd9c init

sh-3.2$ git clean -fd
Removing custom/Extension/application/Ext/Include/BuildingBlock_HelloWorldDashlet.php
Removing custom/Extension/application/Ext/Include/orderMapping.php
Removing custom/modules/ActivityStream/
Removing custom/modules/Forecasts/Ext/clients/
Removing custom/modules/pmse_Project/

sh-3.2$ git status
On branch main
nothing to commit, working tree clean

You can move on to the Prepare Phase:

Troubleshooting Rector

Rafael Fernandes — Wed, 10 Sep 2025 17:52:31 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 5:52:31 PM

Troubleshooting

Depending on how large your files are or your local environment has in terms of resources, Rector can fail.

Here are few workarounds you can use to troubleshoot and ensure it runs.

Uncaught Error: Class "PHPStan\DependencyInjection\ContainerFactory" not found

[09-Sep-2025 20:09:26 GMT] PHP Fatal error:  Uncaught Error: Class "PHPStan\DependencyInjection\ContainerFactory" not found in /var/www/html/sugar/vendor/rector/rector/src/NodeTypeResolver/DependencyInjection/PHPStanServicesFactory.php:49
Stack trace:
#0 [internal function]: Rector\NodeTypeResolver\DependencyInjection\PHPStanServicesFactory->__construct()
#1 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(843): ReflectionClass->newInstanceArgs(Array)
#2 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build('Rector\\NodeType...')
#3 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\NodeType...', Array)
#4 /var/www/html/sugar/vendor/rector/rector/src/DependencyInjection/LazyContainerFactory.php(273): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\NodeType...')
#5 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(806): Rector\DependencyInjection\LazyContainerFactory::Rector\DependencyInjection\{closure}(Object(Rector\Config\RectorConfig), Array)
#6 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build(Object(Closure))
#7 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\NodeType...', Array)
#8 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(946): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\NodeType...')
#9 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(872): RectorPrefix202411\Illuminate\Container\Container->resolveClass(Object(ReflectionParameter))
#10 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(837): RectorPrefix202411\Illuminate\Container\Container->resolveDependencies(Array)
#11 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build('Rector\\StaticRe...')
#12 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\StaticRe...', Array)
#13 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(946): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\StaticRe...')
#14 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(872): RectorPrefix202411\Illuminate\Container\Container->resolveClass(Object(ReflectionParameter))
#15 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(837): RectorPrefix202411\Illuminate\Container\Container->resolveDependencies(Array)
#16 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build('Rector\\Autoload...')
#17 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\Autoload...', Array)
#18 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(946): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\Autoload...')
#19 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(872): RectorPrefix202411\Illuminate\Container\Container->resolveClass(Object(ReflectionParameter))
#20 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(837): RectorPrefix202411\Illuminate\Container\Container->resolveDependencies(Array)
#21 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(277): RectorPrefix202411\Illuminate\Container\Container->build('Rector\\Console\\...')
#22 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(806): RectorPrefix202411\Illuminate\Container\Container->RectorPrefix202411\Illuminate\Container\{closure}(Object(Rector\Config\RectorConfig), Array)
#23 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build(Object(Closure))
#24 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\Console\\...', Array)
#25 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(496): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\Console\\...')
#26 [internal function]: RectorPrefix202411\Illuminate\Container\Container->RectorPrefix202411\Illuminate\Container\{closure}()
#27 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/ContextualBindingBuilder.php(72): iterator_to_array(Object(RectorPrefix202411\Illuminate\Container\RewindableGenerator))
#28 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Util.php(40): RectorPrefix202411\Illuminate\Container\ContextualBindingBuilder->RectorPrefix202411\Illuminate\Container\{closure}(Object(Rector\Config\RectorConfig))
#29 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(922): RectorPrefix202411\Illuminate\Container\Util::unwrapIfClosure(Object(Closure), Object(Rector\Config\RectorConfig))
#30 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(872): RectorPrefix202411\Illuminate\Container\Container->resolvePrimitive(Object(ReflectionParameter))
#31 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(837): RectorPrefix202411\Illuminate\Container\Container->resolveDependencies(Array)
#32 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build('Rector\\Console\\...')
#33 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(653): RectorPrefix202411\Illuminate\Container\Container->resolve('Rector\\Console\\...', Array)
#34 /var/www/html/sugar/vendor/rector/rector/src/DependencyInjection/LazyContainerFactory.php(244): RectorPrefix202411\Illuminate\Container\Container->make('Rector\\Console\\...')
#35 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(806): Rector\DependencyInjection\LazyContainerFactory::Rector\DependencyInjection\{closure}(Object(Rector\Config\RectorConfig), Array)
#36 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(706): RectorPrefix202411\Illuminate\Container\Container->build(Object(Closure))
#37 /var/www/html/sugar/vendor/rector/rector/vendor/illuminate/container/Container.php(663): RectorPrefix202411\Illuminate\Container\Container->resolve('RectorPrefix202...')
#38 /var/www/html/sugar/vendor/rector/rector/bin/rector.php(129): RectorPrefix202411\Illuminate\Container\Container->get('RectorPrefix202...')
#39 /var/www/html/sugar/vendor/rector/rector/bin/rector(5): require_once('/var/www/html/s...')
#40 {main}

If you're running Sugar < 25, you likely installed rector in the sugar's install directory (where ./vendor is) causing incompatibilities.

just uninstall rector and install it anywhere else.

Child process timed out after 120 seconds

 [ERROR] Could not process                                                                                              
         "/path/to/sugar/rector-0.15.20/vendor/symplify/easy-parallel/src/ValueObject/ParallelProcess.php"  
         file, due to:                                                                                                  
         "Child process timed out after 120 seconds". On line: 108

try to add the following to the end of rector.php:

$rectorConfig->parallel(900);

Reached system errors count limit of 50, exiting...

 [ERROR] Could not process some files, due to:                                                                          
         "Reached system errors count limit of 50, exiting...".

try to add the following to the end of rector.php:

$rectorConfig->disableParallel();

Integrations for Product Devs

Rafael Fernandes — Wed, 10 Sep 2025 15:09:30 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 3:09:30 PM

Integration Approaches

The Sugar platform is extremely powerful, flexible, and allows for easy integration. This flexibility means that determining the best approach for your use case scenario is the key to success.

Push/Pull from Sugar via REST API
- Recommended approach
- Developers have full control over integration
- Integration can be stopped and systems will continue to work
- Retry mechanism: Resume integrations at any time (identify deltas through "last_update_time" flags)
- The time delay from/to Sugar is minimal
- Sugar REST API offers almost everything you need, and can be further extended via customization
Push to Sugar, Sugar pushes to an external queue in realtime
- Use Sugar Events to trigger through Logic Hooks
- Requires Logic Hooks (code customization) to be created and deployed
- Does not offer a "retry mechanism", if a logic hook fails to deliver to a queue or contact an external system
- Synchronous in nature, requires a response from an external system
- Needs to handle dependencies manually (contact can only be created after account)
- Good to have a middleware/queue in front of Sugar to receive those event triggers to reliably manage peak loads
Realtime: Embed your app into Sugar through Dashlets
- Simplest approach
- Often requires web user-based authentication
- All load/traffic goes directly to your system, which makes your system the performance bottleneck

REST API Webservices

Accessing your data when you want is good. Accessing your data however you want is better. When you decide to build an integration with Sugar, you’ll need an easy way to access and interact with the data stored in Sugar. The REST (representational state transfer) API (application programming interface) is perfect for this.

You can also leverage our live Sugar RESTful API Collection

Sugar REST API Overview
- Fully RESTfull (GET, POST, PUT, DELETE)
- OAuth2 token based
- All fields and modules are available through the API automatically
- Metadata API provides everything you need to know about your Sugar instance.

Topics

Common APIs

It is important to understand our most commonly used APIs and their functions within Sugar. Your integration might need data within Sugar's module structure that could potentially change over time, so you can use Metadata for it as well as CRUD onto Sugar.

Metadata
- Endpoint with current system's structure
- Modules, fields, relationships, layouts
- Use carefully, its payload can be MBs in size, cache as much as possible
- GET /metadata (use filters as much as possible)
- It does not retrieve labels for dropdowns, use language API to do so
- 3 Tips for using the Sugar Metadata API
Language
- Endpoint to retrieve labels
- Dropdown list values
- Any language-specific content
- GET /lang/<language_code>
CRUD (Create, Read, Update, Delete) records
- Read: GET /<module>/:record
- Create: POST /<module>
- Update: PUT /<module>/:record
- Delete: DELETE /<module>/:record
- Filter: POST /<module>/filter
  - You can use GET as well
  - POST solves the issue when a query is too long and hits HTTP limits
- Retrieve records related to another module: GET /<module>/:record/link/:link_name
- Creates a relationship to a pre-existing record: POST /<module>/:record/link/:link_name/:remote_id

Performance and Best Practices

As you deep dive into Sugar APIs, you will see how easy it is to integrate to pull and push data from and to Sugar and your systems, however, you must consider performance so your integration doesn't become a bottleneck between those systems.

You should consider the following guidelines when implementing your integrations:

Use Sugar's sync_key to link to remote IDs
- Sugar provides in every module a sync_key field
- sync_key is a unique identifier for that module that links back to your external system's generated key
- For example, account ID from ERP is AC0001, set sync_key (pass as a parameter in the POST) and sugar will create a record in account with sync_key=AC0001
- Next patch/update, sugar will check "where sync_key='AC0001'" and update it (it is indexed)
Use Sugar Integrate Upsert APIs
- Sugar's "update or insert" API based on sync_key
- Simplifies a common operation - if record exists, update it, otherwise create it (GET followed by a PUT or POST)
- Upsert by sync_key
- Get by sync_key
- Delete by sync_key
- Set a sync on existing record (without sync_key)
- Create relationship based on sync_key
- Delete relationship based on sync_key
- Note: This endpoint is engineered for maximum performance and omits several ACL and validation checks.
- Important: For security reasons, the Upsert API is restricted to Admin users only—non-admin users will be denied access.
Use Sugar Bulk API
- An endpoint that encapsulates multiple API calls into one single HTTP request
- Requests are executed synchronously (one after the other)
- Reducing network latency between calls
- Combined with Upsert provides the best performance
- Careful not to add too many requests to it
- Start small (5 to 10 requests) and increase until you reach its max capacity
Polling and filtering time-based with Filter API
- Integration gateway (or your external system) asks Sugar every X minutes
- Request Filter API using max_num (max number of records), offset and fields
- The response will provide the data as well as next_offset (offset can be seen as pagination)
- if next_offset is -1, no more records to go through
Initial Data Load into Sugar
- Use Bulk + Upsert to achieve data loads
- Millions of records may take a little while to process, plan ahead (over the weekend)
- Use multi-thread processes to load (for example 20 threads sending 20 bulk upsert requests)
- Careful with Sugar Cloud rate limits
- It's always a good idea to let Sugar Support know you're data loading, they will be considerate.
Understanding PHP limitations
- PHP is single-threaded with limited resources to process your request
- If you send too much data using bulk, you may run out of memory for that request
- Push to the limits but give some room for PHP to finish the request gracefully
Pagination for millions of records by using OFFSET will degrade performance
- We rely on DB to find, sort and limit records
- Nice article explaining how this works in details
- Instead of offsets, store the last processed ID and use it in the WHERE clause and sort by ID
- Example
  - Instead of: (/v11_25/Leads?max_num=1000&offset=4619000&order_by=id)
  - Do this (/v11_25/Leads?filter=[{"id": {"$gt": ”<last_id>"}}]&max_num=1000&order_by=id)
- If you need to add a date, make sure to add it as part of the filter and order

You're up and running, but don't stop now - this is just the beginning of your journey.

Now it's time for Customization for Product Devs.

Integrations for Devs

Rafael Fernandes — Wed, 10 Sep 2025 15:09:03 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/10/2025 3:09:03 PM

Integration Approaches

The Sugar platform is extremely powerful, flexible, and allows for easy integration. This flexibility means that determining the best approach for your use case scenario is the key to success.

Push/Pull from Sugar via REST API
- Recommended approach
- Developers have full control over integration
- Integration can be stopped and systems will continue to work
- Retry mechanism: Resume integrations at any time (identify deltas through "last_update_time" flags)
- The time delay from/to Sugar is minimal
- Sugar REST API offers almost everything you need, and can be further extended via customization
Push to Sugar, Sugar pushes to an external queue in realtime
- Use Sugar Events to trigger through Logic Hooks
- Requires Logic Hooks (code customization) to be created and deployed
- Does not offer a "retry mechanism", if a logic hook fails to deliver to a queue or contact an external system
- Synchronous in nature, requires a response from an external system
- Needs to handle dependencies manually (contact can only be created after account)
- Good to have a middleware/queue in front of Sugar to receive those event triggers to reliably manage peak loads
Realtime: Embed your app into Sugar through Dashlets
- Simplest approach
- Often requires web user-based authentication
- All load/traffic goes directly to your system, which makes your system the performance bottleneck

REST API Webservices

You can also leverage our live Sugar RESTful API Collection

Sugar REST API Overview
- Fully RESTfull (GET, POST, PUT, DELETE)
- OAuth2 token based
- All fields and modules are available through the API automatically
- Metadata API provides everything you need to know about your Sugar instance.

Topics

Common APIs

Metadata
- Endpoint with current system's structure
- Modules, fields, relationships, layouts
- Use carefully, its payload can be MBs in size, cache as much as possible
- GET /metadata (use filters as much as possible)
- It does not retrieve labels for dropdowns, use language API to do so
- 3 Tips for using the Sugar Metadata API
Language
- Endpoint to retrieve labels
- Dropdown list values
- Any language-specific content
- GET /lang/<language_code>
CRUD (Create, Read, Update, Delete) records
- Read: GET /<module>/:record
- Create: POST /<module>
- Update: PUT /<module>/:record
- Delete: DELETE /<module>/:record
- Filter: POST /<module>/filter
  - You can use GET as well
  - POST solves the issue when a query is too long and hits HTTP limits
- Retrieve records related to another module: GET /<module>/:record/link/:link_name
- Creates a relationship to a pre-existing record: POST /<module>/:record/link/:link_name/:remote_id

Performance and Best Practices

You should consider the following guidelines when implementing your integrations:

Use Sugar's sync_key to link to remote IDs
- Sugar provides in every module a sync_key field
- sync_key is a unique identifier for that module that links back to your external system's generated key
- For example, account ID from ERP is AC0001, set sync_key (pass as a parameter in the POST) and sugar will create a record in account with sync_key=AC0001
- Next patch/update, sugar will check "where sync_key='AC0001'" and update it (it is indexed)
Use Sugar Integrate Upsert APIs
- Sugar's "update or insert" API based on sync_key
- Simplifies a common operation - if record exists, update it, otherwise create it (GET followed by a PUT or POST)
- Upsert by sync_key
- Get by sync_key
- Delete by sync_key
- Set a sync on existing record (without sync_key)
- Create relationship based on sync_key
- Delete relationship based on sync_key
- Note: This endpoint is engineered for maximum performance and omits several ACL and validation checks.
- Important: For security reasons, the Upsert API is restricted to Admin users only—non-admin users will be denied access.
Use Sugar Bulk API
- An endpoint that encapsulates multiple API calls into one single HTTP request
- Requests are executed synchronously (one after the other)
- Reducing network latency between calls
- Combined with Upsert provides the best performance
- Careful not to add too many requests to it
- Start small (5 to 10 requests) and increase until you reach its max capacity
Polling and filtering time-based with Filter API
- Integration gateway (or your external system) asks Sugar every X minutes
- Request Filter API using max_num (max number of records), offset and fields
- The response will provide the data as well as next_offset (offset can be seen as pagination)
- if next_offset is -1, no more records to go through
Initial Data Load into Sugar
- Use Bulk + Upsert to achieve data loads
- Millions of records may take a little while to process, plan ahead (over the weekend)
- Use multi-thread processes to load (for example 20 threads sending 20 bulk upsert requests)
- Careful with Sugar Cloud rate limits
- It's always a good idea to let Sugar Support know you're data loading, they will be considerate.
Understanding PHP limitations
- PHP is single-threaded with limited resources to process your request
- If you send too much data using bulk, you may run out of memory for that request
- Push to the limits but give some room for PHP to finish the request gracefully
Pagination for millions of records by using OFFSET will degrade performance
- We rely on DB to find, sort and limit records
- Nice article explaining how this works in details
- Instead of offsets, store the last processed ID and use it in the WHERE clause and sort by ID
- Example
  - Instead of: (/v11_25/Leads?max_num=1000&offset=4619000&order_by=id)
  - Do this (/v11_25/Leads?filter=[{"id": {"$gt": ”<last_id>"}}]&max_num=1000&order_by=id)
- If you need to add a date, make sure to add it as part of the filter and order

You're up and running, but don't stop now - this is just the beginning of your journey. Now it's time to Customizations.

Sugar Developer Tools

Rafael Fernandes — Tue, 02 Sep 2025 12:42:34 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 9/2/2025 12:42:34 PM

Sugar Test Tools

Certain Sugar Test Tools are only made available to existing Sugar Customers and Sugar Partners and their use is subject to the included Test Tools License. You are required to have a Github account and to be a current Sugar Customer or SugarCRM Partner in order to have your request for access approved. These tools are stored in private Github repositories, this means you need to log into your Github account whenever you want to access them.

Requesting access is easy, all you need to do is send an e-mail to developers@sugarcrm.com with your request. Please allow at least 2 business days for your request to be approved.

Sugar Unit Tests

These unit tests contain both server side (PHP) and client side (JavaScript) test suites. PHP unit tests are implemented in PHPUnit. JavaScript tests are implemented using Jasmine.

Sugar Performance Tests

This package contains the JMeter based load testing tool for Sugar that is used to measure Sugar performance and validate deployment architecture.

Open Source Tools

SugarCRM is committed to an open, dynamic, and scalable Sugar Developer community. For this reason, we have made a variety of tools available as open source software to our community. We encourage contributions from outside SugarCRM because our goal is to foster a vibrant developer community that works to meets needs of all Sugar Developers.

Sidecar Dev Tools

Sidecar Dev Tools is a Google Chrome devtools extension that will help you to be more productive when developing Sugar front end code.

Tidbit

Tidbit is a random record data generator for Sugar. By optimizing the communications with the database, large amounts of data can be inserted into the system automatically.

Sugar Integration Building Blocks

Common components to accelerate development of Sugar integrations. This project is focused on the needs of SugarCRM Technology partners that want to quickly build Sugar integrations that are portable, upgrade safe, and Sugar Cloud friendly.

Candybean

Candybean is a Java based framework for building GUI automation tests that Sugar QA leverages and maintains for building functional automation for Sugar. It supports the Selenium WebDriver.

Sucrose

Sugar’s Chart Library based on D3 and derived from NVD3. Used to build charts for Business Applications.

The Sugar REST Harness

SugarCRM Professional Services has created a REST API test automation framework that they use to test their Enterprise CRM projects. This is a great tool for Sugar Developers looking to build a better automated test practice. It supports a variety of output formats which makes it an ideal Sugar REST API test tool to integrate with a DevOps/CI process.

Tags: Development Best Practices

Sugar 25.2 Customization Guide

Rafael Fernandes — Fri, 15 Aug 2025 13:15:26 GMT

Revision 1 posted to Dev Tutorials by Rafael Fernandes on 8/15/2025 1:15:26 PM

Sugar 25.2 Customization Guide

Integrations for Devs

Rafael Fernandes — Thu, 14 Aug 2025 17:27:02 GMT

Revision 28 posted to Dev Tutorials by Rafael Fernandes on 8/14/2025 5:27:02 PM

Integration Approaches

The Sugar platform is extremely powerful, flexible, and allows for easy integration. This flexibility means that determining the best approach for your use case scenario is the key to success.

Push/Pull from Sugar via REST API
- Recommended approach
- Developers have full control over integration
- Integration can be stopped and systems will continue to work
- Retry mechanism: Resume integrations at any time (identify deltas through "last_update_time" flags)
- The time delay from/to Sugar is minimal
- Sugar REST API offers almost everything you need, and can be further extended via customization
Push to Sugar, Sugar pushes to an external queue in realtime
- Use Sugar Events to trigger through Logic Hooks
- Requires Logic Hooks (code customization) to be created and deployed
- Does not offer a "retry mechanism", if a logic hook fails to deliver to a queue or contact an external system
- Synchronous in nature, requires a response from an external system
- Needs to handle dependencies manually (contact can only be created after account)
- Good to have a middleware/queue in front of Sugar to receive those event triggers to reliably manage peak loads
Realtime: Embed your app into Sugar through Dashlets
- Simplest approach
- Often requires web user-based authentication
- All load/traffic goes directly to your system, which makes your system the performance bottleneck

REST API Webservices

You can also leverage our live Sugar RESTful API Collection

Sugar REST API Overview
- Fully RESTfull (GET, POST, PUT, DELETE)
- OAuth2 token based
- All fields and modules are available through the API automatically
- Metadata API provides everything you need to know about your Sugar instance.

Topics

Common APIs

Metadata
- Endpoint with current system's structure
- Modules, fields, relationships, layouts
- Use carefully, its payload can be MBs in size, cache as much as possible
- GET /metadata (use filters as much as possible)
- It does not retrieve labels for dropdowns, use language API to do so
- 3 Tips for using the Sugar Metadata API
Language
- Endpoint to retrieve labels
- Dropdown list values
- Any language-specific content
- GET /lang/<language_code>
CRUD (Create, Read, Update, Delete) records
- Read: GET /<module>/:record
- Create: POST /<module>
- Update: PUT /<module>/:record
- Delete: DELETE /<module>/:record
- Filter: POST /<module>/filter
  - You can use GET as well
  - POST solves the issue when a query is too long and hits HTTP limits
- Retrieve records related to another module: GET /<module>/:record/link/:link_name
- Creates a relationship to a pre-existing record: POST /<module>/:record/link/:link_name/:remote_id

Performance and Best Practices

You should consider the following guidelines when implementing your integrations:

Use Sugar's sync_key to link to remote IDs
- Sugar provides in every module a sync_key field
- sync_key is a unique identifier for that module that links back to your external system's generated key
- For example, account ID from ERP is AC0001, set sync_key (pass as a parameter in the POST) and sugar will create a record in account with sync_key=AC0001
- Next patch/update, sugar will check "where sync_key='AC0001'" and update it (it is indexed)
Use Sugar Integrate Upsert APIs
- Sugar's "update or insert" API based on sync_key
- Simplifies a common operation - if record exists, update it, otherwise create it (GET followed by a PUT or POST)
- Upsert by sync_key
- Get by sync_key
- Delete by sync_key
- Set a sync on existing record (without sync_key)
- Create relationship based on sync_key
- Delete relationship based on sync_key
Use Sugar Bulk API
- An endpoint that encapsulates multiple API calls into one single HTTP request
- Requests are executed synchronously (one after the other)
- Reducing network latency between calls
- Combined with Upsert provides the best performance
- Careful not to add too many requests to it
- Start small (5 to 10 requests) and increase until you reach its max capacity
Polling and filtering time-based with Filter API
- Integration gateway (or your external system) asks Sugar every X minutes
- Request Filter API using max_num (max number of records), offset and fields
- The response will provide the data as well as next_offset (offset can be seen as pagination)
- if next_offset is -1, no more records to go through
Initial Data Load into Sugar
- Use Bulk + Upsert to achieve data loads
- Millions of records may take a little while to process, plan ahead (over the weekend)
- Use multi-thread processes to load (for example 20 threads sending 20 bulk upsert requests)
- Careful with Sugar Cloud rate limits
- It's always a good idea to let Sugar Support know you're data loading, they will be considerate.
Understanding PHP limitations
- PHP is single-threaded with limited resources to process your request
- If you send too much data using bulk, you may run out of memory for that request
- Push to the limits but give some room for PHP to finish the request gracefully
Pagination for millions of records by using OFFSET will degrade performance
- We rely on DB to find, sort and limit records
- Nice article explaining how this works in details
- Instead of offsets, store the last processed ID and use it in the WHERE clause and sort by ID
- Example
  - Instead of: (/v11_25/Leads?max_num=1000&offset=4619000&order_by=id)
  - Do this (/v11_25/Leads?filter=[{"id": {"$gt": ”<last_id>"}}]&max_num=1000&order_by=id)
- If you need to add a date, make sure to add it as part of the filter and order

You're up and running, but don't stop now - this is just the beginning of your journey. Now it's time to Customizations.

Integrations for Product Devs

Rafael Fernandes — Thu, 14 Aug 2025 17:26:46 GMT

Revision 12 posted to Dev Tutorials by Rafael Fernandes on 8/14/2025 5:26:46 PM

Integration Approaches

The Sugar platform is extremely powerful, flexible, and allows for easy integration. This flexibility means that determining the best approach for your use case scenario is the key to success.

Push/Pull from Sugar via REST API
- Recommended approach
- Developers have full control over integration
- Integration can be stopped and systems will continue to work
- Retry mechanism: Resume integrations at any time (identify deltas through "last_update_time" flags)
- The time delay from/to Sugar is minimal
- Sugar REST API offers almost everything you need, and can be further extended via customization
Push to Sugar, Sugar pushes to an external queue in realtime
- Use Sugar Events to trigger through Logic Hooks
- Requires Logic Hooks (code customization) to be created and deployed
- Does not offer a "retry mechanism", if a logic hook fails to deliver to a queue or contact an external system
- Synchronous in nature, requires a response from an external system
- Needs to handle dependencies manually (contact can only be created after account)
- Good to have a middleware/queue in front of Sugar to receive those event triggers to reliably manage peak loads
Realtime: Embed your app into Sugar through Dashlets
- Simplest approach
- Often requires web user-based authentication
- All load/traffic goes directly to your system, which makes your system the performance bottleneck

REST API Webservices

You can also leverage our live Sugar RESTful API Collection

Sugar REST API Overview
- Fully RESTfull (GET, POST, PUT, DELETE)
- OAuth2 token based
- All fields and modules are available through the API automatically
- Metadata API provides everything you need to know about your Sugar instance.

Topics

Common APIs

Metadata
- Endpoint with current system's structure
- Modules, fields, relationships, layouts
- Use carefully, its payload can be MBs in size, cache as much as possible
- GET /metadata (use filters as much as possible)
- It does not retrieve labels for dropdowns, use language API to do so
- 3 Tips for using the Sugar Metadata API
Language
- Endpoint to retrieve labels
- Dropdown list values
- Any language-specific content
- GET /lang/<language_code>
CRUD (Create, Read, Update, Delete) records
- Read: GET /<module>/:record
- Create: POST /<module>
- Update: PUT /<module>/:record
- Delete: DELETE /<module>/:record
- Filter: POST /<module>/filter
  - You can use GET as well
  - POST solves the issue when a query is too long and hits HTTP limits
- Retrieve records related to another module: GET /<module>/:record/link/:link_name
- Creates a relationship to a pre-existing record: POST /<module>/:record/link/:link_name/:remote_id

Performance and Best Practices

You should consider the following guidelines when implementing your integrations:

Use Sugar's sync_key to link to remote IDs
- Sugar provides in every module a sync_key field
- sync_key is a unique identifier for that module that links back to your external system's generated key
- For example, account ID from ERP is AC0001, set sync_key (pass as a parameter in the POST) and sugar will create a record in account with sync_key=AC0001
- Next patch/update, sugar will check "where sync_key='AC0001'" and update it (it is indexed)
Use Sugar Integrate Upsert APIs
- Sugar's "update or insert" API based on sync_key
- Simplifies a common operation - if record exists, update it, otherwise create it (GET followed by a PUT or POST)
- Upsert by sync_key
- Get by sync_key
- Delete by sync_key
- Set a sync on existing record (without sync_key)
- Create relationship based on sync_key
- Delete relationship based on sync_key
Use Sugar Bulk API
- An endpoint that encapsulates multiple API calls into one single HTTP request
- Requests are executed synchronously (one after the other)
- Reducing network latency between calls
- Combined with Upsert provides the best performance
- Careful not to add too many requests to it
- Start small (5 to 10 requests) and increase until you reach its max capacity
Polling and filtering time-based with Filter API
- Integration gateway (or your external system) asks Sugar every X minutes
- Request Filter API using max_num (max number of records), offset and fields
- The response will provide the data as well as next_offset (offset can be seen as pagination)
- if next_offset is -1, no more records to go through
Initial Data Load into Sugar
- Use Bulk + Upsert to achieve data loads
- Millions of records may take a little while to process, plan ahead (over the weekend)
- Use multi-thread processes to load (for example 20 threads sending 20 bulk upsert requests)
- Careful with Sugar Cloud rate limits
- It's always a good idea to let Sugar Support know you're data loading, they will be considerate.
Understanding PHP limitations
- PHP is single-threaded with limited resources to process your request
- If you send too much data using bulk, you may run out of memory for that request
- Push to the limits but give some room for PHP to finish the request gracefully
Pagination for millions of records by using OFFSET will degrade performance
- We rely on DB to find, sort and limit records
- Nice article explaining how this works in details
- Instead of offsets, store the last processed ID and use it in the WHERE clause and sort by ID
- Example
  - Instead of: (/v11_25/Leads?max_num=1000&offset=4619000&order_by=id)
  - Do this (/v11_25/Leads?filter=[{"id": {"$gt": ”<last_id>"}}]&max_num=1000&order_by=id)
- If you need to add a date, make sure to add it as part of the filter and order

You're up and running, but don't stop now - this is just the beginning of your journey.

Now it's time for Customization for Product Devs.

On-Boarding Product Devs

Rafael Fernandes — Thu, 14 Aug 2025 17:26:21 GMT

Current Revision posted to Dev Tutorials by Rafael Fernandes on 8/14/2025 5:26:21 PM

Register

What steps should a partner or customer follow in order to onboard themselves or a colleague as a new Sugar Developer with access to Sugar development resources?

Read below to learn more about how to provide your new developers with this role.

As a Product Developer you can download our software and have instances hosted locally on your servers. To do so, you need to access Sugar On-Site software downloads and mobile development tools, which is controlled using the Download Manager Authorised Contact role.

Set-up

In order to get access to the Sugar code, you need to be either a SugarCRM customer or a partner. To learn more about our partner program and to apply, please check out our website.

Partners also get access to Sugar cloud instances that they can use to quickly get started. See the Partner Portal for more information about accessing SugarCloud.

Demo Builder provides you with your Sugar Cloud Development environment
Finally, please take time to review our Developer Policy before you begin coding.

First API Call

Web Services APIs are the fastest way to get started with custom Sugar development. The Sugar API documentation is built into every Sugar instance, including Sugar's REST API.

Check out the Sugar Developer Guide for more details on how to access Sugar REST APIs and to get started using them. You can also check out the The School of REST blog series and the Tutorial: Intro to the Sugar REST v10 API.

You can also leverage our live Sugar RESTful API Collection

Making your first API call to Sugar is as easy as 1, 2, 3:

Learn

Getting the most out of Sugar means understanding what can be done via the Sugar Administration panel. We highly recommend Sugar Developers learn about Sugar Administration. Both Sugar Developer and Sugar Administrator training programs are available from Sugar University. There are self-paced videos as well as options for live developer webinars and in-person training.

The Sugar Developer Guide and the Dev Blog are other primary training sources.
There are a lot of great Sugar resources out there in the community as well, so check out this blog post to find many of them.
You should also get familiar with the Sugar Developer Tools that SugarCRM and the Sugar Developer community provide for you. We have tools that help you build, test, debug, and deploy your Sugar solutions even faster.
How will you know when you are ready to rock the Sugar Developer universe? When you get certified! You can learn more about our Sugar Certification program and the Sugar Developer Specialist exam at Training & Certification.
Get involved with our Sugar Community by posting your questions and get answers from a broad audience of experts

Resources & Downloads

Use the additional resources and downloads below to further support your onboarding.

SugarClub	SugarClub DevClub Dev Answers & Best Practices Register with Sugar Sign up to receive the latest Sugar Developer News
Sugar Portals	Support Portal Case Portal Software Downloads Portal Portal Dashboard Get your License Keys DemoBuilder Cloud Environment
Sugar Architecture	Architecture Introduction to Sugar Framework Development Methodology Extensions Framework Supported Platforms

You're up and running, but don't stop now - this is just the beginning of your journey.

Now it's time to Low Code No Code for Product Devs.

Dev Tutorials

Helpful Links

Creating Complex Quotes Documents with Doc Merge

Table of Contents

Introduction

A need for a complex quote document

A new Doc Merge approach

The technical details plus the code and template

Sugar 25.2 Customization Guide

User Experience Updates

Modernized Dropdown Editor

Adding support to Shared Drive files on Google Drive

Enable Row-Level Actions in List View Dashlets

Opportunity Delta in List and Record Views

Add Transcription, Recording, and Summary fields on the Meetings module

Dynamic Record View Dashlet Rendering for Flex Relate Fields in Focus Drawer

Sugar REST API updates

Dropdown Editor

Enhancements to Package Builder APIs’ error handling

Historical Deltas API

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

PHP-Parser

JS Library Upgrades

Low to Minimum Impact Upgrade on various JS libraries

DOMPurify JS Library

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Configurability updates

Improved Control Over Field Updates by Process Definitions

Sugar Config Settings

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

Removal of Unused Platform

Removing gulp-filter JS lib

Removing uglify-js and socket.io JS lib

Data Changes

New Indexes for Calls and Meetings

Platform Updates

Scheduler Jobs Now Run on a Consistent Timezone

Enhanced SystemProcessLock Handling to Prevent Redundant Execution During Admin QRR

Improved Deep Linking Support for SugarCRM on Mobile Devices

Enhanced Content Security Policy (CSP) for Improved Application Security

Declarative Metadata Refactoring

Replace the TCPDF with SugarPdf in MapsGenerator

Added Backend Framework for Dropdown Classifications

Prevent Data Loss on Market MLP Uninstallation and upgrade

SugarLive compatibility with the V2 console for Amazon Connect

Bug Fixes

Sugar Core Security Updates

Healthcheck Updates

Sugar 25.2 Customization Guide

User Experience Updates

Modernized Dropdown Editor

Adding support to Shared Drive files on Google Drive

Enable Row-Level Actions in List View Dashlets

Opportunity Delta in List and Record Views

Add Transcription, Recording, and Summary fields on the Meetings module

Dynamic Record View Dashlet Rendering for Flex Relate Fields in Focus Drawer

Sugar REST API updates

Dropdown Editor

Enhancements to Package Builder APIs’ error handling

Historical Deltas API

PHP Library Upgrades

Upgrade PHP libs to the latest Minor versions without breaking changes

PHP-Parser

JS Library Upgrades

Low to Minimum Impact Upgrade on various JS libraries

DOMPurify JS Library

Supported Platforms Update

Support for OAuth 2.0 token-based authorization with Exchange Online and Sugar email functions

Configurability updates

Improved Control Over Field Updates by Process Definitions

Sugar Config Settings

Removed Functions / Libraries / Features

Removal of Legacy Modules Metadata Extension Path

Removal of Unused Platform

Removing gulp-filter JS lib

Removing uglify-js and socket.io JS lib

Data Changes