PHP SDK

The Mobiscroll Connect PHP SDK provides a convenient way to integrate Mobiscroll Connect in PHP backends.

Setup

Install the package using Composer:

Composer

composer require mobiscroll/connect-php

Client Initialization

To use the SDK, initialize MobiscrollConnectClient with your client credentials.

Class: Mobiscroll\Connect\MobiscrollConnectClient

constructorMobiscrollConnectClient::__construct

Constructor arguments.

clientIdstring

Your Client ID obtained from the Mobiscroll Connect dashboard.

clientSecretstring

Your Client Secret obtained from the Mobiscroll Connect dashboard.

redirectUristring

Your application's redirect URI that matches the one configured in the Mobiscroll Connect dashboard.

Usage:

<?php

use Mobiscroll\Connect\MobiscrollConnectClient;

$client = new MobiscrollConnectClient(
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET',
    redirectUri: 'YOUR_REDIRECT_URI'
);

Methods

setCredentials

Sets the access token for the client. This is required before making any API calls that require authentication.

Method: client->auth()->setCredentials(tokens)

tokensTokenResponse

The token response object returned by client->auth()->getToken(code).

onTokensRefreshed

Registers a callback to be invoked whenever the SDK automatically refreshes the access token. Use this to persist the updated tokens so they survive future requests.

Method: client->onTokensRefreshed(callback)

callbackcallable(TokenResponse): void

A callable that receives the updated TokenResponse after a successful automatic token refresh.

Token Refresh

The PHP SDK handles token refresh automatically. When any API call returns a 401 Unauthorized response and the client has a refresh_token stored, the SDK will silently exchange it for a new access token and retry the original request — with no action required from your application.

When the refresh succeeds, the SDK invokes your onTokensRefreshed callback with the updated TokenResponse. You must register this callback and persist the new tokens, otherwise they will be lost between requests.

$client->onTokensRefreshed(function (TokenResponse $updatedTokens) {
    // Persist $updatedTokens in your database or session store
    // so the new access_token and refresh_token survive future requests
    $_SESSION['tokens'] = $updatedTokens->toArray();
});

If the refresh token itself is invalid or has been revoked, the SDK throws an AuthenticationError and the user must re-authorize.

Error Handling

All SDK methods throw exceptions that extend Mobiscroll\Connect\Exceptions\MobiscrollConnectException. You can catch the base exception or any of the specific subclasses.

Exception	HTTP Status	getCodeString()
AuthenticationError	401, 403	AUTHENTICATION_ERROR
ValidationError	400, 422	VALIDATION_ERROR
NotFoundError	404	NOT_FOUND_ERROR
RateLimitError	429	RATE_LIMIT_ERROR
ServerError	5xx	SERVER_ERROR
NetworkError	—	NETWORK_ERROR

ValidationError exposes a getDetails() method that returns field-level validation errors. RateLimitError exposes getRetryAfter() (seconds) and ServerError exposes getStatusCode().

use Mobiscroll\Connect\Exceptions\{
    AuthenticationError,
    ValidationError,
    RateLimitError,
    MobiscrollConnectException,
};

try {
    $events = $client->events()->list(['start' => new DateTime('2024-01-01')]);
} catch (AuthenticationError $e) {
    // Token expired or invalid — refresh manually or re-authorize the user
} catch (ValidationError $e) {
    // Invalid request parameters
    $details = $e->getDetails();
} catch (RateLimitError $e) {
    $retryAfter = $e->getRetryAfter(); // seconds
} catch (MobiscrollConnectException $e) {
    // Catch-all for any other SDK error
}

API

The client exposes resources that map directly to the API endpoints.

Auth

The client->auth() resource handles the OAuth authorization flow, including generating authorization URLs, exchanging codes for tokens, managing connection status, and disconnecting providers.

To localize the Connect pages, pass an optional lng (en, es, fr, ar) to generateAuthUrl, e.g. generateAuthUrl(userId: ..., lng: 'es'). When omitted, the UI falls back to the browser's Accept-Language header, then English; Arabic renders right-to-left.

🔐 OAuth API Reference

Calendars

The client->calendars() resource allows you to list available calendars from all connected providers (Google, Outlook, etc.). It corresponds to the /calendars endpoints.

📅 Calendars API Reference

Events

The client->events() resource provides methods to create, read, update, and delete calendar events across all connected accounts. It corresponds to the /events endpoints.

📅 Events API Reference