Skip to content

Client

Jump to bottom Edit New page
Emmanuel D edited this page Mar 24, 2017 · 10 revisions

Namespace

SugarAPI\SDK\Client

Interface

SugarAPI\SDK\Client\Interfaces\ClientInterface

Abstracts

There are two Abstract Clients included in the Rest PHP Client Framework.

Name Description
SugarAPI\SDK\Client\Abstracts\AbstractClient A generic client implementation, that can be extended and altered for use with any REST API
SugarAPI\SDK\Client\Abstracts\AbstractSugarClient Extends the AbstractClient and implements all required logic to work strictly with the Sugar 7 REST API. Autoload's all of the Endpoint Objects for Sugar's API, as outlined in the Endpoints documentation.

Methods

The following method descriptions align with the abstract implementation on the AbstractClient Class.

setServer()

Set the server property on the Client object. Server property is used to define the API Url Property.

Arguments

Name Type Description
$server string The server URL where the API resides

Returns

Type Description
self The current Client Object for method chaining

setCredentials()

Set the Authentication Credentials being used by the Client Object to authenticate to the API

Arguments

Name Type Description
$credentials array Array of credentials required for the API

Returns

Type Description
self The current Client Object for method chaining

login()

Login to the API using the configured credentials on the Client and store the authentication token.

Returns

Type Description
boolean Whether or not Login succeeded

Exceptions

Type Description
SugarAPI\SDK\Exception\Authentication\AuthenticationException For any errors returned from Login API Endpoint

logout()

Logout of the API, and remove the current authentication token from the Client

Returns

Type Description
boolean Whether or not the Logout succeeded

Exceptions

Type Description
SugarAPI\SDK\Exception\Authentication\AuthenticationException For any errors returned from Logout API Endpoint

refreshToken()

Refresh the authentication token used by the client

Returns

Type Description
boolean Whether or not the Refresh succeeded

Exceptions

Type Description
SugarAPI\SDK\Exception\Authentication\AuthenticationException For any errors returned from Token Refresh API Endpoint

registerEndpoint()

Register an Endpoint Object to a function/method name on the Client

Arguments

Name Type Description
$function string The name of the function/method that will be called on the Client Object to initialize the Endpoint
$Endpoint string The full Namespaced Class name of the Endpoint object

Returns

Type Description
self The current Client Object for method chaining

Exceptions

Type Description
SugarAPI\SDK\Exception\Endpoint\EndpointException If Endpoint Class does not implement SugarAPI\SDK\Endpoint\Interfaces\EPInterface

getServer()

Get the configured server on the Client

Returns

Type Description
string The current server property configured on the Client

getAPIUrl()

Get the configured API Url on the Client

Returns

Type Description
string The current API Url property configured on the Client

getCredentials()

Get the configured credentials on the Client

Returns

Type Description
array The current authentication credentials configured on the Client

setToken()

Set the authentication token to be used by the Client Object to authenticate requests to the API. Login method should pass token to this method, upon successful authentication to the API

Arguments

Name Type Description
$token mixed The authentication token to be used by the Client

Returns

Type Description
self The current Client Object for method chaining

getToken()

Get the configured authentication token on the Client

Returns

Type Description
array The current authentication token configured on the Client

authenticated()

Check if Client is currently authenticated to the API

Returns

Type Description
boolean Whether or not the Client is currently authenticated to the API

::storeToken()

Static method to store an authentication token for later use by the Client object. Default uses Late Static Binding to store a token on the Client Object for subsequent uses of the same Client in the same PHP process

Arguments

Name Type Description
$token mixed The authentication token for the Client that is to be stored
$client_id string A unique client ID to reference the client and store the token against

Returns

Type Description
boolean Whether or not storage of the token completed

::getStoredToken()

Static method to get the stored authentication token for a particular Client

Arguments

Name Type Description
$client_id string The unique client ID

Returns

Type Description
mixed Returns NULL if no token is retrieved, otherwise returns the authentication token

::removeStoredToken()

Static method to remove an authentication token from storage

Arguments

Name Type Description
$client_id string The unique client ID

Returns

Type Description
boolean Whether or not removal of the token from storage succeeded

AbstractSugarClient

There are a few alterations done to the AbstractSugarClient that tailor the Client for usage with the Sugar 7 REST API.

Methods

setCredentials()

Set credentials utilizes the same Array argument, however instead of merely setting the $credentials property with the entire value passed into the method, it merges the passed in array with those values configured on the Client by default. This allows for passing just username and password.

When credentials are set on the Client using this method, the current client_id property in the credentials array, is used to retrieve a stored Token and if one is found, will set the Token on the Client so that authentication to the REST API works without having to re-authenticate. See the [Authentication](Authentication# storage) documentation for further details.

login()

Utilizes the [oauth2Token](SugarEndpoints# oauth2token) Endpoint to login to a Sugar REST API.

logout()

Utilizes the [oauth2Logout](SugarEndpoints# oauth2logout) Endpoint to logout of a Sugar REST API.

refreshToken()

Utilizes the [oauth2Refresh](SugarEndpoints# oauth2refresh) Endpoint to refresh the Client's token.

setVersion()

This method was added to support [Sugar REST API Endpoint Versioning](https://support.sugarcrm.com/Documentation/Sugar_Developer/Sugar_Developer_Guide_7.7/Integration/Web_Services/v10/Extending_Endpoints/# Endpoint_Versioning). By default the version of the Client is set to 10, since the standard REST API Url is $server/rest/v10/. When you call setVersion() you will alter the configured API URL to be whatever number is passed in.

Arguments

Name Type Description
$version int The API version you wish to use. Passing in 12, results in $server/rest/v12/ as the API URL.

Returns

Type Description
self The current Client Object for method chaining

getVersion()

Since the version can be changed for the API Url, this method was added to check what Version the Client is currently using.

Returns

Type Description
int The current API Version

::storeToken()

Static method to store an authentication token for later use by the Client object. Default 'storage' uses Late Static Binding to store a token on the Client Object for subsequent uses of the same Client in the same PHP process. Since the array of credentials is used for storage, the token is stored hierarchically client_id > platform > username i.e.

array(
  '' => array(
        '' => array(
             '' => $token
         )
   )
);

This allows for multiple tokens to be stored for the same client, if the client needs to utilize multiple user's or different platforms when connecting to the Sugar REST API.

Arguments

Name Type Description
$token mixed The authentication token for the Client that is to be stored
$credentials array The same set of credentials used to configure the Client for authentication

Returns

Type Description
boolean Whether or not storage of the token completed

::getStoredToken()

Static method to get the stored authentication token for a particular Client

Arguments

Name Type Description
$credentials array The unique client ID

Returns

Type Description
mixed Returns NULL if no token is retrieved, otherwise returns the authentication token

::removeStoredToken()

Static method to remove an authentication token from storage

Arguments

Name Type Description
$credentials array The set of credentials used for the Client.

Returns

Type Description
boolean Whether or not removal of the token from storage succeeded

Implementations

There is one included Client implementation with the REST PHP Client.

Name Description
SugarAPI\SDK\SugarAPI Extends the AbstractSugarClient, for quick use to access any Sugar REST API

Please see the SugarAPI Client documentation for further instructions on usage.

Add a custom footer
Clone this wiki locally