Skip to content

Value Objects

As of v7.0.

  • Value objects are immutable.
  • Value objects are available in Espo\Core\Field\.
  • It's possible to define custom value object for a field type or for a specific field.

Methods in BaseEntity:


$valueObject = $entity->getValueObject($field);

$entity->setValueObject($field, $valueObject);

$entity->setValueObject($field, null); // null can be set

Supported field types



$address = $accountEntity->getBillingAddress() ?? new Address();

$country = $address->getCountry();
$city = $address->getCity();

$address = Address::create()




$value = new Currency($amount, 'USD');

$valueInEur = $converter->convert($value, 'EUR');


Email address, Phone number


$emailAddressGroup = $accountEntity->getEmailAddressGroup();

$primary = $emailAddressGroup->getPrimary();

$modifiedEmailAddressGroup = $emailAddressGroup


The same is available for phone numbers.

Date, DateTime, DateTimeOptional


$closeDate = $opportunityEntity->getCloseDate();

    $closeDate->modify('+1 month')

$account = $entity->getAccount(); // Link value object

$accountId = $account->getId();
$accountName = $account->getName();

    LinkParent::create($entityType, $id)

$contacts = $entity->getContacts(); // Link-Multiple value object


$contact = LinkMultipleItem
    ->withColumnValue('role', 'Decision Maker');



Defining a custom value object type for a specific field type.

For a field type you need to define 2 parameters in metadata > fields > {fieldType}:

  • valueFactoryClassName – implementation of Espo\ORM\Value\ValueFactory interface;
  • attributeExtractorClassName – implementation of Espo\ORM\Value\AttributeExtractor interface.

It's also possible to define a value object for a specific field in metadata > entityDefs > {entityType} > fields > {fieldName}:

  • valueFactoryClassName;
  • attributeExtractorClassName.