From 15815e3a9d5e8853f67241d89fadcb2d9d000510 Mon Sep 17 00:00:00 2001 From: Kevin Feiler Date: Thu, 16 Oct 2025 01:12:56 +0200 Subject: [PATCH] first commit --- README.md | 316 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..7231a08 --- /dev/null +++ b/README.md @@ -0,0 +1,316 @@ +# TeaSpeak WHMCS Provisioning Module - Modernized Edition + +[![PHP Version](https://img.shields.io/badge/PHP-8.0%2B-blue.svg)](https://www.php.net/) +[![WHMCS Version](https://img.shields.io/badge/WHMCS-8.0%2B-green.svg)](https://www.whmcs.com/) +[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE) + +## ๐Ÿš€ What's New in This Version + +This is a **fully modernized** version of the TeaSpeak WHMCS module with the following improvements: + +### โœจ Major Updates + +- **PHP 8.x Compatible** - Full support for PHP 8.0, 8.1, 8.2, and 8.3 +- **WHMCS API 1.2** - Updated to the latest WHMCS module API +- **Modern PHP Features**: + - Strict types (`declare(strict_types=1)`) + - Type hints for all parameters and return types + - Modern array syntax (`[]` instead of `array()`) + - Arrow functions and null coalescing operators + - Improved error handling + +- **Bootstrap 5 Design** - Beautiful, responsive UI + - Modern card-based layout + - Font Awesome 6 icons + - Improved mobile responsiveness + - Better UX with hover effects and animations + +- **Code Quality**: + - PSR-12 coding standards + - Comprehensive documentation + - Better separation of concerns + - Improved security practices + - Removed hardcoded URLs and made them configurable + +### ๐Ÿ”ง Technical Improvements + +1. **Better Error Handling** + - More descriptive error messages + - Proper exception handling throughout + - Better logging for debugging + +2. **Security Enhancements** + - Input validation improved + - SQL injection protection (using Capsule ORM properly) + - XSS prevention in templates + - CSRF protection considerations + +3. **Performance** + - Optimized database queries + - Reduced redundant code + - Better caching considerations + +4. **Maintainability** + - Modular code structure + - Separated additional functions + - Clear function documentation + - Consistent coding style + +## ๐Ÿ“‹ Requirements + +- **WHMCS**: 8.0 or higher +- **PHP**: 8.0 or higher (recommended: 8.1+) +- **MySQL/MariaDB**: 5.7+ / 10.2+ +- **PHP Extensions**: + - `curl` + - `json` + - `pdo_mysql` + - `mbstring` + +## ๐Ÿ“ฆ Installation + +### New Installation + +1. **Upload Files** + ```bash + # Upload the module files to your WHMCS directory + /path/to/whmcs/modules/servers/teamspeak/ + /path/to/whmcs/modules/addons/teamspeak/ + ``` + +2. **Activate Addon Module** + - Login to WHMCS Admin Area + - Go to: `Setup > Addon Modules` + - Find "TeaSpeak Provisioning" and click "Activate" + - Configure the module settings + +3. **Configure Server** + - Go to: `Setup > Products/Services > Servers` + - Add a new server with type "TeaSpeak Provisioning Server" + - Enter your TeamSpeak ServerQuery credentials + +4. **Create Product** + - Go to: `Setup > Products/Services > Products/Services` + - Create a new product + - Set Module: "TeaSpeak Provisioning Server" + - Configure the following **Custom Fields**: + - `Token` (Text Box) - Admin token + - `Port` (Text Box) - Server port + - `Subdomain` (Text Box, optional) - For TSDNS + - Configure **Configurable Options**: + - `Slots` (Quantity) - Number of slots + - `MBots` (Quantity) - Music bot limit + +### Upgrading from Old Version + +1. **Backup First!** + ```bash + # Backup your current module + cp -r /path/to/whmcs/modules/servers/teamspeak /path/to/backup/ + cp -r /path/to/whmcs/modules/addons/teamspeak /path/to/backup/ + + # Backup database + mysqldump -u username -p database_name > backup.sql + ``` + +2. **Upload New Files** + - Replace the old files with the new ones + - The database structure remains compatible + +3. **Test the Module** + - Test creating a new service + - Test all functions (start, stop, reinstall, etc.) + - Check the client area display + +4. **Update Templates (Optional)** + - To use the new Bootstrap 5 design, update the template reference: + ```php + // In teamspeak.php, change: + 'tabOverviewReplacementTemplate' => 'templates/overview.tpl', + // To: + 'tabOverviewReplacementTemplate' => 'templates/overview_modern.tpl', + ``` + +## ๐ŸŽจ Template Options + +### Classic Template (`overview.tpl`) +- Bootstrap 3 compatible +- Matches older WHMCS themes +- Minimal changes from original + +### Modern Template (`overview_modern.tpl`) +- Bootstrap 5 design +- Font Awesome 6 icons +- Modern card-based layout +- Better mobile responsiveness +- Enhanced UX + +To switch templates, edit `teamspeak.php` in the `teamspeak_ClientArea` function. + +## โš™๏ธ Configuration + +### Addon Module Settings + +Access via: `Setup > Addon Modules > TeaSpeak Provisioning` + +- **License Key**: Your module license key +- **Server Name**: Default name for new servers +- **Port Range**: Min/Max ports for allocation +- **TSDNS Settings**: Enable/disable TSDNS integration +- **Branding**: Banner URLs, buttons, welcome messages +- **Quotas**: Download/Upload limits and bandwidth + +### Product Configuration + +**Required Custom Fields:** +1. **Token** (Text Box) + - Field Name: `Token` + - Required for admin access + +2. **Port** (Text Box) + - Field Name: `Port` + - Auto-populated on creation + +3. **Subdomain** (Text Box, optional) + - Field Name: `Subdomain` + - Required only if TSDNS is enabled + +**Required Configurable Options:** +1. **Slots** (Quantity) + - Option Name: `Slots` + - User can select slot count + +2. **MBots** (Quantity) + - Option Name: `MBots` + - Music bot limit + +## ๐Ÿ”Œ Module Functions + +### Core Functions +- โœ… **Create Account** - Automatically provisions TeaSpeak server +- โœ… **Suspend Account** - Stops server and disables autostart +- โœ… **Unsuspend Account** - Restarts server and enables autostart +- โœ… **Terminate Account** - Deletes server and cleans up data +- โœ… **Change Package** - Updates slots and bot limits +- โœ… **Test Connection** - Validates server credentials + +### Client Area Functions +- โœ… **Start Server** - Start the TeaSpeak server +- โœ… **Stop Server** - Stop the TeaSpeak server +- โœ… **Reinstall Server** - Complete server reinstallation +- โœ… **Reset Permissions** - Reset to default permissions +- โœ… **Settings Management** - Change hostname, password, welcome message +- โœ… **Token Management** - Create/delete privilege keys +- โœ… **Ban Management** - Add/remove IP, name, or UID bans +- โœ… **Backup Management** - Create, restore, download, delete backups +- โœ… **TSDNS Management** - Edit subdomain (if enabled) + +## ๐Ÿ”’ Security Features + +- Strict type declarations prevent type juggling attacks +- Input validation on all user inputs +- Parameterized database queries via Capsule ORM +- Password confirmation for sensitive operations +- IP validation for ban functions +- XSS protection in templates +- Proper error logging without exposing sensitive data + +## ๐Ÿ› Debugging + +### Enable Debug Mode + +In `teamspeak.php`, the module logs all errors via WHMCS's built-in `logModuleCall()` function. + +**View Logs:** +- Admin Area: `Utilities > Logs > Module Log` +- Filter by module: "teamspeak" + +### Common Issues + +1. **"Port does not exist in custom fields"** + - Ensure custom field "Port" exists in product settings + - Field name must be exactly: `Port` + +2. **"Slots parameter not found"** + - Ensure configurable option "Slots" exists + - Option name must be exactly: `Slots` + +3. **"Could not connect to TeamSpeak server"** + - Verify server IP and ServerQuery port + - Check firewall rules + - Verify ServerQuery credentials + +4. **TSDNS not working** + - Ensure TSDNS is enabled in addon module + - Verify TSDNS API URL and key + - Check custom field "Subdomain" exists + +## ๐ŸŒ Multi-Language Support + +The module includes translations for: +- ๐Ÿ‡ฌ๐Ÿ‡ง English +- ๐Ÿ‡ฉ๐Ÿ‡ช German (Deutsch) +- ๐Ÿ‡ช๐Ÿ‡ธ Spanish (Espaรฑol) +- ๐Ÿ‡ซ๐Ÿ‡ท French (Franรงais) +- ๐Ÿ‡ฎ๐Ÿ‡น Italian (Italiano) +- ๐Ÿ‡ต๐Ÿ‡น Portuguese (Portuguรชs) +- ๐Ÿ‡ง๐Ÿ‡ท Portuguese-BR (Portuguรชs Brasileiro) +- ๐Ÿ‡ท๐Ÿ‡บ Russian (ะ ัƒััะบะธะน) +- ๐Ÿ‡น๐Ÿ‡ท Turkish (Tรผrkรงe) +- And many more... + +Languages are automatically selected based on client's WHMCS language setting. + +## ๐Ÿ“ Changelog + +### Version 3.0.0 (2024) - Modernized Edition +- โœจ Full PHP 8.x compatibility +- โœจ WHMCS API 1.2 support +- โœจ Bootstrap 5 modern template +- โœจ Type hints and strict types +- โœจ Modern array syntax +- โœจ Improved error handling +- โœจ Better security practices +- โœจ Code documentation +- โœจ Removed hardcoded URLs +- โœจ Performance improvements +- ๐Ÿ› Fixed various bugs +- ๐Ÿ”’ Security enhancements + +### Version 2.1.4 (Previous) +- Original version +- Bootstrap 3 design +- PHP 7.x compatible +- WHMCS API 1.1 + +## ๐Ÿค Contributing + +This is a proprietary module. For bug reports or feature requests, please contact the module maintainer. + +## ๐Ÿ“„ License + +Proprietary license. See LICENSE file for details. + +## ๐Ÿ†˜ Support + +For support, please contact: +- **Website**: https://planetteaspeak.de +- **Email**: support@planetteaspeak.de + +## ๐Ÿ™ Credits + +- Original Module: planetteaspeak.de +- Modernization: 2024 Update +- TeaSpeak: https://teaspeak.de +- WHMCS: https://whmcs.com + +## ๐Ÿ“š Additional Resources + +- [WHMCS Developer Documentation](https://developers.whmcs.com/) +- [TeaSpeak Documentation](https://teaspeak.de/docs/) +- [PHP 8 Documentation](https://www.php.net/manual/en/migration80.php) + +--- + +**Last Updated**: 2024 +**Version**: 3.0.0 (Modernized Edition) \ No newline at end of file