# 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

```json
{
  "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.