README

PHP 库，用于与 VK API 交互，包括 OAuth 2.0 授权和 API 方法。完整的 VK API 功能文档可以在这里找到。

此库是使用 VK API JSON Schema 创建的。它可以在这里找到。它使用 VK API 版本 5.101

1. 前提条件

• PHP 7.1 或更高版本

2. 安装

可以通过运行以下命令使用 Composer 安装 VK PHP SDK：

composer require vkphp/vk-php-sdk

3. 初始化

使用以下代码创建 VKApiClient 对象：

$vk = new VK\Client\VKApiClient();

您还可以使用不同的 API 版本和不同的语言初始化 VKApiClient，如下所示：

$vk = new VKApiClient('5.101');

$vk = new VKApiClient('5.101', VK\Client\Enums\VKLanguage::ENGLISH);

4. 授权

该库提供了基于 OAuth 2.0 协议在 vk.com API 中实现的基于用户的授权流程。请在开始之前阅读完整的文档。

4.1. 授权码流程

OAuth 2.0 授权码流程允许从服务器端调用方法。

此流程包括两个步骤 - 获取授权码和用代码交换访问令牌。首先，您应该通过使用以下方法将用户重定向到授权页面来获取 "code"（手动用户访问 和 手动社区访问）：

首先创建 VKOAuth 对象

$oauth = new VK\OAuth\VKOAuth();

4.1.1. 要获取 用户访问密钥，使用以下命令：

$oauth = new VK\OAuth\VKOAuth();
$client_id = 1234567;
$redirect_uri = 'https://example.com/vk';
$display = VK\OAuth\VKOAuthDisplay::PAGE;
$scope = [VK\OAuth\Scopes\VKOAuthUserScope::WALL, VK\OAuth\Scopes\VKOAuthUserScope::GROUPS];
$state = 'secret_state_code';

$browser_url = $oauth->getAuthorizeUrl(VK\OAuth\VKOAuthResponseType::CODE, $client_id, $redirect_uri, $display, $scope, $state);

4.1.2. 或者，如果您想获取 社区访问密钥，使用

$oauth = new VK\OAuth\VKOAuth();
$client_id = 1234567;
$redirect_uri = 'https://example.com/vk';
$display = VK\OAuth\VKOAuthDisplay::PAGE;
$scope = [VK\OAuth\Scopes\VKOAuthGroupScope::MESSAGES];
$state = 'secret_state_code';
$groups_ids = [1, 2];

$browser_url = $oauth->getAuthorizeUrl(VK\OAuth\VKOAuthResponseType::CODE, $client_id, $redirect_uri, $display, $scope, $state, $groups_ids);

用户访问密钥 和 社区访问密钥 在作用域数组中具有不同的值

成功授权后，用户的浏览器将被重定向到指定的 redirect_uri。同时，代码将作为 GET 参数发送到指定的地址

https://example.com?code=CODE

然后使用此方法获取访问令牌

$oauth = new VK\OAuth\VKOAuth();
$client_id = 1234567;
$client_secret = 'SDAScasd'
$redirect_uri = 'https://example.com/vk';
$code = 'CODE';

$response = $oauth->getAccessToken($client_id, $client_secret, $redirect_uri, $code);
$access_token = $response['access_token'];

redirect_uri 应该是用于获取代码的第一步中使用的 URL。

4.2. 隐式流程

与授权码流程不同，此流程提供临时访问密钥。

有关用户访问密钥 和 社区访问密钥 的更多信息。

使用隐式流程获取访问权限的第一步是创建 VKOauth 对象

$oauth = new VK\OAuth\VKOAuth();

4.2.1. 要获取 用户访问密钥，使用以下命令：

$oauth = new VK\OAuth\VKOAuth();
$client_id = 1234567;
$redirect_uri = 'https://example.com/vk';
$display = VK\OAuth\VKOAuthDisplay::PAGE;
$scope = [VK\OAuth\Scopes\VKOAuthUserScope::WALL, VK\OAuth\Scopes\VKOAuthUserScope::GROUPS];
$state = 'secret_state_code';
$revoke_auth = true;

$browser_url = $oauth->getAuthorizeUrl(VK\OAuth\VKOAuthResponseType::TOKEN, $client_id, $redirect_uri, $display, $scope, $state, null, $revoke_auth);

如果您想强制用户获取访问权限，请将 revoke_auth 设置为 true。

4.2.2. 或者，如果您想获取 社区访问密钥，使用

$oauth = new VK\OAuth\VKOAuth();
$client_id = 1234567;
$redirect_uri = 'https://example.com/vk';
$display = VK\OAuth\VKOAuthDisplay::PAGE;
$scope = [VK\OAuth\Scopes\VKOAuthGroupScope::MESSAGES];
$state = 'secret_state_code';
$groups_ids = [1, 2];

$browser_url = $oauth->getAuthorizeUrl(VK\OAuth\VKOAuthResponseType::TOKEN, $client_id, $redirect_uri, $display, $scope, $state, $groups_ids);

参数与授权码流程类似

成功授权后，用户的浏览器将被重定向到指定的 redirect_uri。同时，访问令牌将作为片段参数发送到指定的地址

用户访问密钥 将为

https://example.com#access_token=533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400&user_id=8492&state=123456

而对于 社区访问密钥

https://example.com#access_token_XXXXXX=533bacf01e11f55b536a565b57531ad114461ae8736d6506a3&expires_in=86400

access_token 是您的新访问令牌。
expires_in 是访问令牌的存活时间（以秒为单位）。
user_id 是用户标识符。
state 是来自 authorize 方法的字符串。
access_token_XXXXXX 是社区访问令牌，其中 XXXXXX 是社区标识符。

5. API 请求

您可以在这里找到 VK API 方法的完整列表。

5.1. 请求示例

调用方法 users.get 的示例

$vk = new VK\Client\VKApiClient();
$response = $vk->users()->get($access_token, [
    'user_ids'  => [1, 210700286],
    'fields'    => ['city', 'photo'],
]);

5.2. 将照片上传到私信

在开始之前，请阅读完整手册。

调用 photos.getMessagesUploadServer 以接收上传地址

$vk = new VK\Client\VKApiClient();
$address = $vk->photos()->getMessagesUploadServer('{access_token}');

然后使用 upload() 方法将文件发送到上一步中收到的 upload_url 地址

$vk = new VK\Client\VKApiClient();
$photo = $vk->getRequest()->upload($address['upload_url'], 'photo', 'photo.jpg');

您将获得包含 server、photo、hash 字段的 JSON 对象。要保存照片，请使用这三个参数调用 photos.saveMessagesPhoto

$vk = new VK\Client\VKApiClient();
$response_save_photo = $vk->photos()->saveMessagesPhoto($access_token, [
    'server' => $photo['server'],
    'photo'  => $photo['photo'],
    'hash'   => $photo['hash'],
]);

然后，您可以使用最后响应中的 owner_id 和 id 参数创建已上传照片的附件。

5.3. 上传视频文件

在开始之前，请阅读完整手册。

调用 video.save 以获取视频上传服务器地址

$vk = new VK\Client\VKApiClient();
$address = $vk->video()->save($access_token, [
    'name' => 'My video',
]);

通过调用 upload() 方法将文件发送到之前收到的 upload_url

$vk = new VK\Client\VKApiClient();
$video = $vk->getRequest()->upload($address['upload_url'], 'video_file', 'video.mp4');

上传后，视频将经过一段时间处理。

6. 群组更新

6.1. 长轮询

为您的群组启用长轮询并指定通过调用以下 API 方法应跟踪哪些事件

$vk = new VK\Client\VKApiClient();
$vk->groups()->setLongPollSettings($access_token, [
  'group_id'      => 159895463,
  'enabled'       => 1,
  'message_new'   => 1,
  'wall_post_new' => 1,
]);

重写 VK\CallbackApi\VKCallbackApiHandler 类中的方法以处理事件

class CallbackApiMyHandler extends VK\CallbackApi\VKCallbackApiHandler {
    public function messageNew($object) {
        echo 'New message: ' . $object['body'];
    }
    
    public function wallPostNew($object) {
        echo 'New wall post: ' . $object['text'];
    }
}

要开始监听 LongPoll 事件，创建您的 CallbackApiMyHandler 类的实例，VK\CallbackApi\LongPoll\VKCallbackApiLongPollExecutor 类的实例，并调用 listen() 方法

$vk = new VK\Client\VKApiClient();
$access_token = 'asdj4iht2i4ntokqngoiqn3ripogqr';
$group_id = 159895463;
$wait = 25;

$handler = new CallbackApiMyHandler();
$executor = new VK\CallbackApi\LongPoll\VKCallbackApiLongPollExecutor($vk, $access_token, $group_id, $handler, $wait);
$executor->listen();

参数 wait 是等待期。

在调用函数 listen() 时，您还可以指定您想要接收数据的事件的编号。默认值是最后一个事件的编号。

示例

$vk = new VK\Client\VKApiClient();
$access_token = 'asdj4iht2i4ntokqngoiqn3ripogqr';
$group_id = 159895463;
$timestamp = 12;
$wait = 25;

$executor = new VK\CallbackApi\LongPoll\VKCallbackApiLongPollExecutor($vk, $access_token, $group_id, $handler, $wait);
$executor->listen($timestamp);

6.2. 回调 API

CallbackApi 处理器将等待来自 VK 的事件通知。一旦发生事件，您将收到通知并能够处理它。更多信息这里。

要开始使用 Callback API，您需要在社区页面“管理社区”选项卡下进行配置。

第一步是确认您的域名。VK 向您的服务器发送带有事件类型 confirmation 的请求，您需要发送一个确认字符串。对于其他类型的事件，您需要发送 ok 字符串。

请查看这个示例

class ServerHandler extends VK\CallbackApi\Server\VKCallbackApiServerHandler {
    const SECRET = 'ab12aba';
    const GROUP_ID = 123999;
    const CONFIRMATION_TOKEN = 'e67anm1';

    function confirmation(int $group_id, ?string $secret) {
        if ($secret === static::SECRET && $group_id === static::GROUP_ID) {
            echo static::CONFIRMATION_TOKEN;
        }
    }
    
    public function messageNew(int $group_id, ?string $secret, array $object) {
        echo 'ok';
    }
}

$handler = new ServerHandler();
$data = json_decode(file_get_contents('php://input'));
$handler->parse($data);

要处理事件，您需要重写 VK\CallbackApi\Server\VKCallbackApiServerHandler 类中的方法，如上所示。

confirmation 事件处理器有 2 个参数：群组 ID 和密钥。您需要重写此方法。