Project setup

Commit .phpsandbox/setup.json when a project needs repeatable preparation. PHPSandbox reads it when preparing the sandbox, so the Workspace and SDK use the same project setup.

A complete example

{
  "env": {
    "APP_ENV": "local",
    "LOG_CHANNEL": "stderr"
  },
  "up": {
    "application key": "php artisan key:generate",
    "database": "php artisan migrate --force"
  },
  "tasks": {
    "queue": "php artisan queue:work --tries=3"
  },
  "services": {
    "redis": true,
    "mysql": true
  },
  "ports": [
    {
      "localPort": 8000,
      "externalPort": 80,
      "primary": true
    }
  ],
  "startCmd": "php artisan serve --host=0.0.0.0 --port=8000"
}

JSON object order matters for up: commands run in the order they appear.

Installation and startup

If the project contains composer.json, PHPSandbox installs its Composer dependencies. JavaScript dependencies are installed when a supported lock file or packageManager identifies the package manager.

Use up for finite setup commands such as generating an application key or running migrations. A failing command fails setup, so keep these commands non-interactive and safe to repeat.

Use startCmd for the primary application process. Bind HTTP servers to 0.0.0.0, not only 127.0.0.1, so preview routing can reach them.

Tasks and services

tasks defines long-running project processes. A task can be a command string, a list of commands, or an object with command and enabled. PHPSandbox supervises enabled tasks and exposes their status and logs through the Workspace and SDK.

services enables supporting services. Redis is built in; MySQL, MinIO, and Docker may be available depending on the sandbox and account. Only enable a service the application actually needs.

Environment values

Values under env are available to setup commands and are merged into the project's .env. Do not commit credentials here. Store sensitive values as sandbox secrets or enter them through the Workspace environment controls.

PHPSandbox sets the application URL for the active runtime, so code should not assume a permanent preview hostname.

Preview ports

Each ports entry maps a listening localPort to an externalPort used by preview routing. Mark the product's main web port as primary so it becomes the default preview.

The SDK can inspect and update the same configuration through sandbox.config. Those updates are written to .phpsandbox/setup.json; review the file before committing automated changes.

Validate the file

Malformed JSON stops provisioning with an invalid .phpsandbox/setup.json error. After changing setup:

1. Create, import, or restart the sandbox.
2. Confirm dependency installation and every up command succeeds.
3. Check task and service status.
4. Open the primary preview and exercise the application.