Download the PHP package whitecube/winbooks-on-web-php-client without Composer

Winbooks On Web PHP Client

Installation

Usage

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.

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.

Specifying the folder

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

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

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

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, 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.

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.

To specify the amount of nested data you want (maxLevel parameter), you can pass it as a third param to the get method.

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.

Select (Projection Lists)

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

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

Where (Conditions)

Simple = conditions can be applied as follows:

For other comparison methods, use the common >, >=, < & <= symbols:

Or even more sofisticated operators (here's the full list of available operators):

Sometimes it is necessary to compare object model properties:

Order By

To get the results sorted in a certain way, use the orderBy($property, $direction) method.

Note: It is possible to chain multiple orderBy() calls in order to define more fine-grained results sorting.

Relations & Joins (Associations)

Most object models have their associations with sub-models defined in this package, making it easy to query relations with associated object models. Feel free to open a PR if we missed some of them.

The with($relation, $configurator) method allows to overwrite the default relation configuration by providing a callback function as second parameter:

For more advanced or unavailable relations, it is also possible to associate data using your own joins:

Limiting results & Pagination

Limiting the amount of queried results is often necessary in order to avoid endless requests. Just use the take($amount) method in order to limit the results to the desired amount:

In order to take the next results, you should first skip($amount) the previous results:

This basically is pagination, so we also added a shorthand method that combines both concepts in a more comprehensive straightforward way using the paginate($perPage, $page) method:

Inserting data

A generic way to insert data is by using the add($object_model, $code, $data) method:

You can also use the provided Model classes instead. These classes are named like the object models documented in the Winbooks On Web documentation.

Updating data

Deleting data

Tests

This project uses PEST for tests.

First, create a .env file from the .env.example and fill it with your API testing credentials.

To run the tests:

with code coverage (needs pcov or xdebug)

💖 Sponsorships

If you are reliant on this package in your production applications, consider sponsoring us! It is the best way to help us keep doing what we love to do: making great open source software.

Contributing

Feel free to suggest changes, ask for new features or fix bugs yourself. We're sure there are still a lot of improvements that could be made, and we would be very happy to merge useful pull requests.

Thanks!

Made with ❤️ for open source

At Whitecube we use a lot of open source software as part of our daily work. So when we have an opportunity to give something back, we're super excited!

We hope you will enjoy this small contribution from us and would love to Twitter for more updates!