# MTEngine v1.0.1

**MTEngine** is a powerful PHP e-commerce engine built for the Algerian and Arab markets. It provides a full storefront, admin dashboard, AI-powered landing pages, multi-carrier shipping integrations, and a flexible plugin system — all in a single self-hosted package.

---

## Table of Contents

1. [Requirements](#requirements)
2. [Quick Installation](#quick-installation)
3. [Directory Structure](#directory-structure)
4. [Configuration](#configuration)
5. [Features](#features)
6. [Shipping Integrations](#shipping-integrations)
7. [Plugin System](#plugin-system)
8. [Theme System](#theme-system)
9. [Security](#security)
10. [Upgrade Guide](#upgrade-guide)
11. [Troubleshooting](#troubleshooting)
12. [License](#license)

---

## Requirements

| Requirement | Minimum | Recommended |
|---|---|---|
| PHP | 8.1 | 8.2+ |
| MySQL / MariaDB | 5.7 / 10.3 | 8.0 / 10.6 |
| Apache | 2.4 | 2.4 |
| mod_rewrite | required | required |
| cURL extension | required | required |
| PDO + pdo_mysql | required | required |
| mbstring extension | required | required |

> **Shared hosting** is fully supported (cPanel / LiteSpeed / Apache).

---

## Quick Installation

### Step 1 — Upload files
Upload the package to your web root (e.g. `public_html/`) via FTP or file manager.

### Step 2 — Create database
Create a new MySQL database and user in your hosting control panel (cPanel → MySQL Databases).
> **Note:** The installer will attempt to create the database automatically if your user has the `CREATE` privilege. On most shared hosting plans the database must be created manually first — this is normal and expected.

### Step 3 — Run installer
Navigate to `https://yourdomain.com/install/` and follow the on-screen steps:
1. Language selection
2. System requirements check
3. Database connection — the installer writes your `.env` file automatically
4. SQL import
5. Admin account creation
6. License activation

> You do **not** need to edit `.env` manually. The installer handles this for you.
> If you need to reconfigure later, you can edit `.env` directly or re-run the installer after removing `storage/installed.lock`.

### Step 4 — Installer auto-locks
After completion, `storage/installed.lock` is created and the installer is blocked automatically.
Set `APP_URL` in your `.env` to your actual domain once the site is live:
```
APP_URL=https://yourdomain.com
```

---

## Directory Structure

```
mtengine/
├── admin/                  Admin panel templates and assets
├── core/
│   ├── app/
│   │   ├── Controllers/    Application controllers
│   │   ├── Models/         Database models
│   │   ├── Services/       Business logic services
│   │   └── Integrations/   Shipping provider API clients
│   └── system/             Framework core (Router, SeoManager, etc.)
├── install/                Installer wizard + upgrade SQL files
├── lang/                   Translations (en.json, ar.json)
├── plugins/                Optional plugins
├── public/                 robots.php, sitemap.php, static assets
├── storage/                Runtime storage (not web-accessible)
├── themes/matjari/         Default storefront theme
├── uploads/                User-uploaded files
├── .env                    Environment config
└── index.php               Application entry point
```

---

## Configuration

| .env Key | Description | Example |
|---|---|---|
| `DB_HOST` | Database host | `localhost` |
| `DB_NAME` | Database name | `myshop` |
| `DB_USER` | Database user | `myshop_user` |
| `DB_PASS` | Database password | `s3cr3t` |
| `APP_DEBUG` | Show errors — set false in production | `false` |
| `APP_URL` | Site URL, no trailing slash | `https://myshop.dz` |

All other settings are managed from **Admin → Settings**.

---

## Features

- Product management with EditorJS descriptions, galleries, variants, stock, discounts
- AI-powered landing page builder (Gemini API)
- Full order lifecycle with team assignments and call tracking
- Multi-carrier shipping: Yalidine, ZR Express, Maystro, DHD, Ecotrack
- SEO toolkit: meta, Open Graph, schema.org, XML sitemap, robots.txt
- GTM, GA4, Facebook Pixel, TikTok Pixel integrations
- WhatsApp order notifications
- Google Sheets order export
- Full Arabic/English UI with RTL support
- Plugin and theme systems
- Database backup from admin panel

---

## Shipping Integrations

| Provider | Home | Desk | Pickup | Tracking |
|---|---|---|---|---|
| Yalidine | Yes | Yes | No | Yes |
| ZR Express | Yes | Yes | No | Yes |
| Maystro | Yes | Yes | Yes | Yes |
| DHD | Yes | Yes | No | Yes |
| Ecotrack | Yes | No | No | Yes |

Configure under **Admin → Settings → Shipping**.

---

## Security

- CSRF token on all POST requests (including admin state-change actions)
- PDO prepared statements used for all user-supplied data; integer values cast before use in dynamic query fragments
- Upload directory PHP execution blocked via `.htaccess`
- HTML sanitizer on all user-supplied HTML output
- Security headers: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`
- Direct access to `.env`, `settings.json`, and sensitive files blocked via `.htaccess`
- Directory listing disabled (`Options -Indexes`)
- `storage/` directory fully blocked from direct HTTP access
- Session fingerprinting on admin panel (IP + User-Agent binding)
- Role-based access control on all admin routes
- ZIP path traversal protection on plugin uploads and update packages

---

## Upgrade Guide

See **UPGRADE.md** for full instructions.

**v1.0.0 → v1.0.1 quick steps:**
1. Back up database and files
2. Run `install/upgrade_v1.0.0_to_v1.0.1.sql`
3. Replace all files except `.env`, `storage/`, `uploads/`, `settings.json`
4. Clear OPcache if enabled

---

## Troubleshooting

**Blank white page** — Set `APP_DEBUG=true` temporarily in `.env` to see the error.

**500 error** — Check Apache/PHP error log. Ensure `storage/` and `uploads/` are writable.

**Images not uploading** — Check `uploads/` permissions (755 or 775). Ensure GD extension is enabled.

**Installer shows again** — Verify `storage/installed.lock` exists.

**Shipping prices not loading** — Check API credentials under Admin → Settings → Shipping.

---

## License

Licensed software. One license key per domain. Unauthorized redistribution is prohibited.
