CRUD Handling

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.

Create & Read

Creating and Retrieving Records

The BeanFactory class is used for bean loading. The class should be used any time 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 records id by doing 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 as follows:

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

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

//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.

Identifying 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
}

Update

Updating a Bean

Updating a bean can be done by fetching a record and then updating the property:

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

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

//Save 
$bean->save();

Updating a Bean without Modifying 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 the 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::getBean($module, $id);

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

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

//Save
$bean->save();

Delete

Deleting a Bean

Deleting a bean can be done by fetching a record and then setting the deleted property to 1:

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

//Set deleted to true
$bean->deleted = 1;

//Save 
$bean->save();