The Beeper Desktop PHP library provides convenient access to the Beeper Desktop REST API from any PHP 8.1.0+ application.
The REST API documentation can be found on developers.beeper.com.
To use this package, install via Composer by adding the following to your application's composer.json:
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/beeper/desktop-api-php.git"
}
],
"require": {
"beeper/desktop-api-php": "^6.0"
}
}This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.
<?php use BeeperDesktop\Client; $client = new Client( accessToken: getenv('BEEPER_ACCESS_TOKEN') ?: 'My Access Token' ); $page = $client->chats->search( accountIDs: [ 'matrix', 'discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc' ], includeMuted: true, limit: 3, type: 'single', ); var_dump($page->id);
It is recommended to use the static with constructor Dog::with(name: "Joey")
and named parameters to initialize value objects.
However, builders are also provided (new Dog)->withName("Joey").
List methods in the Beeper Desktop API are paginated.
This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:
<?php use BeeperDesktop\Client; $client = new Client( accessToken: getenv('BEEPER_ACCESS_TOKEN') ?: 'My Access Token' ); $page = $client->messages->search( accountIDs: ['discordgo', 'local-whatsapp_ba_EvYDBBsZbRQAy3UOSWqG0LuTVkc'], limit: 10, query: 'oauth', ); var_dump($page); // fetch items from the current page foreach ($page->getItems() as $item) { var_dump($item->id); } // make additional network requests to fetch items from all pages, including and after the current page foreach ($page->pagingEachItem() as $item) { var_dump($item->id); }
When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of BeeperDesktop\Core\Exceptions\APIException will be thrown:
<?php use BeeperDesktop\Core\Exceptions\APIConnectionException; use BeeperDesktop\Core\Exceptions\RateLimitException; use BeeperDesktop\Core\Exceptions\APIStatusException; try { $accounts = $client->accounts->list(); } catch (APIConnectionException $e) { echo "The server could not be reached", PHP_EOL; var_dump($e->getPrevious()); } catch (RateLimitException $e) { echo "A 429 status code was received; we should back off a bit.", PHP_EOL; } catch (APIStatusException $e) { echo "Another non-200-range status code was received", PHP_EOL; echo $e->getMessage(); }
Error codes are as follows:
| Cause | Error Type |
|---|---|
| HTTP 400 | BadRequestException |
| HTTP 401 | AuthenticationException |
| HTTP 403 | PermissionDeniedException |
| HTTP 404 | NotFoundException |
| HTTP 409 | ConflictException |
| HTTP 422 | UnprocessableEntityException |
| HTTP 429 | RateLimitException |
| HTTP >= 500 | InternalServerException |
| Other HTTP error | APIStatusException |
| Timeout | APITimeoutException |
| Network error | APIConnectionException |
Certain errors will be automatically retried 2 times by default, with a short exponential backoff.
Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.
You can use the maxRetries option to configure or disable this:
<?php use BeeperDesktop\Client; // Configure the default for all requests: $client = new Client(requestOptions: ['maxRetries' => 0]); // Or, configure per-request: $result = $client->accounts->list(requestOptions: ['maxRetries' => 5]);
Request parameters that correspond to file uploads can be passed as a resource returned by fopen(), a string of file contents, or a FileParam instance.
<?php use BeeperDesktop\Core\FileParam; // Pass a string with filename and content type: $contents = file_get_contents('/path/to/file'); // Pass a string with filename and content type: $response = $client->assets->upload( file: FileParam::fromString($contents, filename: '/path/to/file', contentType: '…'), ); // Pass in only a string (where applicable) $response = $client->assets->upload(file: '…'); // Pass an open resource: $fd = fopen('/path/to/file', 'r'); try { $response = $client->assets->upload( file: FileParam::fromResource($fd, filename: '/path/to/file', contentType: '…'), ); } finally { fclose($fd); }
You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:
Note: the extra* parameters of the same name overrides the documented parameters.
<?php $accounts = $client->accounts->list( requestOptions: [ 'extraQueryParams' => ['my_query_parameter' => 'value'], 'extraBodyParams' => ['my_body_parameter' => 'value'], 'extraHeaders' => ['my-header' => 'value'], ], );
If you want to explicitly send an extra param, you can do so with the extra_query, extra_body, and extra_headers under the request_options: parameter when making a request, as seen in the examples above.
To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using client.request, like so:
<?php $response = $client->request( method: "post", path: '/undocumented/endpoint', query: ['dog' => 'woof'], headers: ['useful-header' => 'interesting-value'], body: ['hello' => 'world'] );
This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs may change at any time.
This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.
PHP 8.1.0 or higher.