PHPackages                             serwisant/serwisant-api - 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. serwisant/serwisant-api

ActiveLibrary[API Development](/categories/api)

serwisant/serwisant-api
=======================

API client for https://serwisant.online service

3.5.3(6mo ago)339111Apache-2.0PHPPHP >=7.2

Since Jul 19Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/SerwisantOnline/serwisant-api-php-sdk)[ Packagist](https://packagist.org/packages/serwisant/serwisant-api)[ Docs](https://github.com/SerwisantOnline/serwisant-api-php-sdk)[ RSS](/packages/serwisant-serwisant-api/feed)WikiDiscussions master Synced 4w ago

READMEChangelogDependencies (1)Versions (40)Used By (1)

Serwisant Online API PHP SDK
============================

[](#serwisant-online-api-php-sdk)

Requirements:
-------------

[](#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
---------------------

[](#word-about-versioning)

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

```
"require": {
    "serwisant/serwisant-api": "3.4.*"
},

```

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

Braking changes are described in [CHANGELOG](/CHANGELOG.md)

***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:
------

[](#usage)

### 1. Access token and schema factory.

[](#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.

```
use Serwisant\SerwisantApi;

// get own client and secret by creating an application via webpage
$access_token = new SerwisantApi\AccessTokenOauth('client', 'secret', 'public', (new SerwisantApi\AccessTokenContainerEncryptedFile('some_string_as_encryption_key')));

$api = new SerwisantApi\Api();
$api->setAccessToken($access_token);
```

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:

```
CREATE TABLE IF NOT EXISTS access_token
(
    namespace varchar(64)  NOT NULL,
    token     varchar(255) NOT NULL,
    refresh   varchar(255),
    expiry    int(11)      NOT NULL,
    PRIMARY KEY (namespace)
);
```

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

[](#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.

```
use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

/* please note __typename at each type - it's required for proper typecast */
$query = '
query($token: String!) {
    repairByToken(token: $token) {
      __typename
      displayName
      status {
        __typename
        displayName
      }
    }
}';

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $api->publicQuery()->newRequest()->set($query, ['token' => 'abc-def'])->execute()->fetch();

echo $repair->displayName;
echo $repair->status->displayName;
```

### 3. Prepared queries and mutations

[](#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.

```
use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

// tell SerwisantApi\Api where to look for files with queries, mutations, etc. It can be done once, in 1. example.
$api->addLoadPath('/full/path/to/queries/SchemaPublic');

/* @var SerwisantApi\Types\SchemaPublic\PublicQuery $query */
$query = $api->publicQuery();

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $query->repairByToken('abc-def'); // abc-def is a token form repair fetched from user input

echo $repair->displayName;
echo $repair->status->displayName;
```

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.

```
query repairByToken($token: String!, $basic: Boolean = false, $complete: Boolean = false) {
    repairByToken(token: $token) @include(if: $basic) {
        __typename
        status {
            __typename
            displayName
        }
    }
    repairByToken(token: $token) @include(if: $complete) {
        __typename
        rma
        serial
        vendor
        model
    }
}
```

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

```
$query = $api->publicQuery();
$repair = $query->repairByToken('abc-def', ['basic' => true])
```

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

```
$query = $api->publicQuery();
$repair = $query->repairByToken('abc-def', ['complete' => true])
```

### 4. Batched query

[](#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.

```
use Serwisant\SerwisantApi;

/* @var SerwisantApi\Api $api */

/* please note __typename at each type - it's required for proper typecast */
$query = '
query($token: String!) {
  repair: repairByToken(token: $token) {
    __typename
    displayName
  }
  me: viewer {
    __typename
    employee {
      __typename
      displayName
    }
  }
}';

$result = $api->publicQuery()->newRequest()->set($query, ['token' => 'abc-def'])->execute();

/* @var SerwisantApi\Types\SchemaPublic\Repair $repair */
$repair = $result->fetch('repair');

/* @var SerwisantApi\Types\SchemaPublic\Viewer $me */
$me = $result->fetch('me');

echo $repair->displayName;
echo $me->subscriber;
```

***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:

```
$result = $api->publicQuery()->newRequest()->setFile('myBatchedQuery.graphql', ['token' => $secret_token])->execute();
$repair = $result->fetch('repair');
$me = $result->fetch('me');
```

Changelog
---------

[](#changelog)

Changelog in [CHANGELOG](/CHANGELOG.md)

Contributions
-------------

[](#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:

```
php ./bin/introspection.php

```

Development
-----------

[](#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.  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
---------

[](#licencing)

Apache Licence See LICENCE for full licence information.

Author
------

[](#author)

Arkadiusz Kuryłowicz <hello(at)sugarmice.software>

###  Health Score

44

—

FairBetter than 91% of packages

Maintenance66

Regular maintenance activity

Popularity17

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~80 days

Recently: every ~70 days

Total

39

Last Release

199d ago

Major Versions

2.0 → 3.0.02020-04-21

### Community

Maintainers

![](https://www.gravatar.com/avatar/c133733b9dc4349ccd002631b60c013bbb0beea2bcb973f6c80ff4a49424ab7d?d=identicon)[arekk](/maintainers/arekk)

---

Top Contributors

[![arekk](https://avatars.githubusercontent.com/u/992535?v=4)](https://github.com/arekk "arekk (133 commits)")

---

Tags

api-clientcomposergraphql-clientpackagephpsdkserwisant

### Embed Badge

![Health badge](/badges/serwisant-serwisant-api/health.svg)

```
[![Health](https://phpackages.com/badges/serwisant-serwisant-api/health.svg)](https://phpackages.com/packages/serwisant-serwisant-api)
```

###  Alternatives

[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3661.2M46](/packages/tencentcloud-tencentcloud-sdk-php)[neuron-core/neuron-ai

The PHP Agentic Framework.

2.0k496.1k34](/packages/neuron-core-neuron-ai)[avalara/avataxclient

Client library for Avalara's AvaTax suite of business tax calculation and processing services. Uses the REST v2 API.

528.3M7](/packages/avalara-avataxclient)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

252.5k](/packages/eslazarev-wildberries-sdk)[files.com/files-php-sdk

Files.com PHP SDK

2478.1k](/packages/filescom-files-php-sdk)[aimeos/prisma

A powerful PHP package for integrating media related Large Language Models (LLMs) into your applications

1942.4k4](/packages/aimeos-prisma)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)