planetteamspeak/ts3-php-framework

现代按需使用框架，提供独立组件以管理 TeamSpeak 3 服务器实例

维护者

详细信息

github.com/planetteamspeak/ts3phpframework

主页

源代码

问题

文档

安装次数: 75,979

依赖项: 7

建议者: 0

安全: 0

星标: 209

关注者: 23

分支: 58

开放问题: 9

1.3.0 2024-06-01 15:08 UTC

Requires

Requires (Dev)

GPL-3.0 b3629a35a5ec0eb093128ec688a10486125cf1ae

  • Sven 'ScP' Paulsen <scp.woop@planetteamspeak.com>

apiqueryserverinterfacemanagementteamspeakts3filetransfer

This package is auto-updated.

Last update: 2024-08-31 15:38:58 UTC

README

最初于2010年1月发布，TS3 PHP 框架是一个强大、开源、面向对象的框架，采用 PHP 5 实现，并采用 GNU 通用公共许可证授权。它基于简单性和严格测试的敏捷代码库。使用脚本扩展您服务器的功能或创建强大的网络应用程序来管理 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的最后一个/后面添加一些选项。

要连接到特定的虚拟TeamSpeak 3服务器，使用其virtualserver_port

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

可以使用简单的&添加其他选项，就像在HTTP GET URL中一样

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

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

TS3 PHP Framework支持连接到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服务器）

如果您正在运行一个TeaSpeak服务器并带有自定义MOTD，只需在启动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 - 旧的RFC，用于URI编码
  • 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.docker.net.cn/samples/library/teamspeak/) | [Docker Hub](https://hub.docker.com/_/teamspeak/)

使用完整的Docker Stack部署带有Maria DB的TeamSpeak 3

// 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