TeamSpeak3.php

Go to the documentation of this file.

<?php

 
namespace PlanetTeamSpeak\TeamSpeak3Framework;
 
use Exception;
use PlanetTeamSpeak\TeamSpeak3Framework\Adapter\Adapter;
use PlanetTeamSpeak\TeamSpeak3Framework\Adapter\FileTransfer;
use PlanetTeamSpeak\TeamSpeak3Framework\Adapter\MockServerQuery;
use PlanetTeamSpeak\TeamSpeak3Framework\Adapter\ServerQuery;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\AdapterException;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\HelperException;
use PlanetTeamSpeak\TeamSpeak3Framework\Exception\ServerQueryException;
use PlanetTeamSpeak\TeamSpeak3Framework\Helper\Profiler;
use PlanetTeamSpeak\TeamSpeak3Framework\Helper\StringHelper;
use PlanetTeamSpeak\TeamSpeak3Framework\Helper\Uri;
use PlanetTeamSpeak\TeamSpeak3Framework\Node\Host;
use PlanetTeamSpeak\TeamSpeak3Framework\Node\Server;

class TeamSpeak3
{
    public const TS3_PROTO_IDENT = "TS3";

    public const TS3_MOTD_PREFIX = "Welcome";

    public const TEA_PROTO_IDENT = "TeaSpeak";

    public const TEA_MOTD_PREFIX = "Welcome";

    public const ERROR = "error";

    public const EVENT = "notify";

    public const SCHID = "selected";

    public const LIB_VERSION = "1.3.0";
 
    /*@
     * TeamSpeak 3 protocol separators.
     */
    public const SEPARATOR_LINE = "\n"; 
    public const SEPARATOR_LIST = "|";  
    public const SEPARATOR_CELL = " ";  
    public const SEPARATOR_PAIR = "=";  
 
    /*@
     * TeamSpeak 3 API key scopes.
     */
    public const APIKEY_MANAGE = "manage";  
    public const APIKEY_WRITE = "write";   
    public const APIKEY_READ = "read";    
 
    /*@
     * TeamSpeak 3 log levels.
     */
    public const LOGLEVEL_CRITICAL = 0x00; 
    public const LOGLEVEL_ERROR = 0x01; 
    public const LOGLEVEL_WARNING = 0x02; 
    public const LOGLEVEL_DEBUG = 0x03; 
    public const LOGLEVEL_INFO = 0x04; 
    public const LOGLEVEL_DEVEL = 0x05; 
 
    /*@
     * TeamSpeak 3 token types.
     */
    public const TOKEN_SERVERGROUP = 0x00; 
    public const TOKEN_CHANNELGROUP = 0x01; 
 
    /*@
     * TeamSpeak 3 codec identifiers.
     */
    public const CODEC_SPEEX_NARROWBAND = 0x00; 
    public const CODEC_SPEEX_WIDEBAND = 0x01; 
    public const CODEC_SPEEX_ULTRAWIDEBAND = 0x02; 
    public const CODEC_CELT_MONO = 0x03; 
    public const CODEC_OPUS_VOICE = 0x04; 
    public const CODEC_OPUS_MUSIC = 0x05; 
 
    /*@
     * TeamSpeak 3 codec encryption modes.
     */
    public const CODEC_CRYPT_INDIVIDUAL = 0x00; 
    public const CODEC_CRYPT_DISABLED = 0x01; 
    public const CODEC_CRYPT_ENABLED = 0x02; 
 
    /*@
     * TeamSpeak 3 kick reason types.
     */
    public const KICK_CHANNEL = 0x04; 
    public const KICK_SERVER = 0x05; 
 
    /*@
     * TeamSpeak 3 text message target modes.
     */
    public const TEXTMSG_CLIENT = 0x01; 
    public const TEXTMSG_CHANNEL = 0x02; 
    public const TEXTMSG_SERVER = 0x03; 
 
    /*@
     * TeamSpeak 3 plugin command target modes.
     */
    public const PLUGINCMD_CHANNEL = 0x01; 
    public const PLUGINCMD_SERVER = 0x02; 
    public const PLUGINCMD_CLIENT = 0x03; 
    public const PLUGINCMD_CHANNEL_SUBSCRIBED = 0x04; 
 
    /*@
     * TeamSpeak 3 host message modes.
     */
    public const HOSTMSG_NONE = 0x00; 
    public const HOSTMSG_LOG = 0x01; 
    public const HOSTMSG_MODAL = 0x02; 
    public const HOSTMSG_MODALQUIT = 0x03; 
 
    /*@
     * TeamSpeak 3 host banner modes.
     */
    public const HOSTBANNER_NO_ADJUST = 0x00; 
    public const HOSTBANNER_IGNORE_ASPECT = 0x01; 
    public const HOSTBANNER_KEEP_ASPECT = 0x02; 
 
    /*@
     * TeamSpeak 3 client identification types.
     */
    public const CLIENT_TYPE_REGULAR = 0x00; 
    public const CLIENT_TYPE_SERVERQUERY = 0x01; 
 
    /*@
     * TeamSpeak 3 permission group database types.
     */
    public const GROUP_DBTYPE_TEMPLATE = 0x00; 
    public const GROUP_DBTYPE_REGULAR = 0x01; 
    public const GROUP_DBTYPE_SERVERQUERY = 0x02; 
 
    /*@
     * TeamSpeak 3 permission group name modes.
     */
    public const GROUP_NAMEMODE_HIDDEN = 0x00; 
    public const GROUP_NAMEMODE_BEFORE = 0x01; 
    public const GROUP_NAMEMODE_BEHIND = 0x02; 
 
    /*@
     * TeamSpeak 3 permission group identification types.
     */
    public const GROUP_IDENTIFIY_STRONGEST = 0x01; 
    public const GROUP_IDENTIFIY_WEAKEST = 0x02; 
 
    /*@
     * TeamSpeak 3 permission types.
     */
    public const PERM_TYPE_SERVERGROUP = 0x00; 
    public const PERM_TYPE_CLIENT = 0x01; 
    public const PERM_TYPE_CHANNEL = 0x02; 
    public const PERM_TYPE_CHANNELGROUP = 0x03; 
    public const PERM_TYPE_CHANNELCLIENT = 0x04; 
 
    /*@
     * TeamSpeak 3 permission categories.
     */
    public const PERM_CAT_GLOBAL = 0x10; 
    public const PERM_CAT_GLOBAL_INFORMATION = 0x11; 
    public const PERM_CAT_GLOBAL_SERVER_MGMT = 0x12; 
    public const PERM_CAT_GLOBAL_ADM_ACTIONS = 0x13; 
    public const PERM_CAT_GLOBAL_SETTINGS = 0x14; 
    public const PERM_CAT_SERVER = 0x20; 
    public const PERM_CAT_SERVER_INFORMATION = 0x21; 
    public const PERM_CAT_SERVER_ADM_ACTIONS = 0x22; 
    public const PERM_CAT_SERVER_SETTINGS = 0x23; 
    public const PERM_CAT_CHANNEL = 0x30; 
    public const PERM_CAT_CHANNEL_INFORMATION = 0x31; 
    public const PERM_CAT_CHANNEL_CREATE = 0x32; 
    public const PERM_CAT_CHANNEL_MODIFY = 0x33; 
    public const PERM_CAT_CHANNEL_DELETE = 0x34; 
    public const PERM_CAT_CHANNEL_ACCESS = 0x35; 
    public const PERM_CAT_GROUP = 0x40; 
    public const PERM_CAT_GROUP_INFORMATION = 0x41; 
    public const PERM_CAT_GROUP_CREATE = 0x42; 
    public const PERM_CAT_GROUP_MODIFY = 0x43; 
    public const PERM_CAT_GROUP_DELETE = 0x44; 
    public const PERM_CAT_CLIENT = 0x50; 
    public const PERM_CAT_CLIENT_INFORMATION = 0x51; 
    public const PERM_CAT_CLIENT_ADM_ACTIONS = 0x52; 
    public const PERM_CAT_CLIENT_BASICS = 0x53; 
    public const PERM_CAT_CLIENT_MODIFY = 0x54; 
    public const PERM_CAT_FILETRANSFER = 0x60; 
    public const PERM_CAT_NEEDED_MODIFY_POWER = 0xFF; 
 
    /*@
     * TeamSpeak 3 file types.
     */
    public const FILE_TYPE_DIRECTORY = 0x00; 
    public const FILE_TYPE_REGULAR = 0x01; 
 
    /*@
     * TeamSpeak 3 server snapshot types.
     */
    public const SNAPSHOT_STRING = 0x00; 
    public const SNAPSHOT_BASE64 = 0x01; 
    public const SNAPSHOT_HEXDEC = 0x02; 
 
    /*@
     * TeamSpeak 3 channel spacer types.
     */
    public const SPACER_SOLIDLINE = 0x00; 
    public const SPACER_DASHLINE = 0x01; 
    public const SPACER_DOTLINE = 0x02; 
    public const SPACER_DASHDOTLINE = 0x03; 
    public const SPACER_DASHDOTDOTLINE = 0x04; 
    public const SPACER_CUSTOM = 0x05; 
 
    /*@
     * TeamSpeak 3 channel spacer alignments.
     */
    public const SPACER_ALIGN_LEFT = 0x00; 
    public const SPACER_ALIGN_RIGHT = 0x01; 
    public const SPACER_ALIGN_CENTER = 0x02; 
    public const SPACER_ALIGN_REPEAT = 0x03; 
 
    /*@
     * TeamSpeak 3 reason identifiers.
     */
    public const REASON_NONE = 0x00; 
    public const REASON_MOVE = 0x01; 
    public const REASON_SUBSCRIPTION = 0x02; 
    public const REASON_TIMEOUT = 0x03; 
    public const REASON_CHANNEL_KICK = 0x04; 
    public const REASON_SERVER_KICK = 0x05; 
    public const REASON_SERVER_BAN = 0x06; 
    public const REASON_SERVER_STOP = 0x07; 
    public const REASON_DISCONNECT = 0x08; 
    public const REASON_CHANNEL_UPDATE = 0x09; 
    public const REASON_CHANNEL_EDIT = 0x0A; 
    public const REASON_DISCONNECT_SHUTDOWN = 0x0B; 

    protected static array $escape_patterns = [
        "\\" => "\\\\", // backslash
        "/" => "\\/",  // slash
        " " => "\\s",  // whitespace
        "|" => "\\p",  // pipe
        ";" => "\\;",  // semicolon
        "\a" => "\\a",  // bell
        "\b" => "\\b",  // backspace
        "\f" => "\\f",  // formfeed
        "\n" => "\\n",  // newline
        "\r" => "\\r",  // carriage return
        "\t" => "\\t",  // horizontal tab
        "\v" => "\\v"   // vertical tab
    ];

    public static function factory(string $uri): Host|Server|ServerQuery|MockServerQuery|FileTransfer
    {
        self::init();
 
        $uri = new Uri($uri);
 
        $adapter = self::getAdapterName($uri->getScheme());
        $options = ["host" => $uri->getHost(), "port" => $uri->getPort(), "timeout" => (int)$uri->getQueryVar("timeout", 10), "blocking" => (int)$uri->getQueryVar("blocking", 1), "tls" => (int)$uri->getQueryVar("tls", 0), "ssh" => (int)$uri->getQueryVar("ssh", 0)];
 
        self::loadClass($adapter);
 
        if ($options["ssh"]) {
            $options["username"] = $uri->getUser();
            $options["password"] = $uri->getPass();
        }
 
        $adapterClass = "PlanetTeamSpeak\\TeamSpeak3Framework\\" . str_replace(DIRECTORY_SEPARATOR, "\\", $adapter);
 
        $object = new $adapterClass($options);
 
        try {
            if ($object instanceof ServerQuery) {
                $node = $object->getHost();
 
                if ($uri->hasUser() && $uri->hasPass()) {
                    $node->login($uri->getUser(), $uri->getPass());
                }
 
                if ($uri->hasQueryVar("nickname")) {
                    $node->setPredefinedQueryName($uri->getQueryVar("nickname"));
                }
 
                if ($uri->getFragment() == "use_offline_as_virtual") {
                    $node->setUseOfflineAsVirtual(true);
                } elseif ($uri->hasQueryVar("use_offline_as_virtual")) {
                    $node->setUseOfflineAsVirtual((bool)$uri->getQueryVar("use_offline_as_virtual"));
                }
 
                if ($uri->getFragment() == "clients_before_channels") {
                    $node->setLoadClientlistFirst(true);
                } elseif ($uri->hasQueryVar("clients_before_channels")) {
                    $node->setLoadClientlistFirst((bool)$uri->getQueryVar("clients_before_channels"));
                }
 
                if ($uri->getFragment() == "no_query_clients") {
                    $node->setExcludeQueryClients(true);
                } elseif ($uri->hasQueryVar("no_query_clients")) {
                    $node->setExcludeQueryClients((bool)$uri->getQueryVar("no_query_clients"));
                }
 
                if ($uri->hasQueryVar("server_id")) {
                    $node = $node->serverGetById($uri->getQueryVar("server_id"));
                } elseif ($uri->hasQueryVar("server_uid")) {
                    $node = $node->serverGetByUid($uri->getQueryVar("server_uid"));
                } elseif ($uri->hasQueryVar("server_port")) {
                    $node = $node->serverGetByPort($uri->getQueryVar("server_port"));
                } elseif ($uri->hasQueryVar("server_name")) {
                    $node = $node->serverGetByName($uri->getQueryVar("server_name"));
                }
 
                if ($node instanceof Server) {
                    if ($uri->hasQueryVar("channel_id")) {
                        $node = $node->channelGetById($uri->getQueryVar("channel_id"));
                    } elseif ($uri->hasQueryVar("channel_name")) {
                        $node = $node->channelGetByName($uri->getQueryVar("channel_name"));
                    }
 
                    if ($uri->hasQueryVar("client_id")) {
                        $node = $node->clientGetById($uri->getQueryVar("client_id"));
                    }
                    if ($uri->hasQueryVar("client_uid")) {
                        $node = $node->clientGetByUid($uri->getQueryVar("client_uid"));
                    } elseif ($uri->hasQueryVar("client_name")) {
                        $node = $node->clientGetByName($uri->getQueryVar("client_name"));
                    }
                }
 
                return $node;
            }
        } catch (Exception $e) {
            $object->__destruct();
            throw $e;
        }
 
        return $object;
    }

    protected static function getAdapterName(string $name, string $namespace = "Adapter_"): string
    {
        $path = self::getFilePath($namespace);
        $scan = scandir(__DIR__ . DIRECTORY_SEPARATOR . $path);
 
        foreach ($scan as $node) {
            $file = StringHelper::factory($node)->toLower();
 
            if ($file->startsWith($name) && $file->endsWith(".php")) {
                return $path . str_replace(".php", "", $node);
            }
        }
 
        throw new AdapterException("adapter '" . $name . "' does not exist");
    }

    protected static function loadClass(string $class): bool
    {
        if (class_exists($class, false) || interface_exists($class, false)) {
            return false;
        }
 
        if (preg_match("/[^a-z0-9\\/\\\\_.-]/i", $class)) {
            throw new Exception("illegal characters in classname '" . $class . "'");
        }
 
        $file = __DIR__ . DIRECTORY_SEPARATOR . self::getFilePath($class) . ".php";
 
        if (!file_exists($file) || !is_readable($file)) {
            throw new Exception("file '" . $file . "' does not exist or is not readable");
        }
 
        if (class_exists($class, false) || interface_exists($class, false)) {
            throw new Exception("class '" . $class . "' does not exist");
        }
 
        return include_once($file);
    }

    protected static function getFilePath(string $name): string
    {
        $path = str_replace("_", DIRECTORY_SEPARATOR, $name);
        return str_replace(__CLASS__, dirname(__FILE__), $path);
    }

    public static function init(): void
    {
        if (version_compare(phpversion(), "5.2.1") == -1) {
            throw new Exception("this particular software cannot be used with the installed version of PHP");
        }
 
        if (!function_exists("stream_socket_client")) {
            throw new Exception("network functions are not available in this PHP installation");
        }
 
        if (!function_exists("spl_autoload_register")) {
            throw new Exception("autoload functions are not available in this PHP installation");
        }
 
        Profiler::start();
    }

    public static function getEscapePatterns(): array
    {
        return self::$escape_patterns;
    }

    public static function dump(mixed $var, bool $echo = true): string
    {
        ob_start();
        var_dump($var);
 
        $output = preg_replace("/]=>\n(\s+)/m", "] => ", ob_get_clean());
 
        if (PHP_SAPI == "cli") {
            $output = PHP_EOL . PHP_EOL . $output . PHP_EOL;
        } else {
            $output = "<pre>" . htmlspecialchars($output, ENT_QUOTES, "utf-8") . "</pre>";
        }
 
        if ($echo) {
            echo($output);
        }
 
        return $output;
    }
}