SugarBean

Overview

The SugarBean class supports all the model operations to and from the database. Any module that interacts with the database utilizes the SugarBean class, which contains methods to create, read/retrieve, update, and delete records in the database (CRUD), as well as fetch related records.

CRUD Handling

The SugarBean handles the most basic functions of the Sugar database, allowing you to create, retrieve, update, and delete data.

Creating and Retrieving Records

The BeanFactory class is used for bean loading. The class should be used whenever you are creating or retrieving bean objects. It will automatically handle any classes required for the bean. More information on this can be found in the BeanFactory section.

Obtaining the Id of a Recently Saved Bean

For new records, a GUID is generated and assigned to the record id field. Saving new or existing records returns a single value to the calling routine, which is the id attribute of the saved record. The id has the following format:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

You can retrieve a newly created record's id with the following:

  //Create bean
$bean = BeanFactory::newBean($module);

//Populate bean fields
$bean->name = 'Example Record';

//Save
$bean->save();

//Retrieve the bean id
$record_id = $bean->id;

Saving a Bean with a Specific ID

Saving a record with a specific id requires the id and new_with_id attribute of the bean to be set. When doing so, it is important that you use a globally unique identifier. Failing to do so may result in unexpected behavior in the system. An example setting an id is shown below:

  //Create bean
$bean = BeanFactory::newBean($module);

//set the new flag
$bean->new_with_id = true;

//Set the record id with a static id
$id = '38c90c70-7788-13a2-668d-513e2b8df5e1';
$bean->id = $id;

//or have the system generate an id for you
//$id = Sugarcrm\Sugarcrm\Util\Uuid::uuid1()
//$bean->id = $id;

//Populate bean fields
$bean->name = 'Example Record';

//Save
$bean->save();

Setting new_with_id to true prevents the save method from creating a new id value and uses the assigned id attribute. If the id attribute is empty and the new_with_id attribute is set to true, the save will fail. If you would like for the system to generate an id for you, you can use Sugarcrm\Sugarcrm\Util\Uuid::uuid1().

Distinguishing New from Existing Records

To identify whether or not a record is new or existing, you can check the fetched_rows property. If the $bean has a fetched_row, it was loaded from the database. An example is shown below:

  if (!isset($bean->fetched_row['id'])) {
    //new record
} else {
    //existing record
}

If you are working with a logic hook such as before_save or after_save, you should check the arguments.isUpdate property to determine this as shown below:

  <?php

if (!defined('sugarEntry') || !sugarEntry) die('Not A Valid Entry Point');

class logic_hooks_class
{
    function hook_method($bean, $event, $arguments)
    {
        if (isset($arguments['isUpdate']) && $arguments['isUpdate'] == false) {
            //new record
        } else {
            //existing record
        }
    }
}

?>

Retrieving a Bean by Unique Field

Sometimes developers have a need to fetch a record based on a unique field other than the id. In previous versions you were able to use the retrieve_by_string_fields() method to accomplish this, however, that has now been deprecated. To search and fetch records, you should use the SugarQuery builder. An example of this is shown below:

  require_once('include/SugarQuery/SugarQuery.php');
$sugarQuery = new SugarQuery();

//fetch the bean of the module to query
$bean = BeanFactory::newBean('<modules>');

//create first query
$sql = new SugarQuery();
$sql->select('id');
$sql->from($bean);
$sql->Where()->equals('<field>', '<unique value>');

$result = $sql->execute();

$count = count($result);

if ($count == 0) {
    //no results were found
} elseif ($count == 1) {
    //one result was found
    $bean = BeanFactory::getBean('<module>', $result[0]['id']);
} else {
    //multiple results were found
}

Updating a Bean

You can update a bean by fetching a record and then updating the property:

  //Retrieve bean
$bean = BeanFactory::retrieveBean($module, $id);

//Fields to update
$bean->name = 'Updated Name';

//Save
$bean->save();

Note: Disabling row-level security when accessing a bean should be set to true only when it is absolutely necessary to bypass security, for example, when updating a Lead record from a custom Entry Point. An example of accessing the bean while bypassing row security is:

  $bean = BeanFactory::retrieveBean($module, $record_id, array('disable_row_level_security' => true));

Updating a Bean Without Changing the Date Modified

The SugarBean class contains an attribute called update_date_modified, which is set to true when the class is instantiated and means that the date_modified attribute is updated to the current database date timestamp. Setting update_date_modified to false would result in the date_modified attribute not being set with the current database date timestamp.

  //Retrieve bean
$bean = BeanFactory::retrieveBean($module, $id);

//Set modified flag
$bean->update_date_modified = false;

//Fields to update
$bean->name = 'Updated Name';

//Save
$bean->save();

  $bean = BeanFactory::retrieveBean($module, $record_id, array('disable_row_level_security' => true));

Deleting a Bean

Deleting a bean can be done by fetching it then calling the mark_deleted() method which makes sure any relationships with related records are removed as well:

  //Retrieve bean
$bean = BeanFactory::retrieveBean($module, $id);

//Set deleted to true
$bean->mark_deleted($bean->id);

//Save
$bean->save();

  $bean = BeanFactory::retrieveBean($module, $record_id, array('disable_row_level_security' => true));

Fetching Relationships

This section explains how the SugarBean class can be used to fetch related information from the database.

Fetching Related Records

To fetch related records, load the relationship using the link:

  //If relationship is loaded
if ($bean->load_relationship($link)) {
    //Fetch related beans
    $relatedBeans = $bean->$link->getBeans();
}

An example of this is to load the contacts related to an account:

  //Load Account
$bean = BeanFactory::getBean('Accounts', $id);

//If relationship is loaded
if ($bean->load_relationship('contacts')) {
    //Fetch related beans
    $relatedBeans = $bean->contacts->getBeans();
}

Fetching Related Record IDs

To fetch only related record IDs, load the relationship using the link:

  //If relationship is loaded
if ($bean->load_relationship($link)) {
    //Fetch related record IDs
    $relatedBeans = $bean->$link->get();
}

An example of this is to load the record IDs of contacts related to an account:

  //Load Account
$bean = BeanFactory::getBean('Accounts', $id);

//If relationship is loaded
if ($bean->load_relationship('contacts')) {
    //Fetch related beans
    $relatedBeans = $bean->contacts->get();
}

Fetching a Parent Record

Fetching a parent record is similar to fetching child records in that you will still need to load the relationship using the link:

  //If relationship is loaded
if ($bean->load_relationship($link)) {
    //Fetch related beans
    $relatedBeans = $bean->$link->getBeans();

    $parentBean = false;
    if (!empty($relatedBeans)) {
        //order the results
        reset($relatedBeans);

        //first record in the list is the parent
        $parentBean = current($relatedBeans);
    }
}

An example of this is to load a contact and fetch its parent account:

  //Load Contact
$bean = BeanFactory::getBean('Contacts', $id);

//If relationship is loaded
if ($bean->load_relationship('accounts')) {
    //Fetch related beans
    $relatedBeans = $bean->accounts->getBeans();

    $parentBean = false;
    if (!empty($relatedBeans)) {
        //order the results
        reset($relatedBeans);

        //first record in the list is the parent
        $parentBean = current($relatedBeans);
    }
}