Session: Loading Entities

The most basic way to load a single entity is to use the load method.

public function load(?string $className, ?string $id): ?object;

Example

/** @var Employee $employee */
$employee = $session->load(Employee::class, "employees/1");

When there is a 'relationship' between documents, those documents can be loaded in a single request call using the include + load methods. Learn more in How To Handle Document Relationships.

function include(?string $path): LoaderWithIncludeInterface;

public function load(string $className, array $ids): ObjectArray;
public function load(string $className, StringArray $ids): ObjectArray;

public function load(string $className, string $id): ?object;

Example I

We can use this code to also load an employee which made the order.

// loading 'products/1'
// including document found in 'supplier' property

/** @var Product $product */
$product = $session
    ->include("Supplier")
    ->load(Product::class, "products/1");

$supplier = $session->load(Supplier::class, $product->getSupplier()); // this will not make server call

Example II

// loading 'products/1'
// including document found in 'supplier' property
/** @var Product $product */
$product = $session
    ->include("Supplier")
    ->load(Product::class, "products/1");

$supplier = $session->load(Supplier::class, $product->getSupplier()); // this will not make server call

To load multiple entities at once, use one of the following load overloads.

public function load(string $className, array $ids): ObjectArray;
public function load(string $className, StringArray $ids): ObjectArray;

$employees = $session->load(Employee::class, "employees/1", "employees/2", "employees/3");

To load multiple entities that contain a common prefix, use the loadStartingWith method from the advanced session operations.

public function loadStartingWith(
    string $className,
    ?string $idPrefix,
    ?string $matches = null,
    int $start = 0,
    int $pageSize = 25,
    ?string $exclude = null,
    ?string $startAfter = null
): ObjectArray;

Example I

// return up to 128 entities with Id that starts with 'employees'
$result = $session
    ->advanced()
    ->loadStartingWith(Employee::class, "employees/", null, 0, 128);

Example II

// return up to 128 entities with Id that starts with 'employees/'
// and rest of the key begins with "1" or "2" e.g. employees/10, employees/25
$result = $session
    ->advanced()
    ->loadStartingWith(Employee::class, "employees/", "1*|2*", 0, 128);

This method can be used to check whether a document has been modified since the last time its change vector was recorded, so that the cost of loading it can be saved if it has not been modified.

The conditionalLoad method takes a document's change vector. If the entity is tracked by the session, this method returns the entity. If the entity is not tracked, it checks if the provided change vector matches the document's current change vector on the server side. If they match, the entity is not loaded. If the change vectors do not match, the document is loaded.

The method is accessible from the session advanced operations.

function conditionalLoad(?string $className, ?string $id, ?string $changeVector): ConditionalLoadResult;

Example

$session = $store->openSession();
try {
    $changeVector = "";
    $user = new User("Bob");

    $session->store($user, "users/1");
    $session->saveChanges();

    $changeVector = $session->advanced()->getChangeVectorFor($user);
} finally {
    $session->close();
}

$user = new User("Bob");
$changeVector = "a";

$session = $store->openSession();
try {
    // New session which does not track our User entity

    // The given change vector matches
    // the server-side change vector
    // Does not load the document
    $result1 = $session->advanced()
        ->conditionalLoad(User::class, "users/1", $changeVector);

    // Modify the document
    $user->setName("Bob Smith");
    $session->store($user);
    $session->saveChanges();

    // Change vectors do not match
    // Loads the document
    $result2 = $session->advanced()
        ->conditionalLoad(User::class, "users/1", $changeVector);
} finally {
    $session->close();
}

Use the isLoaded method from the advanced session operations To check if an entity is attached to a session (e.g. because it's been previously loaded).

function isLoaded(string $id): bool;

Example

$isLoaded = $session->advanced()->isLoaded("employees/1"); //false
$employee = $session->load(Employee::class, "employees/1");
$isLoaded = $session->advanced()->isLoaded("employees/1"); // true