# STP Ecommerce — Setup Guide

## Prerequisites
- PHP 8.2+ with extensions: mbstring, pdo_mysql, xml, curl, gd, zip, intl
- Composer 2.x
- Node.js 20+ and npm
- MySQL 8.0+ (or MariaDB 10.6+)

---

## Step 1 — Install PHP Dependencies

```bash
cd /path/to/STP-ecommerce
composer install
```

---

## Step 2 — Configure Environment

```bash
cp .env.example .env
php artisan key:generate
```

Then edit `.env` and set at minimum:

```env
APP_URL=http://localhost:8000

DB_HOST=127.0.0.1
DB_DATABASE=stp_ecommerce
DB_USERNAME=root
DB_PASSWORD=your_password
```

---

## Step 3 — Create the Database

```sql
CREATE DATABASE stp_ecommerce CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

---

## Step 4 — Run Migrations & Seed

```bash
php artisan migrate
php artisan db:seed
```

This creates the tables and seeds: admin user, default vendor, sample categories, and sample products.

---

## Step 5 — Storage Link

```bash
php artisan storage:link
```

---

## Step 6 — Install Frontend Dependencies

```bash
npm install
npm run dev        # for development (with hot reload)
# OR
npm run build      # for production
```

---

## Step 7 — Start the Application

```bash
php artisan serve
```

Visit: **http://localhost:8000**

---

## Step 8 — Start the Queue Worker (for emails, SMS, notifications)

```bash
php artisan queue:work --queue=default,notifications,emails
```

For production, use Supervisor to keep this running.

---

## Default Credentials (after seeding)

| Role   | Email                   | Password  |
|--------|-------------------------|-----------|
| Admin  | admin@stp.com           | password  |
| Vendor | vendor@stp.com          | password  |
| Customer | customer@stp.com     | password  |

---

## Payment Gateway Setup

Fill in the gateway credentials in `.env` for each gateway you want to enable:

- **eSewa** — Sandbox: merchant code `EPAYTEST`, secret `8gBm/:&EnhH.1/q`
- **Khalti** — Get test keys from dashboard.khalti.com
- **Razorpay** — Get test keys from dashboard.razorpay.com
- **Stripe** — Get test keys from dashboard.stripe.com
- **PayPal** — Get sandbox credentials from developer.paypal.com

---

## Filament Admin Panel

Access at: **http://localhost:8000/admin**

Login with the admin credentials above.

---

## Shared Hosting (cPanel) Deployment

### Step 0 — build the upload zips (on your own Mac, in Terminal)

You don't need a cPanel terminal for this — your Mac's own Terminal.app
does it, at full disk speed, with no size limits. This project is ~730MB
including a large product-image library (`storage/app/public`, ~470MB),
so it's split into two zips: a small one with the actual app (upload and
extract this first — the site works once this is in place, just with
placeholder/broken product images), and a large one with just the images
(upload whenever's convenient — FTP handles it better than a browser
upload).

```bash
cd ~/Documents/Claude/STP-ecommerce

# 1. The app itself — code + vendor/, no images, no local-only files.
#    Expect roughly 60-90MB.
zip -r -y ~/Desktop/stp-ecommerce-cpanel-app.zip . \
  -x '.env' '.DS_Store' '*/.DS_Store' '_to_delete/*' '_to_delete' \
     'public/storage' 'storage/app/public/*' 'storage/logs/*'

# 2. Product images only — expect roughly 450-470MB (JPEGs don't
#    compress further, so this one stays close to its real size).
zip -r ~/Desktop/stp-ecommerce-product-images.zip storage/app/public
```

Both zips preserve the same folder structure relative to the project
root, so on the server you extract them into the *same* destination
folder and the files land in the right place either way.

If your host's cPanel File Manager rejects the images zip for being too
large (many hosts cap browser uploads well below its size even when your
disk quota is fine with it), use an FTP client (FileZilla, Cyberduck) for
that one instead — FTP has no such cap and resumes on interruption.

### Option A — guided installer (recommended, no terminal needed)

1. In cPanel → **MultiPHP Manager**, set this domain to **PHP 8.2, 8.3, or
   8.4** — this project's `composer.json` requires `^8.2`, so anything in
   that range works (8.4 has been specifically checked against this
   codebase and is fine). Then in **MultiPHP INI Editor** / PHP Extensions
   for the same domain, confirm `gd`, `intl`, `mbstring`, `pdo_mysql`,
   `curl`, `xml`, `zip`, `fileinfo` are all enabled — some hosts ship a few
   of these off by default.
2. In **File Manager**, navigate to where you want the app to live (e.g.
   your home directory, or `public_html` if this domain's document root
   will point straight at it — see step 3 below either way), click
   **Upload**, and upload `stp-ecommerce-cpanel-app.zip` from Step 0.
3. Once uploaded, select it in File Manager and click **Extract** — this
   unzips everything in place without needing a terminal.
4. Point this domain's document root at the extracted folder's `public/`
   subfolder (cPanel → **Domains**, edit the document root) rather than at
   the project root — that's what keeps `.env`, `app/`, `vendor/`, etc. from
   being reachable over HTTP.
5. Visit `https://yourdomain.com/install.php` (adjust the URL to wherever
   you extracted it, if the document root doesn't put it right at the
   domain root) and follow the wizard: it checks PHP version/extensions,
   takes your MySQL credentials, writes `.env`, runs `composer install`
   (harmless no-op here since `vendor/` is already in the zip), migrations,
   seeders, `storage:link`, and the production caches, and finishes with
   the two cron commands to add (see below). It ends with a **"Delete
   install.php now"** button — use it; leaving that file live lets anyone
   who finds the URL re-run setup against your database.
6. Whenever you're ready, upload and extract `stp-ecommerce-product-images.zip`
   the same way, into the same project folder — its contents land at
   `storage/app/public` automatically. Nothing else to run; the symlink
   from step 5 already points there.

The installer runs everything through PHP's `exec()`. If your host has that
disabled (a fairly common shared-hosting security policy — the installer's
Requirements page will tell you), fall back to Option B — but Option B
assumes SSH access, which you may not have either; in that case ask your
host to enable `exec()` for this domain, since there's no way to run
Composer/Artisan commands on shared hosting without either one.

### Option B — manual, via SSH

1. Upload all files to a folder on the server, e.g. `~/stp-ecommerce/`.
2. Point the domain's document root at `~/stp-ecommerce/public`, not at
   `stp-ecommerce/` itself. On cPanel this is normally a field in
   **Domains** (or **Addon Domains**/**Subdomains**) where you set the
   document root directly — no symlink needed. If your host doesn't let you
   set a custom document root, the fallback is to symlink or copy
   `public/`'s contents into `public_html/` and adjust the `index.php`
   paths inside it to point at the project root one level up — but a real
   document-root change is safer, since it's the only way nothing outside
   `public/` (`.env`, `app/`, `vendor/`) is reachable over HTTP.
3. `composer install --no-dev --optimize-autoloader --no-interaction`
4. Copy `.env.example` to `.env`, fill in `DB_*`, `APP_URL`, `MAIL_*`, and
   set `APP_ENV=production`, `APP_DEBUG=false`.
5. `php artisan key:generate --force`
6. `php artisan migrate --force`
7. `php artisan storage:link --force`
8. `php artisan config:cache && php artisan route:cache && php artisan view:cache`
9. `chmod -R 775 storage bootstrap/cache`
10. The frontend assets (`public/build/`) are already compiled and checked
    into this repo — you don't need Node on the server. Only re-run
    `npm run build` locally and re-upload `public/build/` if you've changed
    anything under `resources/css` or `resources/js`.

### Cron jobs (both required, add via cPanel → Cron Jobs)

```
* * * * * php /home/youruser/stp-ecommerce/artisan schedule:run >> /dev/null 2>&1
* * * * * php /home/youruser/stp-ecommerce/artisan queue:work --stop-when-empty --max-time=50 >> /dev/null 2>&1
```

The first drives everything in `routes/console.php` — scheduled product
publishing, abandoned-cart recovery, loyalty-point expiry, vendor payouts,
prescription expiry. The second is not optional: `QUEUE_CONNECTION=database`
means order/prescription emails and SMS just sit in the `jobs` table until
something processes them, and shared hosting has no Supervisor to keep a
long-running `queue:work` process alive — a minute-by-minute
`--stop-when-empty` cron is the standard workaround. Skipping it means no
transactional email or SMS ever actually sends, even though everything
*looks* configured correctly in Settings.

### After deploy

- Confirm SSL is on (cPanel AutoSSL / Let's Encrypt) and `APP_URL` in `.env`
  uses `https://`.
- If you hit `Allowed memory size exhausted` on any bulk `artisan` command
  (product import/backfill, large migrations), raise `memory_limit` in
  cPanel → **MultiPHP INI Editor** for this domain — the default 128M is
  tight for this app's catalog-import commands.
- Delete `install.php` (via its own button, or manually) if you used
  Option A.

---

## Quick Troubleshooting

| Problem | Fix |
|---------|-----|
| `Class not found` errors | Run `composer dump-autoload` |
| Blank page / 500 error | Check `storage/logs/laravel.log` |
| Assets not loading | Run `npm run dev` or `npm run build` |
| Emails not sending | Start queue: `php artisan queue:work` |
| Permission denied on storage | `chmod -R 775 storage bootstrap/cache` |