README

A PHP SDK for interacting with the Macloud API. This SDK provides a simple and secure way to make RESTful API requests with built-in signature authentication.

Features

Support for GET, POST, PATCH, PUT, and DELETE HTTP methods
Built-in SHA256 signature authentication
RESTful API design
JSON request/response format
Configurable timeout settings
Optional logging support

Requirements

PHP >= 5.5
Composer

Installation

Install the package via Composer:

composer require macloudapisdk/sdk

Configuration

Before using the SDK, you need to obtain the following credentials:

app_id: Your application ID (contact technical support to register an account and apply for API credentials)
app_secret: Your application secret key (used for signature generation)
base_api_url: The base API URL (e.g., http://api.local.com/V4/). Contact operations staff for the specific address.

Configuration Parameters

Parameter	Description	Required
`app_id`	Your assigned application ID	Yes
`app_secret`	Your assigned application secret, used for data signing	Yes
`base_api_url`	API base URL prefix	Yes
`timeout`	Request timeout in seconds (default: 10)	No
`log`	Enable SDK logging (default: false)	No
`logfileLinux`	Linux log file path (e.g., `/tmp/sdk.log`)	No

Usage

Basic Setup

error_reporting(E_ALL);
ini_set('display_errors', 'on');

require './vendor/autoload.php';

try {
    $config = [
        'app_id'       => getenv('SDK_APP_ID'),
        'app_secret'   => getenv('SDK_APP_SECRET'),
        'base_api_url' => getenv('SDK_API_PRE'),
        // 'log'          => true,           // Enable SDK logging
        // 'logfileLinux' => '/tmp/sdk.log', // Linux log file path
    ];
    $sdk = new \macloudapisdk\Sdk($config);
    
    // Your API calls here...
    
} catch(\Exception $e) {
    var_dump("code: " . $e->getCode() . " message: " . $e->getMessage());
}

GET Request

$request = [
    'url' => 'test.sdk.get',
    'query' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
    'body' => [],
];
$result = $sdk->get($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

POST Request

$request = [
    'url' => 'test.sdk.post',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->post($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

PATCH Request

$request = [
    'url' => 'test.sdk.patch',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->patch($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

PUT Request

$request = [
    'url' => 'test.sdk.put',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->put($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);
print_r("\n");

DELETE Request

$request = [
    'url' => 'test.sdk.delete',
    'query' => [],
    'body' => [
        "page" => 1,
        "pagesize" => 10,
        "data" => [
            "name" => "name名称",
            "domain" => "baidu.com",
        ],
    ],
];
$result = $sdk->delete($request);
$jsonData = json_decode($result, 1);
print_r("api: ".$request['url']."\n");
print_r("raw: ".$result."\n");
print_r($jsonData);

Signature Algorithm

The SDK uses SHA256 signature authentication to ensure data integrity during transmission:

Client-side: Uses SHA256 algorithm to sign the base64-encoded parameters combined with app_secret. Each request includes the signature.
Server-side: Uses the same algorithm to sign the received parameters and compares it with the provided signature to verify authenticity.

This ensures that data cannot be tampered with during transmission.

Important Notes

URI and Query Parameters: For all requests, URI and GET parameters are separated. For example, if the URL is https://api.local.com/V4/version?v=1, the v=1 parameter must be passed through the query parameter in the request array.
Return Value: Each API call returns a raw string response. You can decode it using json_decode() to get the parsed JSON data.
Error Handling: Always wrap SDK calls in try-catch blocks to handle exceptions properly.

API Response Format

The SDK returns the raw response string. The API typically returns JSON format, which can be decoded using json_decode($result, true) to get an associative array.

Support

For API credentials and base URL information, please contact:

Technical Support: For app_id and app_secret registration
Operations Staff: For the specific API base URL

macloudapisdk / sdk

Maintainers

Package info

Statistics

Security