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 vkcom/vk-php-sdk

3. 初始化

使用以下代码创建VKApiClient对象

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

您还可以使用以下方式初始化VKApiClient，使用不同的API版本和不同的语言

$vk = new VKApiClient('5.101');

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

4. 授权

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

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 和密钥。您需要覆盖此方法。

corponat / vk-php-sdk

维护者

详细信息