Download the PHP package serwisant/serwisant-api without Composer

Serwisant Online API PHP SDK

Requirements:

• PHP 7.2 or higher
• ext-json
• ext-curl
• ext-mbstring

optional:

• ext-openssl for AccessTokenContainerEncryptedFile
• PDO, sqlite, mysql for AccessTokenContainerSqlite/AccessTokenContainerPDO

Word about versioning

Versioning of SDK is very important. It looks like 3.<major>.<minor>, eg. 3.4.0. When you're including SDK into your composer config, it's strongly recommended to set major version as fixed, eg:

It's important, because of typed queries and mutations. If schema will change, arguments passed to queries and mutations will change as well. It can be new required arguments or even order of arguments can change. In that case SDK will e released with incremented major version. If you'll decide to upgrade, it can break your application.

Braking changes are described in CHANGELOG

YOU HAVE BEING WARNED.

There is a single exception to that. internal schema is not for public consumption. Breaking changes will be excluded from above rules.

Usage:

1. Access token and schema factory.

First of all, prepare an instance of SerwisantApi\Api for later use. It should be shared across whole application. You can set it as singleton result, put it into a dependency injection container, etc. Don't create more than one SerwisantApi\Api instance - it's useless and ineffective.

4th argument in AccessTokenOauth is an access token cache.

It's optional, but STRONGLY recommended for performance reasons, because it's persisting access token between requests until it expire and avoid create a new token for every HTTP request. Check out other cache containers:

• SerwisantApi\AccessTokenContainerEncryptedFile - caches data in encrypted local files, it can be used on single-server application with access to local filesystem
• SerwisantApi\AccessTokenContainerFile - caches data in plain-text local files, it can be used on single-server application with access to local filesystem. Please note - it's insecure to use it on shared hosting because plain access tokens can be saved in /tmp directory accessible for other users.
• SerwisantApi\AccessTokenContainerSession - in session container, it should be used only with AccessTokenOauthUserCredentials and store user specific access token (fetched using login and password) - please don't use it for only key-secret access tokens.
• SerwisantApi\AccessTokenContainerSqlite - SQLite database based cache, easy to set-up. Require PDO and php_pdo_sqlite extensions. When using this container you don't need to worry about database - it will be created automatically, on first use.

• SerwisantApi\AccessTokenContainerPDO - generic PDO token container. Please note: you must create a database/table before first use. Table schema:

• ...build your own, use SerwisantApi\AccessTokenContainer abstract class

PLEASE NOTE - your application can be banned if you'll be creating to many access tokens, i.e. for every single request.

2. Basic example with inline query

Put a query string into variable and execute it directly. The most important is to add to each requested object in your query magic field __typename. This gets from GraphQL server a object name and wrap in PHP class. When you'll get a result it will be a PHP object (or array of objects) having all properties, etc.

Missing magic field for any type will result in exception.

3. Prepared queries and mutations

Above example can be called in other way.

Please create in your application's root directory, folder named queries\SchemaPublic

Next please put a content of your query string in queries\SchemaPublic\repairByToken.graphql file. File name is important. It must be an exact query name as it's seen in schema. File extension must be .graphql.

This is exactly the same query you've assigned to variable in 1. example.

Probably you want to ask: why SDK doesn't provide files with all available queries and mutations?

That's because we have no idea what fields/objects you want to get from schema. Possibility to limit a fetched data is one of the most important feature of GraphQL. With pre-defined query files you'll lose a possibility to decide by yourself.

HINT Using a GraphQL syntax you can have multiple query variants in single .graphql file and select proper one using query variables. Look on below example. Let's have repairByToken.graphql. Put attention on multiple repairByToken and @include(if: ..) tag.

Call to get only a repair status (query will be executed fast:

Call to get complex information about repair (query execution can take more time):

4. Batched query

One of cool GraphQL feature is possibility to put into a single request more than one query. You need to give uniq name for each query, and once it's executed result will contain booth responses.

Use batches for performance reasons. Batching queries reduce HTTP traffic.

HINT you can put a batched query (let's assume it's above query) into a query folder under a custom name and call it like:

Changelog

Changelog in CHANGELOG

Contributions

Pull requests are welcome.

Do not edit or update any files in src/Serwisant/SerwisantApi/Types - all files/classes in that directory are auto-generated and changes will be overwritten.

To generate missing types, queries, mutations use bin/introspection.php script:

Development

SDK available as composer package on packagist.org:

• update composer.json with new version
• commit and push changes to master
• git tag 3.0.x
• git push origin --tags

There are environment variables to test/develop SDK against development server. Set:

• set SERWISANT_HOST to eg. http://127.0.0.1:3000 to change base hostname for OAuth token endpoint, OAuth token revoke endpoint and GraphQL schemas.

• set HTTP_TIMEOUT to eg. 10 to set 10s connection timeout to API. Default is 30s.

Licencing

Apache License See LICENCE for full licence information.

Author

Arkadiusz Kuryłowicz <sms(at)kurylowicz.info>