diff --git a/CHANGELOG.md b/CHANGELOG.md index eef8abb..91e5ad4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,3 +30,38 @@ Spore points, subs, bits osv. ### Known issues - WebSocket kræver Node.js manuelt start - Ingen grafisk editor for poll/giveaway endnu +``` + +--- + +#English +✅ Ready! + +You can now: +Create commands +Set up timers, polls, and giveaways +Track points, subs, bits, etc. + +🧾 CHANGELOG.md +``` +# Changelog + +## [0.0.1] – 2025-10-05 +### Added +- First complete version of **Twitch PHP Bot** +- Dashboard with login and role-based access +- Command editor with placeholders +- Live log (SSE + WebSocket fallback) +- Timer, Poll, and Giveaway modules +- Loyalty Points + Bets, Slots, Raffle +- Permission system: Admin, Mod, User +- Helix API integration (subs, mods, VIPs, cheerers) +- SQLite database with auto-migration +- Settings: Watchdog, timeout +- User management (Admin can create/edit/delete) +- Danish/English documentation + +### Known issues +- WebSocket requires manual Node.js startup +- No graphical editor for poll/giveaway yet +``` \ No newline at end of file diff --git a/INSTALL.md b/INSTALL.md index 415b7a3..506decc 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -56,3 +56,90 @@ node ws_server.js ``` Dashboardet skifter automatisk til WebSocket, hvis tilgængelig. +--- + +#English +Installation Guide – Twitch PHP Bot + +##1️⃣ Download + +Clone or download the ZIP from GitHub: +``` +git clone https://github.com//twitch-php-bot.git +``` + +Place it in your web server directory, for example: +``` +C:\xampp\htdocs\bot\ +``` +
+2️⃣ Requirements + +PHP 8.1+ + +Enabled extensions: +``` +pdo_sqlite +curl +mbstring +json +``` + +Check your php.ini file and make sure these are not commented out. + +3️⃣ Configuration + +Create a file named .env in the project root: + +.env +``` +TWITCH_CHANNEL=yourchannelname +TWITCH_OAUTH=oauth:xxxxxxxxxxxxxxxxxxxx +TWITCH_CLIENT_ID=your_client_id +TWITCH_CLIENT_SECRET=your_client_secret +``` + +Get your OAuth token here: https://twitchapps.com/tmi/ + +4️⃣ Database & Admin + +Open: +``` +http://localhost/bot/web/migrate_users.php +``` + +→ ensures correct table columns + +Then open: +``` +http://localhost/bot/web/create_admin.php +``` + +→ creates your admin user + +Login credentials: +``` +Username: admin +Password: demo +``` + + +5️⃣ Start the Bot + +Go to: +``` +http://localhost/bot/web/login.php +``` + +Log in and click Start +The bot runs in PHP behind the scenes and responds to chat commands. + +6️⃣ (Optional) Live Log via WebSocket + +Install Node.js, then run: +``` +npm install ws +node ws_server.js +``` + +The dashboard will automatically switch to WebSocket mode if available. \ No newline at end of file diff --git a/README.md b/README.md index e7c2845..68b24c3 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ [📄 CHANGELOG.md](CHANGELOG.md) · [📄 INSTALL.md](INSTALL.md) · [📄 ROADMAP.md](ROADMAP.md) -# Twitch PHP Bot 🇩🇰 / 🇬🇧 +# 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. --- -## ✨ Features +## ✨ Funktioner - Twitch IRC chat-bot (PHP socket) - Dashboard med login og rettigheder @@ -24,13 +24,13 @@ Webinterface til styring af kommandoer, timers, polls, giveaways, loyalty points --- -## ⚙️ Krav / Requirements +## ⚙️ 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 +- (Valgfrit) Node.js + `ws` for WebSocket live-log --- @@ -51,119 +51,77 @@ Efter første installation: ## 📁 Struktur -/bot
-├── /data
-│ ├── app.db
-│ ├── bot.log
-│ └── settings.json
-├── /web
-├── bot.php # PHP-socket bot
-├── ws_server.js # WebSocket server
-├── .env # Twitch credentials
- -### ``` -/web - -api.php -Helix/Twitch API-helper (HTTP/2, cache, retry). Bruges af dashboardsider til uptime, lister m.m. Nødvendig. - -bets.php -UI til Bets (points-betting): åbne/lukke bets, se indsatser, resolve vindere. Valgfri feature (kræver points). - -commands.php -UI til chat-kommandoer (opret/redigér/slet). Understøtter placeholders og rettigheder. Nødvendig hvis du vil have brugerdefinerede kommandoer. - -control.php -Start/Stop/Restart bot-processen fra web-UI. Læser/skrivet “stop.flag” og launcher botten. Nødvendig hvis du styrer botten fra web. - -create_admin.php -Engangs-script til at oprette første admin-bruger (admin/lan2025 som standard). Kun til første opsætning → slet bagefter. - -db.php -DB-helper til SQLite (WAL, busy_timeout). Bruges af alle sider der læser/skriver i DB. Nødvendig. - -events.php -Server-Sent Events (SSE) endpoint til live-loggen i dashboard. Frigiver session-lås. Valgfri, men giver smooth live-log uden reload. - -eventsub_setup.php -Lille side der registrerer EventSub-abonnementer (subs, bits, osv.) mod din offentlige callback-URL. Valgfri, men kræves for bits/subs-statistik på index. - -eventsub.php -EventSub webhook-endpoint. Modtager Twitch-events, validerer HMAC, skriver til events i DB. Nødvendig hvis du bruger EventSub. - -guard.php -Session/login-tjek (frigiver session-låsen med session_write_close()). Nødvendig. - -help.php -Hjælpeside med liste over placeholders (fx @$user, {uptime}, {random(1,100)}) og syntaks. Valgfri, men praktisk reference. - -index.php -Dashboard (Uptime, bits/subs denne stream, live-log, genveje til moduler). Nødvendig. - -log.php -Viser hele data/bot.log med lidt paging. Brugbar til fejlsøgning. Valgfri men anbefalet. - -login.php -Login-formular (brugernavn/password via users-tabellen). Nødvendig for adgangskontrol. - -logout.php -Rydder session og sender tilbage til login. Nødvendig. - -migrate_users.php Engangs-migration: sikrer kolonnerne password, password_hash, role findes i users. Kun til første opsætning → slet bagefter. - -permissions.php -UI til rettigheder for kommandoer/roller (Admin/Mod/User/VIP/Sub/Chatter). Valgfri, men anbefales hvis du vil styre hvem der må bruge hvad. - -points.php -UI til Loyalty Points (saldoer, transaktioner). Chat-kommando !points. Valgfri – kræves for Bets/Slots/Raffle. - -poll.php -UI til at oprette/afslutte polls (og vise status). Valgfri. - -raffle.php -UI til Raffle med points-billetter (!buy X). Valgfri (kræver points). - -send.php -Simpelt “send test-besked til chatten” fra web-UI (god til at teste chat:edit). Valgfri men nyttig. - -settings.php -Indstillinger: Watchdog on/off + timeout, Min profil (skift eget username/password), og Brugerstyring (Admin kan oprette/redigere/slette brugere, ændre roller, nulstille passwords). Nødvendig for administration. - -slots.php -Emote/slot-spil for points (!spin amount). Valgfri (kræver points). - -style.css -Dark theme for hele UI. Nødvendig for udseende (kan naturligvis tilpasses). - -timers.php -UI til automatiske chat-beskeder pr. tidsinterval. Valgfri. - -validate.php -Checker at OAuth-tokenet er gyldigt og hvilke scopes du har. Valgfri men god til fejlsøgning. - -### Hurtig “hvornår bruger jeg hvad?” - -Første gang -migrate_users.php -create_admin.php (log ind → slet begge scripts) - -settings.php: sæt watchdog/timeout, opret evt. flere brugere -eventsub_setup.php (hvis du vil have bits/subs) – kræver offentlig URL og EVENTSUB_SECRET i .env - -### Daglig brug -index.php: status + live log -commands.php: vedligehold kommandoer -permissions.php: hvem må bruge hvad -timers.php, poll.php, giveaway.php, points.php, bets.php, raffle.php, slots.php: relevante moduler -log.php / validate.php: fejlsøgning - -### Kan de slettes? -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 -(Men hvis du fjerner en side, så fjern også linket til den i index.php.) +/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 @@ -176,4 +134,140 @@ Valgfri moduler: bets.php, poll.php, raffle.php, slots.php, points.php, help.php Udviklet af **Thomas / DjGulvBasS** Med hjælp fra **ChatGPT (OpenAI)** -MIT Licenseol that runs directly on your Windows server alongside Mix It Up Bot. +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** diff --git a/ROADMAP.md b/ROADMAP.md index 03b036d..49144f0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -42,3 +42,51 @@ - \[ ] Export/import af kommandoer - \[ ] Backup/restore via zip - \[ ] API for eksterne systemer + +--- + +#English + +Roadmap – Twitch PHP Bot +##✅ Completed (v0.0.1) + - \[x] PHP socket-based Twitch bot + - \[x] Dashboard (index) + - \[x] Commands, timers, points + - \[x] Polls, giveaways, raffle, slots, bets + - \[x] SSE/WebSocket live log + - \[x] Helix API (subs, bits, mods, VIPs) + - \[x] Login + permissions (Admin, Mod, User) + - \[x] Settings + watchdog + - \[x] SQLite database + +##🚧 Upcoming Versions + + +##v0.1.1 – QoL + UI + - \[ ] Search and sorting for commands + - \[ ] Quick test button for commands + - \[ ] Improved placeholder documentation + - \[ ] Auto-start bot on login + +##v0.1.2 – Stats & Overlay + - \[ ] Display subs/follows/bits in overlay + - \[ ] Uptime graph and stream history + - \[ ] Points leaderboard + +##v0.1.3 – Integration + - \[ ] OBS WebSocket integration + - \[ ] Discord webhook for events + - \[ ] Mobile-friendly design + +##v2.0.0 – Multi-Channel Support + - \[ ] Run multiple channels from the same web interface + - \[ ] Separate databases and logs + +--- + + +🧠 Ideas + - \[ ] GUI editor for polls and giveaways + - \[ ] Export/import of commands + - \[ ] Backup/restore via ZIP + - \[ ] API for external systems \ No newline at end of file