PHPackages                             whitecube/winbooks-on-web-php-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. whitecube/winbooks-on-web-php-client

ActiveLibrary[API Development](/categories/api)

whitecube/winbooks-on-web-php-client
====================================

A PHP Wrapper for the Winbooks On Web REST API.

v1.1.1(5y ago)72.3k2PHPPHP ^7.1|^8.0CI failing

Since Apr 2Pushed 5y ago2 watchersCompare

[ Source](https://github.com/whitecube/winbooks-on-web-php-client)[ Packagist](https://packagist.org/packages/whitecube/winbooks-on-web-php-client)[ RSS](/packages/whitecube-winbooks-on-web-php-client/feed)WikiDiscussions master Synced 6d ago

READMEChangelog (4)Dependencies (4)Versions (5)Used By (0)

Winbooks On Web PHP Client
==========================

[](#winbooks-on-web-php-client)

[![Tests](https://github.com/whitecube/winbooks-on-web-php-client/workflows/Tests/badge.svg)](https://github.com/whitecube/winbooks-on-web-php-client/workflows/Tests/badge.svg)

Installation
------------

[](#installation)

```
composer require whitecube/winbooks-on-web-php-client

```

Usage
-----

[](#usage)

### Authentication

[](#authentication)

Before you can do anything, you have to authenticate with the API. This is done with OAuth 2.0, so you will need the e-mail and the Exchange Token provided by Winbooks on Web. You can get those by following [these steps](https://help.winbooks.be/display/DEV/Grant+an+access+to+your+license).

When you have those ready to go, you can use them to ask the API to grant you an Access Token and a Refresh Token. The Access Token is necessary to authorise every request, and the Refresh Token is used to get a new Access Token if it has expired.

When you create an instance of the Winbooks client, you can give it the Access Token and the Refresh Token right away if you have them. If you don't, you can simply call `authenticate($email, $exchange_token)` afterwards, which will grant you those tokens which you should then save and reuse the next time you make an instance of the client.

```
use Whitecube\Winbooks\Winbooks;

// $access_token and $refresh_token can be null if you do not have them yet
$winbooks = new Winbooks($access_token, $refresh_token);

if(! $winbooks->authenticated()) {
    [$access_token, $refresh_token] = $winbooks->authenticate($email, $exchange_token);
    // Store the tokens somewhere safe
}

// Now you can start using the API
```

### Specifying the folder

[](#specifying-the-folder)

You can set the folder once and it will be used for all subsequent requests.

```
$winbooks->folder('TEST_FOLDER');

$winbooks->get(/*...*/)
```

### Getting data

[](#getting-data)

All getter methods will return the JSON data directly from WoW, already decoded and wrapped into Object Model instances when possible.

#### Returning all data

[](#returning-all-data)

To get all results from an object model, use the `all($object_model, $max_level = 1)` method.

```
$customers = $winbooks->all('Customers');
```

> **Warning**: Depending on the size of your dataset and the server's memory limit, `all()` can cause critical server errors since its results are not paginated. The API wrapper will continue fetching objects until Winbook's REST API indicates everything has been transferred. This is quite a big issue, documented in [Winbook's documentation](https://help.winbooks.be/display/DEV/1.+Query+Data#id-1.QueryData-E.Chunkingdata), which will not be fixed in this package until Winbook's REST API will implement proper pagination options. If you need pagination, it is preferable to [use queries](#querying-data).

#### Returning data for a single object model

[](#returning-data-for-a-single-object-model)

To get a single result from an object model, use the `get($object_model, $code, $max_level = 1)` method.

> **Note**: you can substitute $code for the ID if you have it.

```
$vlad = $winbooks->get('Customer', 'VLADIMIR');
// With ID
$vlad = $winbooks->get('Customer', '4713a22f-ebc0-ea11-80c7-0050s68cc4a2');
```

To specify the amount of nested data you want ([`maxLevel` parameter](https://help.winbooks.be/display/DEV/1.+Query+Data)), you can pass it as a third param to the get method.

```
$vlad = $winbooks->get('Customer', 'VLADIMIR', 3);
```

#### Querying data

[](#querying-data)

Listing object models is often more complicated than just fetching all results. To get more refined results, it is recommended to use the Query Builder provided in this package. It will make API interactions more precise and it is therefore a great way to enhance performance.

Queries can be send using the `query($object_model, $query_builder, $max_level = 1)` method.

```
$results = $winbooks->query('Customers', function($query) {
    // Build your query...
    $query->select('Id', 'Code')->orderBy('Created', 'desc')->paginate(20);
});
```

##### Select (Projection Lists)

[](#select-projection-lists)

To only project a few properties instead of full object models, it is recommended to use the `select(...$properties)` method:

```
$query->select('Id', 'VatApplicable', 'Memo');
```

In order to perform a specific kind of select, use the `selectOperator($operator, ...$properties)` method:

```
use Whitecube\Winbooks\Query\Operator;

$query->selectOperator(Operator::distinct(), 'Id', 'VatApplicable', 'Memo');
```

##### Where (Conditions)

[](#where-conditions)

Simple `=` conditions can be applied as follows:

```
$query->where('Id', '4713a22f-ebc0-ea11-80c7-0050s68cc4a2');
```

For other comparison methods, use the common `>`, `>=`, `