Edit this Page

Repositories and Selectors

In order to select or create specific entity you must create repository class.


To create and automatically link repository class to your Document create class extending DocumentSource and define DOCUMENT constant pointing to your model:

class UserRepository extends DocumentSource
    const DOCUMENT = User::class;

You can access your repository right after running odm:schema command:

protected function indexAction(UserRepository $users)
    //Alternative approach 
    $users = $this->odm->source(User::class);

Create entity

To create record entity call method create of your repository:

$user = $users->create([
    'name' => 'Antony'


Note, that entity values will be populated using setFields method, make sure that you have FILLABLE and SECURED constants property set.

Attention, create would only initiate blank model entity, you have to save it into database manually.

Find Entities

Use methods findByPK, findOne and find to load entities from database:

$user = $users->findOne(['name' => 'Antony']);


Use method findByPK to select entity using id:

protected function indexAction(string $id, UsersRepository $users)
    if (empty($user = $users->findByPK((int)$id))) {
        throw new NotFoundException('No such user');



Method find of your Repository will return entity specific DocumentSelector with included query builder and paginator:

$users = $users->find()->where([
    'name' => 'Antony'

Custom find methods

In order to simplify your domain layer, it is recommended to define custom find commands specific to your application into repository class:

public function findActive(): DocumentSelector
    return $this->find(['status' => 'active']);

You can also chain this methods inside your repository:

public function findAuthors(): DocumentSelector
    return $this->findActive()->where(['type' => 'author']);

Overwrite repository selector

In some cases you might want to set base query for all of your find method. You can do it in your repository constructor or use public method withSelector:

$deletedUsers = $users->withSelector(
    $users->find(['status' => 'deleted'])

All repositories are treated as immutable.

Static Access

If you wish to access record repository and selector using static functions use Spiral\ODM\SourceTrait.

class User extends Record
    use SourceTrait;

    const SCHEMA = [
        '_id'   => ObjectId::class,
        'name'  => 'string',
        'email' => 'string'

    const DEFAULTS = [];

    const INDEXES = [];


Please note, this method will only work in global container scope (inside your application).

Get Projection

To fetch only specific fields from your database use DocumentSelector method getProjection:

$cursor = $users->find(['active' => true])->getProjection(['email']);
dump($cursor); // MongoDB\Driver\Cursor