![Logo](/images/logo.png)

[📄 CHANGELOG.md](CHANGELOG.md) · [📄 INSTALL.md](INSTALL.md) · [📄 ROADMAP.md](ROADMAP.md)

# Twitch PHP Bot 🇩🇰

En letvægts **Twitch Chat Bot** skrevet i **PHP**, der kører direkte på en webserver som **XAMPP** eller **Apache**, uden Node.js eller eksterne services.  
Webinterface til styring af kommandoer, timers, polls, giveaways, loyalty points og brugere.

---

## ✨ Funktioner

- Twitch IRC chat-bot (PHP socket)
- Dashboard med login og rettigheder
- Kommandoer med placeholders (`@$user`, `@$target`, `{uptime}`, `!points`, …)
- Live log (SSE + WebSocket fallback)
- Timers, Polls, Giveaways
- Loyalty points + Bets, Slots, Raffle
- Helix API-integration (subs, mods, VIPs, cheerers, uptime, osv.)
- Rettighedsstyring (Admin / Mod / User)
- SQLite database – ingen ekstern DB
- Dansk/Engelsk dokumentation

---

## ⚙️ Krav

- PHP **8.1+**
- Extensions: `pdo_sqlite`, `curl`, `mbstring`, `json`
- Webserver (XAMPP, Apache, Nginx …)
- Twitch OAuth-token: [https://twitchapps.com/tmi/](https://twitchapps.com/tmi/)
- (Valgfrit) Node.js + `ws` for WebSocket live-log

---

## 🚀 Installation

Se [INSTALL.md](INSTALL.md) for komplette trin.

---

## 🔐 Login

Efter første installation:
- Brugernavn: `admin`
- Adgangskode: `demo`  
(kan ændres under **Indstillinger**)

---

## 📁 Struktur

```
/bot
├── /data
│   ├── app.db
│   ├── bot.log
│   └── settings.json
├── /web
├── bot.php          # PHP-socket bot
├── ws_server.js     # WebSocket server
├── .env             # Twitch credentials
```

---

### `/web` Mappestruktur

| Fil | Beskrivelse |
|------|--------------|
| **api.php** | Helix/Twitch API-helper (HTTP/2, cache, retry). Påkrævet. |
| **bets.php** | UI til Bets (points-betting): åbne/lukke bets, se indsatser, resolve vindere. Valgfri. |
| **commands.php** | UI til chat-kommandoer (opret/redigér/slet). Understøtter placeholders og rettigheder. Nødvendig for brugerdefinerede kommandoer. |
| **control.php** | Start/Stop/Restart botten fra web-UI. Nødvendig hvis du styrer botten fra web. |
| **create_admin.php** | Engangs-script til at oprette første admin (standard: admin/lan2025). Slet efter opsætning. |
| **db.php** | DB-helper til SQLite (WAL, busy_timeout). Nødvendig. |
| **events.php** | SSE-endpoint til live-loggen. Valgfri, giver realtid. |
| **eventsub_setup.php** | Registrerer EventSub-abonnementer (subs, bits, osv.). Valgfri, krævet for live-statistik. |
| **eventsub.php** | EventSub webhook-endpoint. Påkrævet hvis du bruger EventSub. |
| **guard.php** | Session/login-tjek. Nødvendig. |
| **help.php** | Hjælpeside med placeholders (`@$user`, `{uptime}`, `{random(1,100)}`). Valgfri. |
| **index.php** | Dashboard (Uptime, bits/subs, live-log, genveje). Nødvendig. |
| **log.php** | Viser bot.log med paging. Valgfri men nyttig. |
| **login.php** | Login-formular. Nødvendig. |
| **logout.php** | Rydder session. Nødvendig. |
| **migrate_users.php** | Engangs-migration (sikrer kolonner). Slet efter opsætning. |
| **permissions.php** | UI til rettigheder (Admin/Mod/User/Sub/VIP). Valgfri men anbefalet. |
| **points.php** | UI til Loyalty Points (!points). Valgfri, krævet for bets/slots/raffle. |
| **poll.php** | UI til Polls. Valgfri. |
| **raffle.php** | UI til Raffle (!buy X). Valgfri (kræver points). |
| **send.php** | Simpel “send test-besked til chatten”. Valgfri men nyttig. |
| **settings.php** | Indstillinger: watchdog, timeout, brugerstyring. Nødvendig for admin. |
| **slots.php** | Slot-spil (!spin). Valgfri (kræver points). |
| **style.css** | Dark theme. Nødvendig. |
| **timers.php** | UI til timers (auto-beskeder). Valgfri. |
| **validate.php** | Checker OAuth-tokenets gyldighed og scopes. Valgfri. |

---

### 🧭 Hurtig oversigt

**Første opsætning**
- Kør `migrate_users.php`
- Kør `create_admin.php` → log ind → slet begge scripts  
- Konfigurer i `settings.php`  
- *(Valgfrit)* `eventsub_setup.php` (kræver offentlig URL + `EVENTSUB_SECRET` i `.env`)

**Daglig brug**
- `index.php`: Dashboard + live-log  
- `commands.php`: Vedligehold kommandoer  
- `permissions.php`: Rettigheder  
- Moduler: `timers.php`, `poll.php`, `giveaway.php`, `points.php`, `bets.php`, `raffle.php`, `slots.php`  
- `log.php`, `validate.php`: Fejlsøgning

**Slet efter opsætning**
- `migrate_users.php`, `create_admin.php`

**Valgfri moduler**
- `bets.php`, `poll.php`, `raffle.php`, `slots.php`, `points.php`, `help.php`, `send.php`, `log.php`, `eventsub_setup.php`  
*(Fjerner du en side, så fjern linket i `index.php`)*

---

## 📄 Filer

- [CHANGELOG.md](CHANGELOG.md) – versionshistorik  
- [ROADMAP.md](ROADMAP.md) – planlagte funktioner  
- [LICENSE](LICENSE) – MIT-licens

---

## 🧡 Credits

Udviklet af **Thomas / DjGulvBasS**  
Med hjælp fra **ChatGPT (OpenAI)**  
MIT License

---

# Twitch PHP Bot 🇬🇧

A lightweight **Twitch Chat Bot** written in **PHP**, running directly on a web server such as **XAMPP** or **Apache**, with **no Node.js** or external services required.  
Includes a full web interface to manage commands, timers, polls, giveaways, loyalty points, and user access.

---

## ✨ Features

- Twitch IRC chat bot (PHP socket)
- Dashboard with login and role-based access
- Command editor with placeholders (`@$user`, `@$target`, `{uptime}`, `!points`, …)
- Live log (SSE + WebSocket fallback)
- Timers, Polls, Giveaways
- Loyalty points + Bets, Slots, Raffle
- Helix API integration (subs, bits, mods, VIPs, cheerers, uptime, etc.)
- Role management (Admin / Mod / User)
- SQLite database – no external DB needed
- Danish/English documentation

---

## ⚙️ Requirements

- PHP **8.1+**
- Extensions: `pdo_sqlite`, `curl`, `mbstring`, `json`
- Web server (XAMPP, Apache, Nginx, etc.)
- Twitch OAuth token: [https://twitchapps.com/tmi/](https://twitchapps.com/tmi/)
- *(Optional)* Node.js + `ws` for WebSocket live log

---

## 🚀 Installation

See [INSTALL.md](INSTALL.md) for full step-by-step instructions.

---

## 🔐 Login

After first setup:
- **Username:** `admin`  
- **Password:** `demo`  
(can be changed under **Settings**)

---

## 📁 Structure

```
/bot
├── /data
│   ├── app.db
│   ├── bot.log
│   └── settings.json
├── /web
├── bot.php          # PHP socket bot
├── ws_server.js     # WebSocket server
├── .env             # Twitch credentials
```

---

### `/web` Folder Overview

| File | Description |
|------|--------------|
| **api.php** | Helix/Twitch API helper (HTTP/2, cache, retry). Required. |
| **bets.php** | UI for points betting (open/close bets, view wagers, resolve winners). Optional. |
| **commands.php** | Manage chat commands (create/edit/delete). Supports placeholders and roles. Required for custom commands. |
| **control.php** | Start/Stop/Restart bot from web UI. Required if controlling bot from web. |
| **create_admin.php** | One-time script to create initial admin (default: admin/lan2025). Delete after first setup. |
| **db.php** | SQLite helper (WAL mode, busy timeout). Required. |
| **events.php** | SSE endpoint for live log. Optional, improves real-time updates. |
| **eventsub_setup.php** | Registers EventSub subscriptions (subs, bits, etc.). Optional, needed for live stats. |
| **eventsub.php** | EventSub webhook endpoint. Required if using EventSub. |
| **guard.php** | Session/login check. Required. |
| **help.php** | Placeholder documentation (`@$user`, `{uptime}`, `{random(1,100)}`). Optional. |
| **index.php** | Dashboard (uptime, subs/bits, live log, shortcuts). Required. |
| **log.php** | View bot.log with pagination. Optional but useful. |
| **login.php** | Login form. Required. |
| **logout.php** | Logout script. Required. |
| **migrate_users.php** | One-time migration script (ensures DB columns). Delete after setup. |
| **permissions.php** | Manage command access per role (Admin/Mod/User/Sub/VIP). Optional but recommended. |
| **points.php** | Loyalty points UI (!points). Optional; required for bets/slots/raffle. |
| **poll.php** | Poll management UI. Optional. |
| **raffle.php** | Raffle module (!buy X). Optional; requires points. |
| **send.php** | Send test messages to chat. Optional but handy. |
| **settings.php** | Settings: watchdog, timeout, user management. Required for admin control. |
| **slots.php** | Slot machine game (!spin). Optional; requires points. |
| **style.css** | Dark theme styling. Required. |
| **timers.php** | Timed chat messages. Optional. |
| **validate.php** | Checks OAuth validity and scopes. Optional, useful for debugging. |

---

### 🧭 Quick “When to Use What”

**First-time setup**
- Run `migrate_users.php`
- Run `create_admin.php` → log in → delete both scripts  
- Configure in `settings.php`  
- *(Optional)* `eventsub_setup.php` (requires public URL + `EVENTSUB_SECRET` in `.env`)

**Daily use**
- `index.php`: Dashboard + live log  
- `commands.php`: Manage commands  
- `permissions.php`: Role access  
- Modules: `timers.php`, `poll.php`, `giveaway.php`, `points.php`, `bets.php`, `raffle.php`, `slots.php`  
- `log.php`, `validate.php`: Debugging

**Safe to delete after setup**
- `migrate_users.php`, `create_admin.php`

**Optional modules**
- `bets.php`, `poll.php`, `raffle.php`, `slots.php`, `points.php`, `help.php`, `send.php`, `log.php`, `eventsub_setup.php`  
*(If removed, also remove links in `index.php`)*

---

## 📄 Files

- [CHANGELOG.md](CHANGELOG.md) – version history  
- [ROADMAP.md](ROADMAP.md) – planned features  
- [LICENSE](LICENSE) – MIT License

---

## 🧡 Credits

Developed by **Thomas / DjGulvBasS**  
With help from **ChatGPT (OpenAI)**  
Licensed under **MIT**
