README

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

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

1. 前提条件

PHP 7.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.80');

$vk = new VKApiClient('5.80', 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 = array(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 = array(VK\OAuth\Scopes\VKOAuthGroupScope::MESSAGES);
$state = 'secret_state_code';
$groups_ids = array(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 = array(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 = array(VK\OAuth\Scopes\VKOAuthGroupScope::MESSAGES);
$state = 'secret_state_code';
$groups_ids = array(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, array(
    'user_ids'  => array(1, 210700286),
    'fields'    => array('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, array(
    '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, array(
    '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, array(
  '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 事件处理程序有两个参数：群组 ID 和密钥。您需要重写此方法。

tristamoff / vk-php-sdk

维护者

详细信息