first commit
This commit is contained in:
Kevin Feiler
316
README.md
Normal file
316
README.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# TeaSpeak WHMCS Provisioning Module - Modernized Edition
|
||||
|
||||
[](https://www.php.net/)
|
||||
[](https://www.whmcs.com/)
|
||||
[](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)
|
||||
Reference in New Issue
Block a user