README

这是https://github.com/HerrSammyDE/ts3-php-framework/的镜像，用于https://packagist.org.cn/packages/herrsammyde/ts3-php-framework
所有权利归各自所有者所有

最初于2010年1月发布，TS3 PHP框架是一个强大、开源、面向对象的框架，使用PHP 5实现并许可在GNU通用公共许可证下。它基于简单性和严格测试的敏捷代码库。通过脚本扩展服务器功能，或创建强大的Web应用程序来管理您的TeamSpeak 3服务器实例的所有功能。

经过彻底测试。企业级，采用敏捷方法构建，TS3 PHP框架从一开始就进行了单元测试，以确保所有代码都保持稳定，并且易于您扩展、用您的扩展进行重新测试，并进一步维护。

为什么TS3 PHP框架比其他库更好？

TS3 PHP框架是一个现代的按需使用框架，提供用于与TeamSpeak 3服务器通信的独立组件。

与其他基于PHP的库相比，有许多关于TS3 PHP框架的论点。它是其类别中最动态、功能最丰富的软件，并且在使用正确的情况下提供了前所未有的性能。

特性

TS3 PHP框架的特性包括

• 完全面向对象的PHP 5和E_STRICT兼容组件
• 通过ServerQuery访问所有TeamSpeak 3服务器功能
• 集成全功能且可定制的TSViewer界面
• 完全支持文件传输，上传和/或下载自定义图标和其他内容
• 使用异常和可定制的错误消息的强大错误处理能力
• 针对多个官方服务（如黑名单和自动更新服务器）的查询机制
• 基于事件的脚本动态信号槽

使用这个小巧的软件加快新开发并降低维护成本！

安装

要求

• PHP - 基于 PHP 7.x 开发，以 7.2.x 为目标进行测试。
• TeamSpeak服务器 - v3.4.0（构建 >= 1536564584）或更高版本。

常与以下内容一起使用...

• 服务器 - Apache，nginx，php-fpm，CLI
• 数据库 - 独立（sqlite），Maria DB，PostgreSQL
• 开发 - Git，composer，docker，PHPUnit

请注意，TS3 PHP框架的大多数开发和部署是在nginx上进行的，因此在Apache上的社区经验和测试比在其他Web服务器上更多。

您可以通过手动下载或使用Composer安装TS3 PHP框架

composer require planetteamspeak/ts3-php-framework

上述命令将安装最新可用的版本。

如果您想安装TS3 PHP框架的master分支（可能尚未发布/标记），则需要运行

composer require planetteamspeak/ts3-php-framework:dev-master

测试

要运行所有测试，请使用php vendor/bin/phpunit。

有用链接

访问以下页面了解更多关于TS3 PHP框架的信息

• 在线文档
• 变更日志
• 变更日志（开发版）

入门指南

连接URI（选项+ IPv4 与 IPv6）

在您能够运行“获取服务器实例的版本”或“更新一些设置”之类的命令之前，您需要指定要连接到的实例。这是通过在TeamSpeak3::factory($uri)中使用的URI完成的。

基础 $uri 总是看起来像这样

$uri = "serverquery://username:password@127.0.0.1:10011/";

注意：如果你的 URI 中包含特殊字符，你需要使用 rawurlencode 对这部分进行编码

$uri = "serverquery://" . rawurlencode("test!@#$%^&*()_+") . ":" . rawurlencode('sd5kjKJ2') . "@127.0.0.1:10011/";

你还可以在 URI 的最后一个 / 后面添加一些选项。

要使用 virtualserver_port 连接到特定的 TeamSpeak 3 服务器

$uri = "serverquery://username:password@127.0.0.1:10011/?server_port=9987";

可以通过简单的 & 添加额外的选项，就像在 HTTP GET URLs 中一样

$uri = "serverquery://username:password@127.0.0.1:10011/?server_port=9987&blocking=0";

可用选项的列表可以在 TeamSpeak3 > factory 中找到

TS3 PHP 框架支持连接到 IPv6 TeamSpeak 主机。IPv6 地址必须写成方括号内

$uri = "serverquery://username:password@[fe80::250:56ff:fe16:1447]:10011/";

你可以使用这个简单的技巧来始终根据提供的 IP 地址类型获取正确的 URI

if(filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV4)) {
  $uri = "serverquery://username:password@${ip}:10011/";
} elseif(filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_IPV6)) {
  $uri = "serverquery://username:password@[${ip}]:10011/";
} else {
  echo "${ip} is no valid IPv4 or IPv6 address!";
}

SSH 连接（仅限 TeamSpeak 服务器）

可以使用可选的 ssh 参数建立 SSH 连接

$uri = "serverquery://username:password@[fe80::250:56ff:fe16:1447]:10022/?ssh=1";

SSL/TLS 连接（仅限 TeaSpeak 服务器）

可以使用可选的 tls 参数建立安全的 ServerQuery 连接

$uri = "serverquery://username:password@[fe80::250:56ff:fe16:1447]:10011/?tls=1";

自定义协议欢迎信息和/或 MOTD（仅限 TeaSpeak 服务器）

如果你正在运行一个自定义 MOTD 的 TeaSpeak 服务器，只需在开始 ServerQuery 连接之前定义 CUSTOM_PROTO_IDENT 和/或 CUSTOM_MOTD_PREFIX

define("CUSTOM_PROTO_IDENT", "MyTS3");
define("CUSTOM_MOTD_PREFIX", "Hello");

编码 URI 特殊字符

当将 URI 作为参数或参数传递时，某些部分可能需要包含特殊字符。你应该在这些部分上使用 rawurlencode

// Bad:
$uri = "serverquery://test!@#$%^&*()_+:sd5kjKJ2@127.0.0.1:10011/";
// Good:
$uri = "serverquery://" . rawurlencode("test!@#$%^&*()_+") . ":sd5kjKJ2@127.0.0.1:10011/";

注意：编码 URI 组件而不是整个 URI 字符串。有效的特殊字符需要保持未编码！

特殊字符在新版的 RFC 3986 中定义为不在 (ascii, latin) 集合中的任何字符

ALPHA / DIGIT / "-" / "." / "_" / "~"

附加信息

• 最常见的情况是只对 'username'、'password' 部分进行编码。
• 如果没有使用特殊字符，则无需编码。
• 路径和查询组件需要额外的解析，例如，我们不想对有效的 '/' 和 '&' 进行编码。
• 片段组件可能需要使用旧的 urlencode 进行编码。
• RFC 1738 - 用于 URI 编码的旧 RFC
• RFC 3986 - 现有的 URI 标准
• RFC 2396 - 第 3 部分 - 有效的 URI 语法（特别是，组件）
• PHP.net - rawurlencode

常用的 PHP 代码（require 解决方案）

常用的 PHP 代码意味着一个简单的创建的 file.php，你将像这样开始编写你的代码

<?php

echo "Hello World!";

当你使用这个解决方案时，你可能会像这样开始使用 TS3 PHP 框架

<?php
// load framework files
require_once("libraries/TeamSpeak3/TeamSpeak3.php");
  
try
{
  // IPv4 connection URI
  $uri = "serverquery://username:password@127.0.0.1:10011/?server_port=9987";

  // connect to above specified server, authenticate and spawn an object for the virtual server on port 9987
  $ts3_VirtualServer = TeamSpeak3::factory($uri);

  // spawn an object for the channel using a specified name
  $ts3_Channel = $ts3_VirtualServer->channelGetByName("I do not exist");
}
catch(TeamSpeak3_Exception $e)
{
  // print the error message returned by the server
  echo "Error " . $e->getCode() . ": " . $e->getMessage();
}

PHP 代码在 MVC 中（use 解决方案）

当你使用基于 MVC 的软件，如 Symfony、CakePHP、Laravel 或类似软件时，你可能会使用类似这样的代码

<?php

use TeamSpeak3;
use TeamSpeak3_Exception;

class TeamspeakController extends Controller
{
  public function doSomething()
    {
    try
    {
      // IPv4 connection URI
      $uri = "serverquery://username:password@127.0.0.1:10011/?server_port=9987";
      
      // Create new object of TS3 PHP Framework class
      $TS3PHPFramework = new TeamSpeak3();
      
      // connect to above specified server, authenticate and spawn an object for the virtual server on port 9987
      $ts3_VirtualServer = $TS3PHPFramework->factory($uri);
      
      // spawn an object for the channel using a specified name
      $ts3_Channel = $ts3_VirtualServer->channelGetByName("I do not exist");
    }
    catch(TeamSpeak3_Exception $e)
    {
      // print the error message returned by the server
      return "Error " . $e->getCode() . ": " . $e->getMessage();
    }
  }
}

有关更多信息，请访问文档（见上面的 有用链接）

Docker

设置 TeamSpeak3 的本地测试实例（amd64，Alpine Linux）

docker run --name teamspeak_server -p 9987:9987/udp -p 10011:10011 -p 30033:30033 -e TS3SERVER_LICENSE=accept teamspeak:latest

添加 -d 标志以在后台运行。选项 / 示例：[Docker 文档](https://docs.dockerd.com.cn/samples/library/teamspeak/) | [Docker Hub](https://hub.docker.com/_/teamspeak/)

使用完整 Docker Stack 部署 TeamSpeak 3 与 Maria DB

// If fresh Docker install, you might need to:
docker swarm init
// Deploy stack with latest TS3, PHP 7.x, Maria DB:
docker stack deploy -c docker-compose.yml teamspeak

其他有用的命令

docker logs teamspeak_server # View container logs
docker exec -it teamspeak_server sh # Open shell in container
docker stop teamspeak_server # Stop container
docker rm teamspeak_server # Remove container
docker ps # Show all processes
docker stack ps # Show stack processes
docker stack ls # List stacks

注意：当部署 Docker Stack 时，容器将被唯一命名

$ docker stack ps teamspeak
CONTAINER ID        IMAGE               ...   NAMES
f97fe9827b08        mariadb:latest      ...   teamspeak_db.1.xbwjm6jcu5qow44u5i9da2hcv
f9c1538b9875        teamspeak:latest    ...   teamspeak_teamspeak.1.rr3sipmw6dhod92wuhgs3s1rn