<?php
/**
* MyClientAPI class
* `````````````````
* Version 2015-09-30
*
* This class provides a PHP sample providing access to the API features as
* described on the http://www.myclientglobal.com/external_forms_and_api/ page.
* Please visit this page for more information about the MyClient API.
*
* Example
* ```````
* require_once('MyClientAPI.php');
*
* $myclient = new MyClientAPI(
* "https://url-to-the-myclient-installation/", // SAMPLE ONLY
* "b5dd5a0c962c733f669309247db3f5ee264b5ced" // SAMPLE ONLY
* );
* $success = $myclient->createResellerOffice(
* "example company", "john", "doe", "johndoe@example.com", "server1"
* );
*
* if ($success) ...
*
* License
* ```````
* Copyright (c) 2013-2015, MyClientGlobal.com Ltd
*
* Permission to use, copy, modify, and/or distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
* copyright notice and this permission notice appear in all copies.
*
*/
class MyClientAPI {
protected $m_url;
protected $m_auth_token;
protected $m_timeout;
public $lastErrorCode;
public $lastErrorMessage;
public $lastRawResponse;
/**
* Construct a new MyClientAPI class instance
* @param url $server_url The full URL to your MyClient installation
* @param string $auth_token Authentication token
* @param int $timeout Request timeout in seconds (optional)
*/
public function __construct($server_url, $auth_token, $timeout = 5) {
$this->m_url = rtrim($server_url, '/').'/';
$this->m_auth_token = $auth_token;
$this->m_timeout = max(1, intval($timeout)); /* seconds */
/* Verify URL */
if (! filter_var($this->m_url, FILTER_VALIDATE_URL)) {
trigger_error("Error: MyClientAPI constructed with malformed URL");
}
/* Verify auth token */
if (strlen($this->m_auth_token) != 40 /* strlen(sha1(X)) */) {
trigger_error("Error: MyClientAPI constructed with invalid token");
}
$this->setError("", 0);
}
/**
* Determine if the remote MyClient installation is currently responding to API queries.
*
* @return bool
*/
public function testConnection() {
return $this->doRequest(array(
'action' => 'ping'
));
}
/**
* Make a request to an Automated Event Handler event.
*
* @param string $api The call to make, as specified in the Automated Event Handler
* @param string $optional_Username
* @param string $optional_BackupsetID
* @param string $optional_BackupJob
* @return bool Success / failure
*/
public function triggerEvent(
$api,
$optional_Username=null,
$optional_BackupsetID=null,
$optional_BackupJob=null
) {
$params = array(
'action' => 'event',
'api' => ''.$api
);
if (! is_null($optional_Username)) {
$params['action'] = 'event-username';
$params['loginname'] = ''.$optional_Username;
if (! is_null($optional_BackupsetID)) {
$params['action'] = 'event-backupset';
$params['backupset'] = ''.$optional_BackupsetID;
if (! is_null($optional_BackupJob)) {
$params['action'] = 'event-backupjob';
$params['backupset'] = ''.$optional_BackupJob;
}
}
}
return $this->doRequest($params);
}
/**
* Create a new reseller office on the MyClient installation.
*
* @param string $office_name The company name for the new reseller's office
* @param string $operator_first_name System Operator's first name
* @param string $operator_last_name System Operator's last name
* @param string $operator_email System Operator's email address, used to log in with
* @param string $default_server Default server for new accounts created by this reseller.
* Must be a valid server name
* @param string $Optional_operator_password
* @return bool Success / failure
*/
public function createResellerOffice(
$office_name,
$operator_first_name,
$operator_last_name,
$operator_email,
$default_server,
$Optional_operator_password=null
) {
$params = array(
"action" => "create-reseller-office",
"office-name" => "".$office_name,
"operator-first-name" => "".$operator_first_name,
"operator-last-name" => "".$operator_last_name,
"operator-email" => "".$operator_email,
"default-server" => "".$default_server
);
if (! is_null($Optional_operator_password)) {
$params['operator-password'] = ''.$Optional_operator_password;
}
return $this->doRequest($params);
}
/**
* Internal method to make a MyClient API request.
*
* @param array $params Data to be POSTed to the API endpoint
* @return bool
*/
protected function doRequest($params) {
/* Perform request */
$ctx = stream_context_create(array(
"http" => array(
"method" => "POST",
"timeout" => intval($this->m_timeout),
"user_agent" => "MyClientAPI/1.0",
"content" => http_build_query(
array( "auth" => $this->m_auth_token ) + $params
)
)
));
$response = file_get_contents(
$this->m_url . "API/external.php", false, $ctx
);
$this->lastRawResponse = $response;
/* Verify response */
$this->setError();
if (
($response !== false) &&
(($response_arr = @json_decode($response, true)) !== false) &&
array_key_exists('status', $response_arr) &&
array_key_exists('message', $response_arr)
) {
$this->setError(
''.$response_arr['message'],
intval($response_arr['status'])
);
}
return (
$this->lastErrorCode >= 200 &&
$this->lastErrorCode <= 299
);
}
/**
* Internal method to set the MyClientAPI class instance error state.
*
* @param string $message
* @param int $code
*/
protected function setError($message = "Communication Error", $code = 400) {
$this->lastErrorCode = intval($code);
$this->lastErrorMessage = "".$message;
}
}