README

Caution

IMPORTANT CHANGE
With Version 3.x we refactored to integrate phpseclib3. This changes affects how TCP connections are established. The "raw" mode was removed, and the support for only ssh mode was established to handel Teamspeak 3 and Teamspeak 6 Server API connections.

The X stands for a non-specific Teamspeak Server Version. So we would handle all current and future Versions from a Teamspeak Server.

Unfortunately, the original repository is no longer up to date and has not been maintained for 3 years. This is the reason why this project is being created.
The main goal is to bring the framework up to date and to equip it with extended unit tests which can also be carried out with tests for a live server.
The ideal is that this version can be integrated into your own project and the main functionalities can be tested with your Teamspeak server.

Installation

With the Refactoring at Version 3.x, the Framework has a lot of changes. But most functionalities and namespaces are the same.

PHP Required Extensions
apt install php8.3 php8.3-{common,mbstring,ssh2} -y

Via Composer
Current Version:
composer require prestige-solution/ts-x-php-framework

or with a specific release
composer require prestige-solution/ts-x-php-framework:latest
composer require prestige-solution/ts-x-php-framework:3.0.0-beta

or with a specific branch
composer require prestige-solution/ts-x-php-framework:dev-ts-x-refactoring-dev

If your teamspeak 3 server is not running with version 3.x, check the rsa host key situation

Check out the documentation make-ts3-ssh-compatible.md
There you can find instructions to set up a compatible rsa host key. It should work with docker and non-docker versions.

New test routines for future developments and improvements with live server testing

Prepare your Environment
Before you start UnitTests, make sure that you have set the environment variables. You find more information's at testing-live-server

Permissions for Query User
The best way to test all functionalities is to use the serveradmin query user.
The serveradmin is != Server Admin there you can find in your Teamspeak Client UI.

You can find more information in the Documentation testing-live-server

Additional Node

• We know the serveradmin (query user) is a high-security risk if you use it over the internet. We would try to find a better solution with SSH public key authentication.
  
• Currently, you can improve fail2ban, query_ip_whitelist and query_ip_blacklist.

Run Tests
To run all tests use composer test.

Build Factory URI

Default URI Options

If you build the serverquery without the above parameter, then their options will be set by default.
Note: don't set timeout to 0. Further Information's at php.net

Examples

• URI Example

'serverquery://<user>:<pass>@<host>:<port>/?server_port=9987&no_query_clients=0&timeout=30&nickname=<bot_name>'

• Contains Username or Password special chars like + then you can use

'serverquery://'.rawurlencode(<user>).':'.rawurlencode(<password>) .'@<host>:<port>/?server_port=9987&no_query_clients=0&timeout=30'

In my opinion, you should don't use specials chars. Better, create a new QueryLogin Password and / or Username.

• You can use IPv4, IPv6 or DNS. Implement the following Example in your Project.

if (filter_var($host, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4) || filter_var(gethostbyname($host), FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
    $validatedHost = $host;
} elseif (filter_var($host, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6) || filter_var(gethostbyname($host), FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
    $validatedHost = '['.$host.']';
} else {
    return false;
}

Important note

We have no intention of abandoning the original repository altogether. We will keep the namespace so that an update to the original PlanetTeamspeak repository can be considered as far as possible and the Support from the Maintainer is back.