Sandbox Laravel Package

Getting Started

Upgrade to 1.1.0 normally and run your test suite; there is no database migration. First inspect the SandboxBelongsToMany relation class, especially the syncAcrossCopies() signature and the 39 contract tests added in this release. Those tests are the quickest reference for accepted payload shapes, return values, and rejected relation configurations.

A good first use case is a back-office assignment change that must be visible immediately on both the active record and its draft copy without opening a new draft or changing ownership. Use it inside an existing transaction:

DB::transaction(function () use ($activeCopy, $tagIds, $userId) {
    $copies = $activeCopy->tags()->syncAcrossCopies(
        collect($tagIds)->mapWithKeys(fn ($id) => [
            $id => ['assigned_by' => $userId],
        ])->all()
    );

    $copies->each->touch();
});

Implementation Patterns

Use syncAcrossCopies() when the relationship change is intended to cross the active/draft boundary directly. It accepts an ID list, a pivot attribute map, or a payload factory. Prefer the simple ID list for plain many-to-many assignments and the pivot map when pivot metadata must be written alongside the assignment.

Use a payload factory when the IDs or pivot data depend on state that should be read only after parent locks are acquired. Keep the factory deterministic and side-effect free; it is evaluated once after parent locks, so do not rely on it being called repeatedly and avoid performing writes inside it.

Treat the return value as the integration point for the rest of the transaction. It returns the affected parent copies, so iterate over them to touch timestamps, refresh read models/projections, write audit records, or queue follow-up work after commit. Dispatch domain events after the transaction commits if they depend on the final relationship state.

Preserve custom Pivot behavior by continuing to use the package relation rather than manual attach/detach loops. If the application relies on custom pivot events or pivot model methods, verify those side effects still occur exactly once.

The method applies the selected copy’s removal delta to both copies while preserving unrelated assignments in the opposite copy. That is useful for targeted edits, but it is not a full mirror operation. If business rules require both copies to have identical assignment sets, confirm that this delta-based behavior matches the requirement before relying on it.

Gotchas and Tips

Do not use this on filtered many-to-many relations or relations with identity overrides. The release explicitly rejects unsupported filtered relations and identity overrides, so relations using constraints such as pivot filters or custom identity logic should continue using the normal draft workflow or be refactored into a clean relation.

The method compares raw database keys while retaining global-scope filters. That helps matching across copies, but global scopes still apply. If a scope hides the active or draft copy, synchronization may not behave as expected; check scopes before reaching for withoutGlobalScope.

Because unrelated assignments in the opposite copy are preserved, do not assume a call is a destructive “replace everything” sync. Test removal scenarios explicitly, especially when draft and active copies have diverged.

Keep the call inside a transaction. The return value is intended for same-transaction timestamp, projection, and audit updates. Side effects that must not run on rollback should be deferred until after commit.

No migration is required for 1.1.0. The generated-column and Oracle discovery improvements from 1.0.2 are retained, so Oracle users should still run their normal package tests but do not need schema changes for this release.

Use the 39 contract tests as extension-point documentation. They are the best guide for expected payload normalization, rejected relation configurations, custom pivot behavior, and return semantics. Add at least one application-level integration test covering your own global scopes, custom pivot model, and audit/timestamp flow.