Download the PHP package cyclechain/sandboxer without Composer

Sandboxer

A zero-modification Laravel package that provides complete data isolation for live product demos, SaaS playgrounds, interactive trial sessions, and testing environments—without altering a single line of your existing models, migrations, or database tables.

🎯 The Problem Sandboxer Solves

When offering live demos or trial sessions for your SaaS or web application, visitors often want to create, edit, or delete data (e.g., creating blog posts, adding products, modifying settings).

Traditionally, developers had to choose between:

1. Resetting the database periodically: Interrupts active users and causes data collisions across simultaneous visitors.
2. Modifying application logic & models: Polluting codebase with tenant checks, session filters, or custom traits.
3. Spinning up isolated containers per user: Expensive, slow, and hard to manage at scale.

🚀 The Sandboxer Solution

Sandboxer intercepts Eloquent CRUD operations per user session transparently. Any data created, updated, or deleted by a demo visitor exists only in their isolated sandbox session.

• Master Database is 100% untouched: Production data remains safe and pristine.
• Zero Model Modifications: Works out-of-the-box without adding traits or modifying your Eloquent models or migrations.
• Multi-Visitor Isolation: Visitor A sees their sandboxed changes; Visitor B sees theirs—neither affects the master database or each other.
• Automatic Expiration & Cleanup: Sessions and sandboxed data expire automatically after a configured TTL.

📦 Installation

Install Sandboxer via Composer.

1. Production & Live Demo Installation

If you are deploying Sandboxer to provide live demo environments, interactive product tours, or sandbox mode in your production or staging SaaS application, install it as a main dependency:

2. Development & Testing Installation

If you are using Sandboxer strictly for local development isolation, testing, or preview environments, install it as a dev dependency:

⚙️ Setup & Migration

Publish the configuration file:

Run the package database migrations (creates sandbox_sessions and sandbox_storage tables):

🚀 Quick Start

Enable sandbox mode in your .env file:

That's it! Sandboxer automatically intercepts database operations whenever sandbox mode is activated.

🔍 Automatic Sandbox Activation

Sandboxer can automatically detect and activate sandbox mode for incoming HTTP requests based on:

1. Subdomains: demo.yourdomain.com, sandbox.yourdomain.com, try.yourdomain.com
2. URL Paths: /demo, /sandbox, /try
3. Query Parameters: ?sandbox=1, ?demo=true
4. Active Session Cookie: sandbox_session cookie

Configure auto-detection in config/sandboxer.php:

📖 Usage

Sandbox Authentication Integration

For applications requiring demo user login, update your login controller (or custom auth handler) using SandboxAuthHelper:

Manual Sandbox Control

Use the Sandboxer Facade to check or control sandbox state manually:

🧹 Session Expiration & Automatic Cleanup

Sandbox sessions expire automatically based on the SANDBOXER_TTL setting (default: 3600 seconds / 1 hour).

To clean up expired sessions, schedule the SandboxCleanupJob in your app/Console/Kernel.php or routes/console.php:

Or dispatch manually:

🏗️ How It Works (Architecture)

1. Write Interception: When a model is created, updated, or deleted, ModelEventInterceptor captures the attributes, places the database connection in pretend mode (preventing actual SQL writes), and persists the mutation into sandbox_storage.
2. Read Interception: When Eloquent queries execute (all(), where(), find()), SandboxScope overlays sandboxed insertions, updates, and deletions onto the retrieved master data.

⚙️ Configuration Reference

Edit config/sandboxer.php:

🧪 Testing

Run the PHPUnit test suite:

Or via Docker:

📄 License

The MIT License (MIT). Please see License File for more information.

👨‍💻 Credits

Developed and maintained by Fatih Mert Doğancan & CycleChain.