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:

<?php

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

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

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

Supported field types

Address

<?php

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

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

<?php

$address = Address::create()
    ->withCity($city)
    ->withCountry($country)
    ->withPostalCode($postalCode);

$accountEntity->setBillingAddress($address);

Currency

<?php

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

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

$opportunityEntity->setAmount($valueInEur);

Email address, Phone number

<?php

$emailAddressGroup = $accountEntity->getEmailAddressGroup();

$primary = $emailAddressGroup->getPrimary();

$modifiedEmailAddressGroup = $emailAddressGroup
    ->withAddedEmailAddress(
        EmailAddress::create('address@test.com')->optedOut()
    );

$accountEntity->setEmailAddressGroup($modifiedEmailAddressGroup);

The same is available for phone numbers.

Date, DateTime, DateTimeOptional

<?php

$closeDate = $opportunityEntity->getCloseDate();

$opportunityEntity->setCloseDate(
    $closeDate->modify('+1 month')
);

<?php

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

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

<?php

$entity->setParent(
    LinkParent::create($entityType, $id)
);

<?php

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

$entity->setContacts(
    $contacts->withRemovedById($id)
);

<?php

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

$entity->setContacts(
    LinkMultiple::create([$contact->getId()]);
);

Defining

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.