README

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

此库使用VK API JSON Schema创建。它可以在此处找到。它使用VK API 版本 5.131。

1. 前提条件

PHP 8.1

2. 安装

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

composer require vkcom/vk-php-sdk

3. 初始化

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

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

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

$vk = new VKApiClient('5.131');

$vk = new VKApiClient('5.131', \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\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\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\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 和密钥。您需要覆盖此方法。

vkcom / vk-php-sdk

维护者

详细信息