Service » Array operators

Atomically push values into or pull values out of array fields on a document using MongoDB's $push and $pull operators.

About array operators

Mondoc provides protected static helpers for pushing values into and pulling values out of array fields. Because they are protected, you expose only the operations that make sense for your domain by wrapping them in public static methods on your own service class.

All operations are atomic — a single updateOne command is issued to MongoDB with no prior read required.

These methods work with scalar values (strings, integers, booleans). Pushing or pulling complex objects or nested arrays is not supported by these helpers; use updateOne() directly in that case.

Push

  • pushIntoArrayById(ObjectId $id, string $field, string $value, bool $distinct = true): bool
    Pushes $value into the array field $field on the document identified by $id. When $distinct is true (default), the push is only performed if the value does not already exist in the array, preventing duplicates.
  • pushIntoArrayWithFilter(array $filter, string $field, mixed $value): bool
    Pushes $value into the array field $field on the first document matching $filter. No duplicate-check is applied; build the filter to enforce any uniqueness constraint you need.

Pull

  • pullFromArrayById(ObjectId $id, string $field, string|int|bool $value): bool
    Removes all occurrences of $value from the array field $field on the document identified by $id.
  • pullFromArrayWithFilter(array $filter, string $field, mixed $value): bool
    Removes all occurrences of $value from the array field $field on the first document matching $filter.

Exposing operators in your service

Wrap the protected methods in your service to expose only what your application needs. 

<?php
use District5\Mondoc\Db\Service\MondocAbstractService;
use MongoDB\BSON\ObjectId;

class UserService extends MondocAbstractService
{
    protected static function getCollectionName(): string
    {
        return 'users';
    }

    /**
     * Add a role string to a user's 'roles' array (distinct by default).
     */
    public static function addRole(ObjectId $userId, string $role): bool
    {
        return self::pushIntoArrayById($userId, 'roles', $role);
    }

    /**
     * Remove a role string from a user's 'roles' array.
     */
    public static function removeRole(ObjectId $userId, string $role): bool
    {
        return self::pullFromArrayById($userId, 'roles', $role);
    }

    /**
     * Add a tag to all documents matching a custom filter.
     */
    public static function addTagWhere(array $filter, string $tag): bool
    {
        return self::pushIntoArrayWithFilter($filter, 'tags', $tag);
    }
}

Usage 

<?php
$user = UserService::getById($someObjectId);

// Add a role (will not duplicate if already present)
UserService::addRole($user->getObjectId(), 'editor');

// Remove a role
UserService::removeRole($user->getObjectId(), 'editor');

// Add a tag to all active users in the 'GB' region
UserService::addTagWhere(['active' => true, 'region' => 'GB'], 'beta');
Recommended reading:
Atomic operationsfast_rewind fast_forward Aggregation