RxDB - Replication with Laravel Orion

The Orion replication provides handlers for run replication with Orion REST API as the transportation layer.

Installation

npm i rxdb-orion

Usage

The package usage is simple, but there are some important rules to follow

Frontend

• Array properties with ref will be replicated using sync route
• For other relationship properties, a specific replication will be required for each one.

import { replicateOrion } from 'rxdb-orion';
import { userSchema } from './schemas/user';
import { roleSchema } from './schemas/role';

const database = await createRxDatabase({
  name: 'mydb',
  storage: getRxStorageDexie(),
});

await database.addCollections({
  users: {
    schema: userSchema,
  },
  roles: {
    schema: roleSchema,
  },
});

const replicationState = replicateOrion({
  url: 'http://my.fake.api/users',
  params: { include: 'roles' },
  collection: users,
  batchSize: 3,
});

await replicationState.start();

Manager

It is common for an application to require handling multiple replications. For this reason, the package includes the Manager class to assist in such situations.

As Laravel Orion backend is unable to send events to the client, the manager executes reSync() every 10000ms by default.

You can customize the interval as you see fit.

import { replicateOrion, Manager } from 'rxdb-orion';

const manager = new Manager([
  replicateOrion({
    url: 'http://my.fake.api/users',
    params: { include: 'roles' },
    collection: users,
    batchSize: 3,
  }),
  replicateOrion({
    url: 'http://my.fake.api/categories',
    collection: categories,
    batchSize: 3,
  }),
], 5000);

await manager.start();

Database

Important: To ensure correct replication, define your created_at, updated_at, and deleted_at fields as timestamp(6) in your database migrations. This allows storage of milliseconds, which is required for accurate checkpointing and synchronization.

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

class CreateCategoriesTable extends Migration
{
  public function up()
  {
    Schema::create('categories', function (Blueprint $table) {
      $table->uuid('id')->primary();
      $table->string('name');
      $table->timestamps(6);
      $table->softDeletes(precision: 6);
    });
  }

  public function down()
  {
    Schema::dropIfExists('categories');
  }
}

Warning: When a model has hasMany relations, replications run in parallel. Child records can be created before their parent record, so a foreign key constraint may be violated on the server.

For this reason, do not create a foreign key constraint for hasMany relations in your migrations. Store the parent id as a plain column instead.

Model

The package uses a Scope to request all documents that have been written after the given checkpoint.

Therefore, it is recommended to create a trait for making the necessary model customizations.

<?php

namespace App\Traits;

use Illuminate\Database\Eloquent\Casts\Attribute;

trait Syncable {

    /**
     * Prepare a date for array / JSON serialization.
     *
     * @param  \DateTimeInterface  $date
     * @return string
     */
    protected function serializeDate(DateTimeInterface $date)
    {
        $instance = $date instanceof DateTimeImmutable
            ? CarbonImmutable::instance($date)
            : Carbon::instance($date);

        return $instance->toDateTimeString('millisecond');
    }

    /**
     * Determine if model is deleted
     */
    protected function _deleted(): Attribute
    {
        return Attribute::make(
            get: fn () => $this->deleted_at !== null,
        );
    }

    /**
     * Scope a query to only include models changed after given value.
     *
     * @param  \Illuminate\Database\Eloquent\Builder  $query
     * @param  int  $updatedAt
     * @param  string  $id
     * @return \Illuminate\Database\Eloquent\Builder
     */
      public function scopeMinUpdatedAt(Builder $query, string $updatedAt, ?string $id = null): Builder
      {
          return $query->where('updated_at', '>', $updatedAt)
              ->when($id, fn($query) =>
                  $query->orWhere(function($query) use ($updatedAt, $id) {
                      $query->where('updated_at', $updatedAt)->where('id', '>', $id);
                  })
              )
              ->orderBy('updated_at');
      }
}

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class User extends Model {

    use Syncable;

    ....
}

Server-side attachments with Spatie Media Library

If you need attachments to sync across multiple devices, you must persist the file data on the server. The recommended approach is to use Spatie Media Library with an Orion controller hook. The _attachments field flows directly in the request body — no push modifier needed.

1. Configure the model

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Casts\Attribute;
use Spatie\MediaLibrary\HasMedia;
use Spatie\MediaLibrary\InteractsWithMedia;
use App\Traits\Syncable;

class User extends Model implements HasMedia
{
    use InteractsWithMedia;
    use Syncable;

    /**
     * Return base64-encoded attachments so RxDB can
     * store them locally on pull.
     */
    protected function _attachments(): Attribute
    {
        return Attribute::make(
            get: fn () => $this->getMedia('attachments')->mapWithKeys(function ($media) {
                return [$media->file_name => [
                    'type' => $media->mime_type,
                    'data' => base64_encode(stream_get_contents($media->stream())),
                ]];
            })->toArray(),
        );
    }
}

2. Create a reusable controller trait

<?php

namespace App\Http\Controllers\Api\Traits;

use Illuminate\Http\Request;
use Illuminate\Database\Eloquent\Model;

trait HandlesMedia
{
    /**
     * Process _attachments sent via push replication.
     * The _attachments field contains { name: { type, data } }
     * where data is base64-encoded.
     */
    protected function saveAttachments(Request $request, Model $model): void
    {
        $attachments = $request->input('_attachments', []);

        if (empty($attachments)) {
            return;
        }

        $model->getMedia()->each(fn($media) => $media->delete());

        foreach ($attachments as $name => $meta) {
            if (empty($meta['data'])) {
                continue;
            }

            $model->addMediaFromBase64($meta['data'])
                ->usingName($name)
                ->usingFileName($name)
                ->toMediaCollection();
        }
    }
}

4. Use the trait in your Orion controllers

<?php

namespace App\Http\Controllers\Api;

use Orion\Http\Controllers\Controller;
use App\Models\User;
use App\Http\Controllers\Api\Traits\HandlesMedia;

class UsersController extends Controller
{
    use HandlesMedia;

    protected $model = User::class;

    protected function afterSave(Request $request, User $user): void
    {
        $this->saveAttachments($request, $user);
    }
}

You can still add your own logic before or after calling saveAttachments