qbnk / qbank3api-phpwrapper
A PHP-Wrapper for QBank 3's API. Provides a simple way to communicate with QBank 3 from PHP.
Requires
- php: >=8.1
- ext-json: *
- guzzlehttp/guzzle: ^7.4
- kamermans/guzzle-oauth2-subscriber: ^1.0
- psr/log: ~3.0
- psr/simple-cache: ^3.0
- symfony/cache: ^6.3
Requires (Dev)
- mockery/mockery: ^1.3.5
- phpunit/phpunit: ^8.5
- roave/security-advisories: dev-latest
Suggests
- monolog/monolog: Great logging alternative.
- dev-master
- 7.0.13
- 7.0.12
- 7.0.11
- 7.0.10
- 7.0.9
- 7.0.8
- 7.0.7
- 7.0.6
- 7.0.5
- 7.0.4
- 7.0.3
- 7.0.2
- 7.0.1
- 7.0.0
- 6.3.2
- 6.3.1
- 6.2.1
- 6.2.0
- 6.1.5
- v6.1.4
- v6.1.3
- v6.1.2
- 6.1.1
- 6.1.0
- 6.0.1
- 6.0.0
- 5.x-dev
- 5.1.6
- 5.1.5
- 5.1.4
- 5.1.3
- 5.1.2
- 5.1.1
- 5.1.0
- 5.0.3
- 5.0.2
- v5.0.1
- v5.0.0
- v4.9.2
- v4.9.1
- v4.9.0
- v4.8.0
- v4.7.0
- v4.6.0
- v4.5
- v4.4.1
- v4.4
- 4.3
- v4.2
- v4.1
- v4.0.1
- v4.0.0
- 3.4.13
- 3.4.12
- 3.4.11
- 3.4.10
- 3.4.9
- 3.4.8
- 3.4.7
- 3.4.6
- 3.4.5
- v3.4.4
- v3.4.3
- v3.4.2
- v3.4.1
- v3.4
- v3.3
- v3.2.1
- v3.2
- v3.1.1
- v3.1
- v3.0.1
- v3.0
- 2.1.10
- 2.1.9
- v2.1.8
- v2.1.7
- v2.1.6
- v2.1.5
- v2.1.4
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.15
- v2.0.14
- v2.0.13
- v2.0.12
- v2.0.11
- v2.0.10
- v2.0.9
- v2.0.8
- v2.0.7
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0
- 1.4.x-dev
- v1.4.2
- v1.4.1
- v1.4.0
- 1.3.x-dev
- v1.3.4
- v1.3.3
- v1.3.2
- v1.3.1
- v1.3.0
- v1.2.14
- v1.2.13
- v1.2.12
- v1.2.11
- v1.2.10
- v1.2.9
- v1.2.8
- v1.2.7
- v1.2.6
- v1.2.5
- v1.2.4
- v1.2.3
- v1.2.2
- v1.2.1
- 1.2.0
- 1.1.x-dev
- v1.1.0
- 1.0.x-dev
- v1.0.14
- v1.0.13
- v1.0.12
- v1.0.11
- v1.0.10
- 1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- v0.14.1
- v0.14.0
- v0.13.0
- v0.12.1
- v0.12.0
- v0.11.3-alpha
- v0.11.2-alpha
- v0.11.1-alpha
- v0.11.0-alpha
- v0.10.5-alpha
- v0.10.4-alpha
- v0.10.3-alpha
- v0.10.2-alpha
- v0.10.1-alpha
- v0.10.0-alpha
- v0.9.0-alpha
- v0.8.0-alpha
- v0.7.0-alpha
- v0.6.4-alpha
- v0.6.3-alpha
- v0.6.2-alpha
- v0.6.1-alpha
- v0.6.0-alpha
- v0.5.1-alpha
- v0.5.0-alpha
- v0.4.2-alpha
- v0.4.1-alpha
- v0.4.0-alpha
- v0.3.0-alpha
- v0.2.0-alpha
- v0.1.8-alpha
- v0.1.7-alpha
- v0.1.6-alpha
- v0.1.5-alpha
- v0.1.4-alpha
- v0.1.3-alpha
- v0.1.2-alpha
- v0.1.1-alpha
- dev-add-templateId-zero
- dev-get-original-with-correct-deploymentsite
- dev-backport/v6-symfony-caching
- dev-backport/signedUrlEnable
- dev-addedPropertyTypeOptions
- dev-backport/upload-signed-urls
- dev-backport/remove-body-get-delete-requests3
- dev-backport/remove-body-get-delete-requests
- dev-bugfix/signedUrl
- dev-backport/v6-signed-urls
- dev-backport/addPropertyType
- dev-updatePropertyType
- dev-feature/expose-basePath-function
- dev-addUserToGroups
- dev-bugfix/namespaced-cache-keys
- dev-bugfix/updateCredentials-port
- dev-feature/php-81
- dev-backport/omit-type-definitions-client
- dev-bugfix/user-swapping
- dev-backport/user-swapping
- dev-backport/user-search-3.4
- dev-backport/user-search
- dev-hotfix/baseurl-issue-fix
This package is auto-updated.
Last update: 2024-11-04 08:21:07 UTC
README
Introduction
QBank 3 API PHP Wrapper is a library that makes it easy to use the QBank 3 API directly from PHP. No need to handle the connections or interpreting the results yourself.
Installation
Install via composer.
{
"require": {
"qbnk/qbank3api-phpwrapper": "dev-master"
}
}
Upgrading
Each major version comes with backwards incompatible changes. See specific instructions in UPGRADING.md
Usage
This documentation presumes that you have a firm grasp of the concepts in QBank. If you do not or perhaps want a reference to lean on, please read the articles in the Knowledge Base for QBank. The Knowledge Base is found at: support.qbank.se
Instantiate the wrapper by creating a new QBankApi
. The QBankApi
class constructor takes three arguments of which
two are required. The first is the URL to the api of the QBank you want to connect to. If the QBank is hosted by QBNK
the domain of the QBank is sufficient; otherwise the full URL to the API endpoint is needed.
The second argument is a Credentials
object which contains all necessary information to authenticate against QBank.
These are as follows:
- Client id - A unique id used to identify the caller. Issued by QBNK and usually per organisation.
- Username - A username of a user in the QBank that you are connecting to. The access to content and actions are determined by this.
- Password - The users password.
To get a client id issued, please contact us at support@qbank.se
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
Searching
Searching is essential to find Media
in QBank. Usually one would have at least some criteria for listing Media
but
even when wanting to display everything searching is the way to go. To find every Media
in QBank you would execute
a search with no parameters. With no filtering options set, the search would match everything just like the *
wildcard
in the terminal or similar.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$results = $qbankApi->search()->search(new Search());
var_dump(count($results)); // Prints: int(50)
But why did we only get 50 results when our QBank contains thousands of Media
? The simple answer is that searches are
paginated to not flood you with data and return to you in a reasonable amount of time. The default page size is 50. It
is pretty simple to get several pages of results with the number of results of your choosing in each.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search();
$search->setLimit(10);
for ($i = 0; $i < 5; $i++) {
$search->setOffset($i * $search->getLimit());
$results = $qbankApi->search()->search($search);
var_dump(count($results));
}
/*
Prints:
int(10)
int(10)
int(10)
int(10)
int(10)
*/
The results of an executed Search
is a SearchResult
object. This is merely a wrapper class around an array of
Media
objects, but with some extra information tacked on. One of these are the very useful getTotalHits()
method.
With it you can search with a reasonable limit and still print out the number of total results. You can then write code
to fetch more results when needed.
SearchResult
also implements Iterator
so that you can loop over it just as a regular array. This makes it easy to
display your results.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$results = $qbankApi->search()->search(new Search());
var_dump(count($results)); // Prints: int(50)
var_dump($results->getTotalHits()); // Prints: int(34814);
foreach ($results as $media) { //Prints a list of 50 media id and name combinations
echo 'ID: '.$media->getMediaId().' Name: '.$media->getName()."\n";
}
Searching with criteria
Usually we have some default criteria such as Media
belonging to specific Category
or maybe deployed to a specific
site. This is easily done by adding criteria to the Search
object.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search()
->setCategoryIds([1, 2]);
->setDeploymentSiteIds([1])
;
$results = $qbankApi->search()->search($search);
You may also want to filter on a Property
. This is done by adding a PropertyCriteria
to your search object. This
will however not get those set in the SearchResult
. To get Property
values for Media
in a SearchResult
a
PropertyRequest
has to be added to the Search
object.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$search = new Search()
->setProperties([
new PropertyRequest()->setSystemName('property1'),
new PropertyCriteria()->setSystemName('property2')
])
;
$results = $qbankApi->search()->search($search);
There are many more possibilities to filter your searching by and this has just been a demonstration of some of the most
used ones. Browse through the setters in the Search
class and it should be pretty obvious what is possible.
Events
Events are calls that are made to report back to QBank that something has happened worthy of statistics collection, an event. Statistics for events are shown in QBank.
To be able to report an event a session id must be obtained. The session id identifies the acting user over a period of time. To obtain a session id, a session source must be provided. The session source identifies the source of the event (eg. frontend, api, app). To get a session source issued, contact support@qbank.se.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$sessionId = $qbankApi->events()->session(SESSION_SOURCE_ID, 'identifierhash', '127.0.0.1', 'CustomApp/1.0', USER_ID);
$qbankApi->events()->view($sessionId, MEDIA_ID);
To report custom events (the ones not covered by the methods available), just use the custom()
method. These will be
displayed in the statistics alongside the other.
<?php
use QBNK\QBank\API\QBankApi;
use QBNK\QBank\API\Credentials;
use QBNK\QBank\API\Model\Search;
$credentials = new Credentials('CLIENT_ID', 'myUsername', 'myPassword');
$qbankApi = new QBankApi('customer.qbank.se', $credentials);
$sessionId = $qbankApi->events()->session(SESSION_SOURCE_ID, 'identifierhash', '127.0.0.1', 'CustomApp/1.0', USER_ID);
$qbankApi->events()->custom($sessionId, MEDIA_ID, 'Some custom event');
It is also possible to report external usage eg. from a CMS or other. This is not shown in the statistics, but in the
media detail in QBank. This provides a good overview of where a media is used. Of course you can also remove the usage
report if it is no longer in use. See the methods addUsage()
and removeUsage()
respectively.