README

这是一个PHP HTTP客户端，使用Guzzle HTTP库对Mastodon联邦社交网络的REST API进行操作。

安装

您需要PHP 7.0+和Composer来运行此项目。准备好了吗？运行

composer require phediverse/mastodon-rest

将库导入您的项目。然后，无论您在哪里使用它，请确保已包含Composer的自动加载器，通过

require __DIR__ . 'vendor/autoload.php'; // assuming you're in the same directory as the vendor dir Composer created

获取认证

除了少数例外（见下方的“未认证端点”），您需要访问令牌才能使用API进行任何有用的操作。这个访问令牌是由指向您所在实例的有效注册应用程序生成的有效用户生成的。此时，应用程序和访问令牌都是长期有效的；一旦您获得一个，就不需要为特定用户返回。因此，不同的类处理与认证相关的任务，而不是实际端点活动。

注册应用程序

首先，您需要注册一个应用程序。您需要一个名称和一个重定向URI，并需要决定应用程序应该默认使用的范围。有关范围的信息可以在https://github.com/tootsuite/mastodon/blob/master/docs/Using-the-API/OAuth-details.md找到。

一旦您有了您的应用程序，您可以使用json_encode()函数将对象进行编码以存储其凭据以备后用。

use Phediverse\MastodonRest\{Auth\AppRegisterClient, Auth\Scope, Resource\Application};

$registerClient = AppRegisterClient::forInstance('social.targaryen.house');
$app = $registerClient->createApp('My Phediverse Reader', 'https://example.com/oauth_landing', [Scope::READ]);

如果您打算直接使用应用程序进行登录（而不是通过授权代码授予方式的正确OAuth 2方式），或者您不介意人们从他们的浏览器中将授权代码复制粘贴到您的应用程序中，您可以使用Resource\Application::REDIRECT_NONE URI而不是标准HTTP URL。此外，如果您在创建应用程序时没有指定范围，客户端将自动为您请求所有三个范围，即Scope::ALL。或者，换句话说

$anotherApp = $registerClient->createApp('No Redirect, All The Power', Application::REDIRECT_NONE);
file_put_contents('instance_creds.json', json_encode($anotherApp));

通过授权代码授予进行登录

注意：以下示例使用内置的PHP函数来处理请求等；如果您在（微）框架中使用此库，请使用该框架的请求/响应处理方法。

开始过程

现在您已经有了应用程序，您可以进行OAuth2授权代码授予过程。首先，让我们从配置JSON中提取我们的应用程序，并将其放入AuthClient实例中。

$app = \Phediverse\MastodonRest\Resource\Application::fromJsonConfig(file_get_contents('instance_creds.json'));
$authClient = \Phediverse\MastodonRest\Auth\AuthClient::forApplication($app);

然后让我们确定要重定向用户的位置，添加一个随机的state值以避免跨站请求伪造（CSRF）攻击。Mastodon将state作为查询字符串参数返回，当我们重定向回我们时。

$url = $authClient->getAuthCodeUrl($state = bin2hex(random_bytes(12)));
// record $state to the user's session or similar
header('Location', $url); // redirect the user to the OAuth2 Auth Code URL

请注意，虽然state由OAuth2 RFC推荐，但它不是必需的，如果没有实际的重定向，它就没有意义。在这种情况下，您可以在调用中省略该参数，或者如果需要使用第二个参数：访问令牌请求的范围数组，将其设置为null。如果您省略第二个参数，如上面所示，您将获得在最初设置应用程序时请求的范围。这与省略范围时的原始API行为略有不同，后者返回一个只有read访问权限的令牌。

完成过程

一旦用户登录到Mastodon实例并允许您的应用程序访问，他们将被重定向回您，查询字符串中包含code以及您在上面的示例中提供的state。如果您的应用程序使用了非重定向，用户将获得授权代码在他们的浏览器窗口中。

假设您已经设置了一个重定向登录页面，当用户登录到您的页面后，还需要一个步骤来获取访问令牌。

// since we're in a different request than where we started this process...
$app = \Phediverse\MastodonRest\Resource\Application::fromJsonConfig(file_get_contents('instance_creds.json'));
$authClient = \Phediverse\MastodonRest\Auth\AuthClient::forApplication($app);

// verify state here; it'll be in $_GET['state']

$accessToken = $authClient->finishAuthCodeRequest($_GET['code']); // string

恭喜！您现在有了该用户在该Mastodon实例的访问令牌，可以使用主API客户端类，或者任何其他Mastodon API客户端。

通过密码授权登录

如果您使用此库用于个人用途，并且不介意用户凭据通过或存储在您的系统中，流程会更简单，而且不需要跨越多个请求。

// still need your app and an AuthClient
$app = \Phediverse\MastodonRest\Resource\Application::fromJsonConfig(file_get_contents('instance_creds.json'));
$authClient = \Phediverse\MastodonRest\Auth\AuthClient::forApplication($app);

$accessToken = $authClient->login('your@email.address', 'SuperSecretP4$$w0rd'/*, override scopes here */);

与授权代码流一样，如果您没有指定任何作用域，您将获得一个使用您在设置应用程序时指定的默认作用域的令牌。

方法和资源

现在您已经获得了访问令牌，您可以设置主API客户端实例。

$client = \Phediverse\MastodonRest\Client::build('social.targaryen.house', $accessToken);

让我们先获取您自己账户的显示名称。

$account = $client->getAccount(/* defaults to your ID; can put someone else's ID in here too */);
echo $account->getDisplayName(); // Your Display Name

资源也可以直接引用其他资源，例如。

$instance = $account->getInstance(); // Instance resource

您还可以序列化一个资源，要么是JSON，要么是PHP（PHP使用底层的JSON表示法的一个修改版本来进行序列化），然后使用客户端对象将资源从其序列化形式中检索回来。请注意，序列化资源将强制其完成下载（有关更多信息，请参阅 涡轮按钮）。在反序列化时，客户端会注入自己，因此此时检索相关资源将工作正常。

我还尽量在JSON方面与原始API响应格式非常接近，因此对资源进行JSON编码将得到与Mastodon API输出非常相似的结果（相同的键名等）。

$serializedAccount = json_encode($accout);

$deserializedAccount = $client->deserialize($serializedAccount);
echo $deserializedAccount->getId(); // your ID

未认证的端点

未认证的端点不使用访问令牌，但它们很少见。主要的一个是实例端点，我们在这里进行演示。它使用 涡轮按钮 中描述的技术，比一次性执行所有调用要快得多地获取实例信息。

$client = \Phediverse\MastodonRest\Client::build('mastodon.network', 'ACCESS_TOKEN');
$hosts = ['mastodon.xyz', 'icosahedron.website', 'sealion.club', 'cybre.space', 'toot.cat', 'toot.cafe'];

/** @var \Phediverse\MastodonRest\Resource\Instance[] $instances */
$instances = array_map(function($host) use ($client) { // requests are started here, in parallel!
    return $client->getInstance($host);
}, array_combine($hosts, $hosts));

foreach ($instances as $hostname => $instance) { // everything in this loop will finish around the same time
    echo $hostname . ($instance->isMastodon() ? (': ' . $instance->getName()) : ' is not a Mastodon instance') . "\n";
}

// we can also pull the name for the host we specified in client setup, as it's the default
echo "Default client: " . $client->getInstance()->getName() . "\n";

涡轮按钮

并行请求

在底层，客户端会尽量减少阻塞，只有在你请求需要HTTP响应的内容时才强制解析HTTP请求（好吧，HTTPS是默认的，除非你在一个主机名中指定了方案）。这可能看起来不是什么大问题，但这意味着如果客户端尽早知道这些请求，它将尽可能地并行化请求。所以尽早请求资源对象，并在你的应用程序中有其他事情要做时，尽可能晚地从那些资源对象中提取信息，这样事情就会神奇地变得更快！

我可能还会进一步调整以允许更直接地操作底层承诺，这样您就可以让系统知道当大量请求不需要按顺序解决时，可以获得更多速度。但这将是另一天的事情。

如果您想强制资源在完全下载之前阻塞，请调用其 resolve() 方法。该方法可以链式调用。

一些注意事项

1. 登录端点，无论是用于完成Auth Code授权还是通过用户名和密码登录，都不会进行异步操作，因为您将获得一个访问令牌。如果人们想要异步化这部分，那可以是以后的任务。
2. 异步运行通常只有一层深度；如果您在原始资源加载之前请求一个相关资源，您将阻塞，直到原始资源加载完成。我会（或某个其他贡献者）稍后修复这一点。

缓存

客户端缓存GET请求，包括引用相同的资源，如果存在多个对同一资源的请求，以避免简单地对服务器端进行重击。如果需要任何原因清除缓存，请使用$client->clearCache()；有关参数的信息请参阅代码。您还可以通过将Client调用中的$useCache参数设置为false来绕过请求的缓存。

一旦我添加了更新给定资源的方法，更新将自动刷新或删除缓存中的相关资源，具体取决于是否需要再次向服务器发送请求。

贡献

请随意分叉/PR，尽管我可能对代码风格（遵循PSR-1、PSR-2、PSR-4、PSR-7标准）或与性能相关的懒加载问题（如有疑问，请查看现有代码如何懒加载所有内容）吹毛求疵。

测试将及时构建；使用Guzzle的ClientInterface构建此库的Client类主要是为了模拟Mastodon的API，这样我们就可以在没有实例可用的情况下对客户端进行单元测试。

代码许可为MIT。我以任何有意义的方式都与Mastodon的主要开发团队无关。

您可以通过电子邮件iansltx@gmail.com（您应该这样报告安全问题...不要在公共问题跟踪器上...公共问题跟踪器适用于其他库相关的问题）联系我，或在Fediverse上找到我 @iansltx@social.targaryen.house。