README

这是 Threema Gateway API 的非官方包装器。

您还有四个其他选择

使用官方 Threema github 仓库 https://github.com/threema-ch/threema-msgapi-sdk-php。不再维护（2015年10月）
从 https://gateway.threema.ch/ 下载 .zip 文件版本。目前版本 v1.1.7，发布于 2016 年 10 月。缺少批量查找 API。
使用一个接近官方版本的未官方版本，偶尔接受 Threema 的补丁 https://github.com/rugk/threema-msgapi-sdk-php。它有一个 official 分支，反映了官方版本。Rugk 已经做了大量出色的工作，将包推进现代生态系统，同时尽可能地保持向后兼容。
使用 https://github.com/chillerlan/php-threema，这是一个单独的实现（2017年6月），缺少一些功能。在某些地方，API 比上述替代方案更简洁/更有逻辑性。

为什么要构建另一个版本？

PHP7.2 集成了 libsodium。如果我们以 7.2 作为最低版本，官方版本中的大量复杂代码就不再需要。我们可以删除旧的 PECL sodium 驱动程序和驱动程序选择代码。Salt git 子模块不再需要。
Composer 意味着我们可以在命令行运行器、删除大量文件并执行静态初始化的自动加载器（即使在 Threema 不被使用的情况下）
修复一些由上述内容引起的问题，以及一些损坏的类型提示（针对 phpStorm），并将（少量）单元测试拆分到单独的 /tests 目录，以避免污染权威类映射
添加缺少的 批量查找 功能（通过子类化替代方案难以添加）
添加对其他未记录的消息类型（例如位置）的支持。
总的来说，尽量遵循现代 php 包约定，以便在其他项目中使用时更舒适。
修复一些架构问题，使其更容易测试，并允许依赖注入。
使 API 更一致：例如，很难知道何时传递二进制值或十六进制编码的值。
简化 API：删除或包装辅助类以减少复杂性

总之，有什么新功能

仅限 PHP7.2+（libsodium）
遵循现代约定的简单包
Composer 支持：干净的自动加载器
依赖注入
Symfony 控制台命令，便于使用并便于在大型应用程序中集成
支持批量查找 API 调用
支持接收位置消息类型（未公开记录）

版本控制

官方 .zip 版本为 1.1.7，截至撰写本文时（2018 年 8 月）。Rugk 版本为 1.2.0（2018 年 8 月）。此存储库是 1.2.0 主干的克隆。为了减少混淆，此存储库命名为 threema-gateway 而不是 threema-msgapi-sdk。由于破坏性更改，它从 2.0.0 开始。有关详细信息，请参阅 CHANGELOG.md

此存储库的贡献者与 Threema 或 Threema GmbH 无关。

安装

composer install lss/threema-gateway

如果您想检查您的服务器是否符合要求并且一切配置是否正确，请在控制台运行 vendor/bin/threema-gateway 不带任何参数。如果它正在运行，它应该会显示命令列表；如果不，则会显示错误信息。

SDK 使用方法

按照以下文档创建新的密钥对。请妥善保存它们并保密。不要通过网络使它们可访问。
访问 https://gateway.threema.ch/ 并创建一个账户。
您将选择您的 Threema ID，它以 * 开头，总共有 8 个字符长，例如 *MYKEY12。
上传您的公钥。
您的 API 密钥显示为您的账户名称：一个 16 位的字母数字字符串。

创建连接

$connectionFactory = new ConnectionFactory();
$connection = $connectionFactory->getConnection('*MYKEY12', 'MYAPISECRET');

目前只有一个加密方法和一个 HttpDriver（目前）可用。如果您想更改连接设置或提供替代驱动程序或模拟进行测试，请将它们传递给 ConnectionFactory 构造函数

向 Threema ID 发送文本消息（简单模式）

消息在 Threema 网关服务器上加密。

$result = $connection->sendToThreemaID('TEST1234', "This is a Test Message");
if ($result->isSuccess()) {
    echo 'new id created '.$result->getMessageId();
}
else {
    echo 'error '.$result->getErrorMessage();
}

向 Threema ID 发送文本消息（端到端模式）

消息在发送到 Threema 网关之前在本地加密。

$result = $connection->sendTextMessage($myPrivateKeyHex, "TEST1234", "thePublicKeyAsHex", "This is an end-to-end encrypted message");

if ($result->isSuccess()) {
    echo 'Message ID: '.$result->getMessageId() . "\n";
}
else {
    echo 'Error: '.$result->getErrorMessage() . "\n";
}

向 Threema ID 发送文件消息（端到端模式）

$result = $connection->sendFileMessage($myPrivateKeyHex, "TEST1234", "thePublicKeyAsHex", "/path/to/my/file.pdf");

if ($result->isSuccess()) {
    echo 'File Message ID: '.$result->getMessageId() . "\n";
}
else {
    echo 'Error: '.$result->getErrorMessage() . "\n";
}

技术说明

与 Threema 网关服务器的通信大部分是二进制的。但并非全部。有时你会得到二进制值的十六进制版本。PHP 包装器试图隐藏所有这些：将所有值作为十六进制编码的二进制字符串传递给 $connection（使用 $encryptor->bin2hex()）。所有返回的值都是十六进制编码的二进制字符串。

$encryptor 主要需要和返回二进制字符串作为参数，但在使用 API 的正常情况下，您不需要加密器，因此不需要担心它。如果不确定，请参阅控制台命令示例。大多数参数现在都有 phpDoc 注释，告诉您它们是二进制字符串还是十六进制字符串。

tl;dr：预计将看到并使用十六进制

控制台客户端使用方法

运行

vendor/bin/threema-gateway

以获取命令及其选项的列表。

将您的 API 密钥、公钥和私钥存储在当前工作目录中名为 default.key 的文件中。有关模板，请参阅 default.key.sample。这将节省您大量的输入并使您的秘密不在命令行上。请不要将 default.key 文件提交到版本控制。

要生成新的密钥对，

vendor/bin/threema-gateway key:create-pair

它将打印密钥到控制台。将它们复制并粘贴到您的 default.key 文件中。您还需要这些信息在 Threema 网关上注册您的 ID。

一个好的测试来查看一切是否正常工作的是

vendor/bin/threema-gateway credits

它应该显示您账户中剩余的积分或失败时的错误信息。

贡献

您的拉取请求在这里受到欢迎。请遵循已经存在的非正式编码风格（它试图保持接近 Threema 的原始风格）。有关注意事项，请参阅本说明书的顶部：这是一个非官方分支的非官方分支。这个分支的目标与其他分支非常不同，因此也许您可以考虑您的贡献在哪里最有用。

原始代码没有附带很多测试。所有新的代码都应该由 phpUnit 测试覆盖。要运行测试，

composer test

或

vendor/bin/phpunit

使用 phpstan 进行检查，它必须在最大级别上为绿色（没有错误）。

composer phpstan

待办事项

ReceiveMessageResult 假设您想要将文件附件存储在本地文件系统中。这可能并不正确，例如如果使用 Amazon 基础设施。重构以允许 FileAcceptors(?) 可以被重载以使用 Flysystem、本地文件系统或忽略文件的空对象模式
Url 类可能不需要
等待PSR-18获得批准，然后迁移HttpDriver使用它（然后我们可以停止自己直接使用cUrl，并依赖第三方做得更好）

其他平台（Java和Python）

GitHub上的所有仓库现在不再由Threema GmbH维护。然而，社区已经分支了所有平台的仓库，现在它们是非官方维护的。

Java仓库可以在simmac/threema-msgapi-sdk-java找到
和Python仓库可以在lgrahl/threema-msgapi-sdk-python找到。

lss / threema-gateway

维护者

详细信息