roydejong / superoffice-webapi
Unofficial PHP SDK for SuperOffice WebAPI
Requires
- php: >=8.2
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- ext-openssl: *
- guzzlehttp/guzzle: ~7
- lcobucci/jwt: ^4.0
- spatie/guzzle-rate-limiter-middleware: ^2.0
Requires (Dev)
- php-coveralls/php-coveralls: ~2.2
- phpunit/phpunit: ~9.0
This package is auto-updated.
Last update: 2024-10-28 16:04:07 UTC
README
Unofficial PHP SDK for SuperOffice Web API
This library provides a PHP SDK for the SuperOffice REST WebAPI, specifically targeting CRM Online (SuperOffice Cloud).
This library's functionality is currently limited to Projects, Appointments and Documents, but it should be easy enough to expand it to other SuperOffice types as well if you need them - just note that some work is needed.
Installation
The recommended way to install this library is with Composer, by adding the superoffice-webapi
package as a dependency to your application:
composer require softwarepunt/superoffice-webapi
Configuration
You will need to be registered as a SuperOffice developer, and you must have a registered app to receive the necessary client credentials.
Initializing
When initializing the client, you must pass a Config
object:
<?php use SoftwarePunt\SoWebApi\Client; use SoftwarePunt\SoWebApi\Config; $config = new Config(); $config->environment = "sod"; $config->tenantId = "Cust12345"; // ... $client = new Client($config);
You can also set the configuration values by array:
<?php new Config([ 'environment' => "sod", 'tenantId' => "Cust12345" // ... ]);
Options
Available configuration options:
Authentication (OAuth / SuperId)
If you are targeting Online CRM, you must use OAuth to aquire a BEARER
access token for the web api.
Local installations must use BASIC
/ SOTICKET
authentication methods (currently not supported by this library).
Redirect user to authorization screen
After setting your configuration, you can ask the client to generate the OAuth authorization URL:
<?php use SoftwarePunt\SoWebApi\Client; $client = new Client(/* $config */); $redirectUrl = $client->getOAuthAuthorizationUrl("optional_state");
This will generate a redirect URL like https://env-name.superoffice.com/login/common/oauth/authorize?client_id=...
.
When you redirect the user to this URL, they will be asked to authorize your application and grant access to their account.
Request access token
Once the user authorizes your app, you will receive a callback request on your configured requestUri
.
You can can exchange the code
parameter in the request for an access token:
<?php $tokenResponse = $client->requestOAuthAccessToken($_GET['code']);
The TokenResponse
object contains the following keys:
Your application is responsible for storing these tokens.
Refresh access token
You can use the refresh_token
to generate new access tokens, as long as the user hasn't revoked your application's access:
<?php $tokenResponse = $client->refreshOAuthAccessToken($tokenResponse->refresh_token);
This response will be a TokenResponse
object, but with refresh_token
set to null
.
Verify JWT
To comply with SuperOffice requirements, your application should verify the JWT from each token response (so when requesting a new token or refreshing a token):
<?php // ... request or refresh access token to get a $tokenResponse $jwtIsValid = $tokenResponse->validateAndVerifyJwt($config); if (!$jwtIsValid) { // ... something is fishy, bail }
This will validate the token (valid issuer, not expired) and verify it against the appropriate SuperOffice certificate for the configured environment.
Configure access token
You must explicitly set the access token you want to use with the client before performing any requests:
<?php use SoftwarePunt\SoWebApi\Client; // Optionally pass it directly in the client constructor: $client = new Client(/* $config */, $tokenResponse->access_token); // Or set it on an existing client instance: $client->setAccessToken($tokenResponse->access_token);
Tenant status check
You can perform a tenant status check to retrieve information about the customer's environment. You can use this to determine whether the environment is available or not, and get a load-balanced target URL for your API requests.
"Each tenant has a status page where you can check its state to ensure your application remains stable and responds accordingly."
<?php use SoftwarePunt\SoWebApi\Client; // Authentication is not required, but "tenantId" must be set in your config. $client = new Client(/* $config */); $tenantStatus = $client->getTenantStatus(); // If the target environment is offline, do not proceed: if (!$tenantStatus->IsRunning) die("Tenant offline!"); // Tenant status gives a load-balanced base URL you can set on the client: $client->setBaseUrl($tenantStatus->Endpoint);
The TenantStatus
object contains the following keys:
Collections
This library exposes different collections of API entities that you can interact with. Each collection can be accesed via the client instance, e.g. $client->projects()
.