README

What is this?
Basic usage
Contexts
- Available contexts
API service
- Lazy connection
- Remember configuration and connection

What is this?

This package gives you possibility to easy integrate your system with vBulletin 5 API using simple methods calls.

Tested with vB 5.2

Basic usage

    use Signes\vBApi\Api;
    use Signes\vBApi\ApiConfig;
    use Signes\vBApi\Connector\Provider\GuzzleProvider;
    
    $apiConfig = new ApiConfig($apiKey, $uniqueId, $clientName, $clientVersion, $platformName, $platformVersion);
    $apiConnector = new GuzzleProvider('http://example.com/my-forum/');
 
    $api = new Api($apiConfig, $apiConnector);
    
    $response = $api->callRequest('user.fetchByEmail', ['email' => 'test@example.com']);

First of all create your API configuration file which should include information's like:
- vBulletin API key - you can find it in vBulletin control panel, under API section. |
- Unique ID - Unique id is used to identity your client and platform name, it can be any unique string. Be careful, if you will change unique ID your request will be recognized as request from new API client and new API client ID will be returned. |
- Client name - Your client name.
- Client version - Your client version.
- Platform name - Your platform name.
- Platform version - Your platform version.
```
use Signes\vBApi\ApiConfig;
$apiConfig = new ApiConfig($apiKey, $uniqueId, $clientName, $clientVersion, $platformName, $platformVersion);
```
When configuration object is ready, next step is to initiate connection provider. This provider is responsible for communication between your application and vB forum.

By default you can use included Guzzle provider but before you will do this, you should require guzzlehttp/guzzle package in composer. Guzzle provider required forum URL in constructor with trailing slash.
```
use Signes\vBApi\Connector\Provider\GuzzleProvider;
$apiConnector = new GuzzleProvider('http://example.com/my-forum/');
```
If this is not good enough, you can provide own connection class, just implement Signes\vBApi\Connector\ConnectorInterface interface.
After that you are ready to prepare API service, which required Signes\vBApi\ApiConfig and Signes\vBApi\Connector\ConnectorInterface objects.
```
use Signes\vBApi\Api;
$api = new Api($apiConfig, $apiConnector);
```

When API service is initialized, you can call any API resource.

$response = $api->callRequest('user.fetchByEmail', ['email' => 'test@example.com']);
$response = $api->callRequest('site.getSiteStatistics', []);

Contexts

Contexts gives you possibility to encapsulation logic into single class. Under the hood contexts also uses raw vB API requests.
Every context must extend Signes\vBApi\Context\Context class and can required different parameters in constructor.

Example code:

    use Signes\vBApi\Api;
    use Signes\vBApi\ApiConfig;
    use Signes\vBApi\Connector\Provider\GuzzleProvider;
    use Signes\vBApi\Context\User\FetchCurrentUserInfo;
    use Signes\vBApi\Context\User\Login;
    
    $apiConfig = new ApiConfig($apiKey, $uniqueId, $clientName, $clientVersion, $platformName, $platformVersion);
    $apiConnector = new GuzzleProvider('http://example.com/my-forum/');
    $api = new Api($apiConfig, $apiConnector);
    
    $currentLoggedInUserContext = new FetchCurrentUserInfo();
    $loginUserContext = new Login('adminUsername', 'adminPassword');
    
    $meFirst = $api->callContextRequest($currentLoggedInUserContext);
    $api->callContextRequest($loginUserContext);
    $meSecond = $api->callContextRequest($currentLoggedInUserContext);
    
    echo $meFirst['username'] // "Guest"
    echo $meSecond['username'] // "adminUsername"

Context should handle information about request method type, API request type and should return all required parameters by vB for given request.
For your custom context you can also overwrite parseResponse method to return expected format, not raw vB API response.

Available contexts

User
- Register
- Login
- Fetch current logged in user data
- Fetch user data by email
more contexts soon ...

API service

What do API service for you:

send init request to retrieve access token, secret, api version and client id for future requests,
remember your identity (when you send valid login request, every future requests will be called as this logged in user),
prepare signature for every request and include every required by vBulletin parameters,

If you want to integrate with multiple vBulletin instances, you can use API service as a registry. If instance is not remembered null will be returned.

use Signes\vBApi\Api;
(new Api($apiConfig, $apiConnector))->rememberInstance('myInstanceName');
(new Api($apiConfigSecond, $apiConnectorSecond))->rememberInstance('myOtherInstance');

$firstInstance = Api::getInstance('myInstanceName');
$secondInstance = Api::getInstance('myOtherInstance');

Lazy connection

API service constructor has third parameter $lazy with default true value. This parameter determine moment of init request.

If it is set to true init request will be send during the first callRequest method call. So if you provided incorrect configuration you will learn about it until now.

If it is set to false init request will be send when API service instance is created

Remember configuration and connection

It is possible to keep information about ApiConfig between PHP requests and it is strongly recommend to do that on production. To do that you can use any of your cache services. Just store ApiConfig in cache, and for future use it instance.

That gives you one more benefit, when you login on user account, this information will be remembered in ApiConfig and you do not have to call login request for some period of time (depends of your cache expiration).

Credits

Pawel Grzesiecki - Developer (http://signes.pl/) MIT License

signes / vbulletin-api-php

Maintainers

Details