# Local development

The developer machine is where WEBX Travel is **built and tested**. Production
(cPanel) only receives the result — see
[shared-hosting-cpanel.md](shared-hosting-cpanel.md).

## Toolchain

A portable toolchain lives next to the project in `../_devtools/` so it does not
collide with any existing XAMPP/WAMP install:

| Tool | Version | Notes |
|---|---|---|
| PHP | 8.3.x (portable) | Laravel 12 needs 8.2+. Production runs 8.4. |
| Composer | 2.x (`composer.phar`) | Always run through PHP 8.3. |
| Node.js | 24 LTS (portable) | Only needed to **build** the frontend. |

**Activate a shell with the tools on PATH:**

- Windows CMD: double-click `..\_devtools\activate.bat`
- PowerShell: `. ..\_devtools\activate.ps1`

After activation, `php`, `node`, `npm` and `composer` are available and
`composer` runs on PHP 8.3.

> If you set up a fresh machine, install a portable PHP 8.3 (non-thread-safe
> x64) and Node 24 into `_devtools/`, enable the `openssl, curl, mbstring,
> pdo_mysql, fileinfo, gd, intl, sodium, pdo_sqlite` extensions in
> `_devtools/php83/php.ini`, and drop the latest `composer.phar` alongside.

## First-time setup

```bash
# from the project root, with the toolchain activated
composer install
copy .env.example .env      # then edit it (see below)
php artisan key:generate
npm install
```

### `.env` for local dev

Local dev uses SQLite so **no MySQL server is required**:

```env
APP_NAME="WEBX Travel"
DB_CONNECTION=central
CENTRAL_DB_DRIVER=sqlite
CENTRAL_DB_DATABASE="C:/…/webxtravel/database/central.sqlite"
TENANT_DB_DRIVER=sqlite
TENANCY_CENTRAL_DOMAINS=localhost,127.0.0.1
TENANCY_SUBDOMAIN_BASE=webxtravel.test
TENANCY_MANAGE_DATABASE=true
```

## Build the central schema and a couple of tenants

```bash
# SQLite needs the central file to exist first:
php -r "file_exists('database/central.sqlite') || touch('database/central.sqlite');"

php artisan core:migrate --force
php artisan tenant:provision "Amaka Tours"  --domain=amaka.webxtravel.test --driver=sqlite --force
php artisan tenant:provision "Globe Travel" --domain=globe.webxtravel.test --driver=sqlite --force
php artisan tenants:list
```

Each tenant gets its own SQLite database under `storage/tenant-databases/`,
named from its technical id (not its commercial name).

## Run it

```bash
php artisan serve          # backend at http://127.0.0.1:8000
npm run dev                # Vite dev server (hot reload) in another shell
```

To hit a tenant locally, map its host to `127.0.0.1` in your `hosts` file, e.g.
`127.0.0.1  amaka.webxtravel.test`, then browse the API at
`http://amaka.webxtravel.test:8000/api/v1/tenant`.

## Quality gates (run before every deploy)

```bash
php artisan test           # backend suite (isolation, security, migrations)
npm run type-check         # vue-tsc, no emit
npm run build              # compiles resources → public/build
```

All three must pass. `php artisan test` uses isolated SQLite databases and never
touches your dev data.
