How to Check for Session Changes

• The advanced session hasChanges property indicates whether any entities were added, modified, or deleted within the session.

• Note: The hasChanges property is cleared (reset to false) after calling saveChanges.

$session = $store->openSession();
try {
    // No changes made yet - 'hasChanges' will be FALSE
    $this->assertFalse($session->advanced()->hasChanges());

    // Store a new entity within the session
    $employee = new Employee();
    $employee->setFirstName("John");
    $employee->setLastName("Doe");

    $session->store($employee, "employees/1-A");

    // 'hasChanges' will now be TRUE
    $this->assertTrue($session->advanced()->hasChanges());

    // 'HasChanges' will reset to FALSE after saving changes
    $session->saveChanges();
    $this->assertFalse($session->advanced()->hasChanges());

} finally {
    $session->close();
}

• Use the session's advanced method whatChanged to get all changes made to all the entities tracked by the session.

• For each entity that was modified, the details will include:

  • The name and path of the changed field
  • Its old and new values
  • The type of change

Example I

$session = $store->openSession();
try {
    // Store (add) new entities, they will be tracked by the session
    $employee = new Employee();
    $employee->setFirstName("John");
    $employee->setLastName("Doe");
    $session->store($employee, "employees/1-A");

    $employee = new Employee();
    $employee->setFirstName("Jane");
    $employee->setLastName("Doe");
    $session->store($employee, "employees/2-A");

    // Call 'WhatChanged' to get all changes in the session
    $changes = $session->advanced()->whatChanged();

    $this->assertCount(2, $changes); // 2 entities were added

    // Get the change details for an entity, specify the entity ID
    $changesForEmployee = $changes["employees/1-A"];
    $this->assertCount(1, $changesForEmployee); // a single change for this entity (adding)

    // Get the change type
    $change = $changes[0]->getChange(); // ChangeType::DOCUMENT_ADDED
    $this->assertTrue($change->isDocumentAdded());

    $session->saveChanges();

} finally {
    $session->close();
}

Example II

$session = $store->openSession();
try {
    // Load the entities, they will be tracked by the session
    $employee1 = $session->load(Employee::class, "employees/1-A");// 'Joe Doe'
    $employee2 = $session->load(Employee::class, "employees/2-A");// 'Jane Doe'

    // Modify entities
    $employee1->setFirstName("Jim");
    $employee1->setLastName("Brown");
    $employee2->setLastName("Smith");

    // Delete an entity
    $session->delete($employee2);

    // Call 'WhatChanged' to get all changes in the session
    $changes = $session->advanced()->whatChanged();

    // Get the change details for an entity, specify the entity ID
    $changesForEmployee = $changes["employees/1-A"];

    $this->assertEquals("FirstName", $changesForEmployee[0]->getFieldName()); // Field name
    $this->assertEquals("Jim", $changesForEmployee[0]->getFieldNewValue());   // New value
    $this->assertTrue($changesForEmployee[0]->getChange()->isFieldChange());  // Change type

    $this->assertEquals("LastName", $changesForEmployee[1]->getFieldName());  // Field name
    $this->assertEquals("Brown", $changesForEmployee[1]->getFieldNewValue()); // New value
    $this->assertTrue($changesForEmployee[1]->getChange()->isFieldChange());  // Change type

    // Note: for employee2 - even though the LastName was changed to 'Smith',
    // the only reported change is the latest modification, which is the delete action.
    $changesForEmployee = $changes["employees/2-A"];
    $this->assertTrue($changesForEmployee[0]->getChange()->isDocumentDeleted());

    $session->saveChanges();

} finally {
    $session->close();
}

public function hasChanges(): bool;

public function whatChanged(): array; // array<string, DocumentsChangesArray>

class DocumentsChanges
{
    private mixed $fieldOldValue = null;            // Previous field value
    private mixed $fieldNewValue = null;            // Current field value
    private ChangeType $change;                     // Type of change that occurred
    private ?string $fieldName = null;              // Name of field on which the change occurred
    private ?string $fieldPath = null;              // Path of field on which the change occurred

    public function getFieldFullName(): ?string;    // Path + Name of field on which the change occurred

    // ... getters and setters
}

class ChangeType
{
    public function isDocumentDeleted(): bool;
    public function isDocumentAdded(): bool;
    public function isFieldChanged(): bool;
    public function isNewField(): bool;
    public function isRemovedField(): bool;
    public function isArrayValueChanged(): bool;
    public function isArrayValueAdded(): bool;
    public function isArrayValueRemoved(): bool;

}