-
Notifications
You must be signed in to change notification settings - Fork 29
Client
#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.
###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 documentation for further details.
####login() Utilizes the oauth2Token Endpoint to login to a Sugar REST API.
####logout() Utilizes the oauth2Logout Endpoint to logout of a Sugar REST API.
####refreshToken() Utilizes the oauth2Refresh Endpoint to refresh the Client's token.
####setVersion()
This method was added to support Sugar REST API 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.