ThinkORM 4.0 Documentation

To add ThinkORM to your PHP project, use Composer to require the topthink/think-orm package. This ORM requires PHP 8.0+ and is based on PDO.

composer require topthink/think-orm

A LazyCollection is a memory-efficient collection class designed for handling large datasets. Unlike a standard collection that loads all items into memory at once, LazyCollection uses PHP Generators to iterate through items one by one.

This makes it ideal for processing database results via a cursor or large arrays where loading everything into memory would cause exhaustion. Most operations on a LazyCollection (like map, filter, take, skip) return a new LazyCollection instance, allowing you to chain operations without actually executing them until you iterate over the collection or convert it to an array.

// Example: Using a cursor from a query to create a LazyCollection
$lazyCollection = LazyCollection::make($query->cursor());

foreach ($lazyCollection as $item) {
    // Items are fetched one by one, saving memory
    echo $item->name;
}

In ThinkORM, a MorphOne relationship allows a model to belong to a single related model through a polymorphic interface. This is useful when multiple different models share a single related table (e.g., a Comment model that can belong to either a Post or a Video).

To implement this, you define the relationship in your parent model using the following parameters:

• Model: The target model class.
• Morph Key: The foreign key column in the related table that stores the parent's ID.
• Morph Type: The column in the related table that stores the type (class name or identifier) of the parent model.
• Type: The specific type value used to identify the current parent model in the polymorphic field.

To avoid storing long, fully-qualified class names in your morphType database column, you can use aliases. The setAlias(array $alias) method allows you to map short identifiers to actual model class names.

When parseModel is called during relationship resolution, it checks this alias map first.

// Define aliases so the DB stores 'post' instead of 'App\Model\Post'
$relation->setAlias(['post' => Post::class, 'video' => Video::class]);

You can manipulate the data within a LazyCollection using several functional methods. These methods return a new LazyCollection and do not execute immediately:

• map(callable $callback): Transforms each item using the provided callback.
• filter(?callable $callback = null): Filters items. If no callback is provided, it filters by truthiness.
• take(int $limit): Returns a new collection containing only the first $limit items.
• skip(int $offset): Skips the first $offset items.
• page(int $page, int $listRows = 15): Returns a subset of the collection based on pagination logic (starting from page 1).

$results = LazyCollection::make($largeDataset)
    ->filter(fn($item) => $item->active)
    ->map(fn($item) => $item->name)
    ->take(10);

foreach ($results as $name) {
    echo $name;
}

If you want to inspect the generated SQL query before it is executed, use the fetchSql() method. This returns a Fetch object that allows you to retrieve the SQL string.

• fetchSql(bool $fetch = true): Sets the mode to fetch SQL. If $fetch is true, it returns a Fetch instance which can then be used to call methods like select(), update(), etc., to get the string.

// Get the SQL string for a select query
$sql = Db::name('user')->where('id', 1)->fetchSql()->select();
// Output: SELECT * FROM `user` WHERE `id` = 1

The enclose(bool $enclose = true) method determines whether the resulting parsed array will be wrapped in an extra set of parentheses. This is useful when the Where object represents a sub-clause that needs to be isolated within a larger SQL statement.

• If $enclose is true, parse() returns [ [$condition1, $condition2, ...] ].
• If $enclose is false, parse() returns [ $condition1, $condition2, ... ].

$where = new Where(['id' => 1]);

$where->enclose(true);
$parsed = $where->parse();
// Result: [ [['id', '=', 1]] ]

$where->enclose(false);
$parsed = $where->parse();
// Result: [['id', '=', 1]]

Use the load() method to perform lazy eager loading on all models within the collection. This is useful for resolving relationships for a set of models in a single query rather than one by one.

Parameters:

• array $relation: The name(s) of the relation(s) to load.
• mixed $cache: Whether to use cache for the relation (default false).
• bool $withJoin: Whether to use a JOIN for the relation (default false).

// Eager load the 'user' relation for all models in the collection
$collection->load(['user']);

// Eager load with cache and JOIN
$collection->load(['profile'], true, true);