# Laravel Herd Setup Instructions

This project uses **Laravel Herd** for local development on Windows.

> **No MySQL required.** The migrations are written for **SQLite**, which is the
> default in `.env.example`. Earlier revisions of this guide told you to install
> MySQL and set `DB_CONNECTION=mysql` — that is no longer correct and will
> leave you with an empty database. Follow the steps below instead.

## Prerequisites

1. **Laravel Herd for Windows** — https://herd.laravel.com/
   - Bundles PHP 8.3 and Composer
   - Automatic local SSL certificates
   - Simple site management

2. **Git** (optional, only if you want version control) — https://git-scm.com/download/win/

Nothing else. No MySQL, no XAMPP, no Node.js.

## Installation Steps

### 1. Install Laravel Herd

1. Download and run the installer.
2. Follow the wizard — Herd installs PHP and Composer automatically.
3. Herd runs in the system tray once installed.

### 2. Install the project dependencies

Open a terminal in the project directory (`D:\school`):

```bash
composer install
```

### 3. Create the environment file

```bash
copy .env.example .env
```

The defaults in `.env.example` are correct for local use. Two keys matter:

```env
DB_CONNECTION=sqlite
# DB_DATABASE stays unset -> defaults to database/database.sqlite
SESSION_DRIVER=database
```

Do **not** set `DB_DATABASE=` to an empty value. An empty string overrides
Laravel's fallback and the app fails with
`SQLSTATE[HY000] [14] unable to open database file`.

`SESSION_DRIVER` must stay `database`: the app invalidates sessions by deleting
rows from the `sessions` table when an account is deactivated or a password
changes. With the `file` driver those deletions do nothing.

### 4. Generate the application key

```bash
php artisan key:generate
```

### 5. Create the SQLite file

```bash
type nul > database\database.sqlite
```

### 6. Migrate and seed

```bash
php artisan migrate --seed
```

This creates a demo school (Achimota Academy) with classes, subjects, staff,
students, invoices, payments, marks and timetable entries. Demo logins are
listed in the README.

### 7. Point Herd at the project

1. Open Herd from the system tray → **Sites**.
2. Add the directory `D:\school`.
3. Herd creates the local domain `school.test`.

## Accessing the Application

- **Application**: https://school.test (or http://127.0.0.1:8000 via `php artisan serve`)
- **Database**: the single file `database\database.sqlite`

## Common Commands

```bash
php artisan serve                    # dev server on :8000
php artisan migrate:fresh --seed      # reset to pristine demo data
php artisan test                      # run the Pest suite
vendor\bin\pint                       # code style
php artisan route:list                # all routes
```

To inspect or edit the database, any SQLite browser works — DB Browser for
SQLite (https://sqlitebrowser.org/) or the `sqlite3` CLI. You do **not** need
MySQL Workbench or phpMyAdmin.

## Troubleshooting

### "Database file at path [] does not exist" / "unable to open database file"

`DB_DATABASE` is set to an empty value in `.env`. Comment the line out so
Laravel falls back to `database/database.sqlite`.

### Site loads but every page redirects to /login

The `sessions` table is missing. Run `php artisan migrate`. The session driver
is `database`, so that table must exist.

### Herd is not showing the site

1. Confirm the directory added is `D:\school` (not a subfolder).
2. Restart Herd from the system tray.
3. Check PHP is on PATH: `php --version`.

### Deactivated users can still log in

Confirm `SESSION_DRIVER=database` in `.env`. With `file` sessions, account
deactivation cannot revoke existing sessions.

## Node.js

Not needed. The project ships plain Blade templates with a hand-written
stylesheet in `public/assets/css/app.css` and no Vite build step, so `npm
install` / `npm run dev` do nothing. Node is only worth installing if you
intend to add a frontend build.

## Production Deployment

Do not follow the generic advice at the end of the old version of this file.
See **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)** for the real cPanel/Plesk
procedure, including the document-root, permissions and hardening steps.