# Installation Guide

## Requirements

- PHP 8.0 or newer, with the `pdo_mysql` extension (enabled by default in XAMPP)
- MySQL 8+ or MariaDB 10.4+
- A web server: Apache (with `mod_rewrite`) or PHP's built-in server for quick
  testing/LAN use

## 1. XAMPP (Windows/Mac/Linux) — local or LAN use

1. Install [XAMPP](https://www.apachefriends.org/) and start **Apache** and
   **MySQL** from the control panel.
2. Copy the `garage-management-system` folder into `C:\xampp\htdocs\`
   (or `/opt/lampp/htdocs/` on Linux).
3. Create the database:
   - Open `http://localhost/phpmyadmin`, or run from a terminal:
     ```
     "C:\xampp\mysql\bin\mysql.exe" -u root < database\database.sql
     ```
     (Use `database\demo_data.sql` instead if you want the system pre-loaded
     with realistic sample data to explore — it includes everything
     `database.sql` does, plus sample customers, vehicles, work orders, an
     insurance claim, inventory, and invoices.)
4. Copy `config/config.php` and edit the `database` section with your
   credentials (defaults to `root` / no password, matching a fresh XAMPP
   install):
   ```php
   'database' => [
       'host'     => '127.0.0.1',
       'database' => 'garage_management',
       'username' => 'root',
       'password' => '',
   ],
   ```
   Also set `app.base_path` if the project isn't at your web server's root, e.g.
   `'base_path' => '/garage-management-system/public'`.
5. Generate a random `app.key` value in `config.php` (any 32+ character random
   string — used as a general secret; not currently used for encryption, but set
   it anyway for forward-compatibility).
6. Point your browser to `http://localhost/garage-management-system/public/`
   (adjust the path to match where you copied the folder and your `base_path`
   setting).
7. Log in with the seeded administrator account:
   - **Email:** `admin@garage.local`
   - **Password:** `Admin@12345`
   - **Change this password immediately** from Profile → Change Password.
8. Go to **Branding & Settings** and set your real garage name, contact info,
   logo, and brand colors — they apply instantly across the whole app and every
   printed document.

### Clean URLs (Apache)

The included `public/.htaccess` already routes everything through
`public/index.php` with clean URLs (no `.php` in any URL). Make sure
`AllowOverride All` is set for the `htdocs` directory in your Apache config so
`.htaccess` is respected (XAMPP's default `httpd-xampp.conf` already allows
this for `htdocs`).

## 2. cPanel / Shared Hosting

1. Upload the whole project (everything, not just `public/`) to a directory
   **outside** `public_html`, e.g. `/home/youruser/garage-management-system/`.
2. In cPanel → **Domains**, set the document root for your domain/subdomain to
   `garage-management-system/public` (this keeps `app/`, `config/`, `storage/`,
   and `database/` outside the web-accessible root — important for security,
   since `storage/uploads` contains files that must only be served through the
   app's own permission-checked route).
   - If your host doesn't let you set a custom document root, instead symlink
     or copy just the *contents* of `public/` into `public_html`, and adjust
     `config.php`'s `require` paths in `public/index.php` accordingly (or ask
     your host to enable custom document roots — most do).
3. Create a MySQL database and user via cPanel → **MySQL Databases**, and note
   the credentials (cPanel-created DB names/users are usually prefixed with
   your account name).
4. Import `database/database.sql` (or `demo_data.sql`) via cPanel →
   **phpMyAdmin** → Import.
5. Edit `config/config.php` with your cPanel database credentials and set
   `app.url` to your real domain.
6. Ensure `storage/uploads/*` and `public/uploads/branding` are writable
   (usually `755`; cPanel file manager → Permissions).
7. Visit your domain and log in with the seeded admin account (see step 7
   above), then change the password immediately.

## 3. Local Network (LAN) — no internet required

The app has zero external dependencies (no CDN scripts/fonts, no API calls to
third-party services), so once installed it works entirely offline on a local
network:

1. Install and configure as in the XAMPP steps above, but run Apache/MySQL on
   a machine that stays on and is reachable on your LAN (e.g. `192.168.1.50`).
2. Set `app.url` in `config.php` to that machine's LAN address, e.g.
   `http://192.168.1.50/garage-management-system/public`.
3. Other computers/phones on the same network open that URL in any browser —
   no app install needed, and the UI is responsive down to mobile width.
4. Password reset normally requires email; since a LAN install has no mail
   server, the **forgot password** flow instead displays the reset link
   directly on screen for a staff member to relay to the user (or use it
   themselves if resetting their own account) — this is intentional, not a
   missing feature.

## 4. Quick local testing (no Apache) — for developers

PHP's built-in server works fine for trying the app out without configuring
Apache:

```bash
php -S 127.0.0.1:8000 -t public public/router.php
```

Then open `http://127.0.0.1:8000`. `public/router.php` makes the built-in
server behave like the `.htaccess` rules (serving real files directly,
routing everything else through `index.php`).

## 5. Post-Install Checklist

- [ ] Changed the default admin password
- [ ] Set real garage name, address, phone, email, tax number in Settings →
      General
- [ ] Uploaded your real logo and set brand colors in Settings → Branding
- [ ] Reviewed Roles & Permissions and adjusted them to match your team
- [ ] Created accounts for your actual staff (Users → New User) instead of
      sharing the admin login
- [ ] Set up a MySQL backup routine (see below)

## 6. Backups

The entire system's state lives in the MySQL database plus the
`storage/uploads/` and `public/uploads/branding/` directories (uploaded
photos/documents/logos). Back up both:

```bash
# Database
mysqldump -u root -p garage_management > backup_$(date +%Y%m%d).sql

# Uploaded files
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz storage/uploads public/uploads
```

Restore by importing the SQL dump into a fresh database and extracting the
uploads archive back into place.

## Troubleshooting

- **"Database connection failed"** — check `config/config.php` credentials and
  that MySQL is running.
- **404 on every page except the homepage** — Apache's `mod_rewrite` isn't
  enabled, or `AllowOverride All` isn't set for the directory; check
  `public/.htaccess` is present and being read.
- **Blank page / 500 error** — set `'debug' => true` in `config.php` temporarily
  to see the real PHP error, then revert it for production use.
- **Uploaded logo/photo doesn't show** — check `storage/uploads/*` and
  `public/uploads/branding` are writable by the web server user.