Download the PHP package echo-five/sparky-api-client-php without Composer

Sparky API Client PHP

A PHP client library for the Sparky API.

Menu

• Requirements
• Installation
  • How to install?
  • How to update?
  • How to remove?
• Get started
• Features
  • Simple request vs Signed request
  • Debugging
• Available methods
  • Request
  • Get Response
  • Get Response Status
  • Get Response Headers
  • Get Response Data
  • Get Response Messages
  • Get Sent
  • Get Sent Headers
  • Get Sent Payload
  • Get cURL Info
  • Debug Start
  • Debug Stop
  • Debug Get
  • Debug Reset
  • Accept Unsafe Certificates
• License

Requirements

PHP 8.3 or higher with cURL, JSON, Sodium and Ctype extensions

Installation

How to install?

This package can be installed via Composer:

How to update?

Use the following command to update this package only:

How to remove?

This package can be uninstalled via Composer:

Get started

Prerequisites

• The library has been installed via Composer.
• You have a valid API Key.
• You have a valid API Signature Key (to "sign" the request, see here).

Create a new blank PHP file and copy the code below:

This example is stored in the project and can be downloaded here: GetStartedSimpleRequest.php

Features

Simple request vs Signed request

The library allows two types of requests:

• Simple requests (unsigned)
  The request is validated only using your API key.
• Signed requests
  Your request is signed using asymmetric cryptography.
  This allows to verify both the authenticity and integrity of the data.

Signed requests, although a bit slower, are therefore more secure than simple requests.

How it works

• When you create an API key on the platform, a cryptographic key pair is generated as well.
  • The public key is stored on the API side and linked to your account.
  • The private key (the API Signature Key) is shown to you once.
    • The system does not store it and cannot regenerate it.
      You must keep it secure.
• You use the API Signature Key to sign your requests before they are sent.
• The system verifies each signature using your registered public key.
• If the signature is invalid, the request is not processed.

Signing requests is very straightforward!
The only thing to do is to provide your API Signature Key when you instantiate the library.
Then all requests will be automatically signed!

This example is stored in the project and can be downloaded here: GetStartedSignedRequest.php

IMPORTANT

• Store your API Key and API Signature Key securely (environment variables, secrets manager, etc.).
• Never share your API Key or API Signature Key, and never commit them to version control.

Debugging

Troubleshooting an API can sometimes be challenging.
The library includes a debugging mode to help you better understand how requests are built and sent.

The debugging mode allows to:

• See the time consumption of each request.
• See how many requests were executed.
• See the execution order of the requests.

Using the debugging mode is very easy!
Just start it at a specific breakpoint and stop it at another.

See Available methods section for more debugging options.
This example is stored in the project and can be downloaded here: GetStartedDebugging.php

Here is an example of the debugging information:

Available methods

Request

This method allows to make an API request.

request(string $requestType, string $requestEndpoint, array <$requestParams>, string <$requestMode>)

• The requestType argument defines the HTTP method to use.
  Allowed values are GET, POST, PUT, PATCH, and DELETE.
  This argument is mandatory.

• The requestEndpoint argument defines the endpoint to call.
  This is a URI, e.g.: /endpoint or /api/v1/mirror
  This argument is mandatory.

• The requestParams argument defines the data to send to the endpoint.
  This is a key/value array, by default no data is sent.
  For GET and DELETE: sent as query string parameters.
  For POST, PUT, PATCH: sent as request body.
  This argument is optional.

• The requestMode argument defines the body encoding format.
  Allowed values are JSON (default), FORM, and HTTP.
  Only applicable for POST, PUT, and PATCH requests.
  This argument is optional.

This method returns the class instance itself, not the result of the request.
The request result must be retrieved using another method (getResponse).
For convenience, this method is chainable.

Example:

Get Response

This method allows to get the response of the request.

getResponse(bool <$object>)

• The object argument defines if the request response must be returned as object or not.
  The API replies in JSON format, so the response is a raw JSON string.
  The object argument allows to get a PHP object instead of a raw JSON string.
  The object argument is set to true by default.

Usage examples:

This method returns a raw JSON string or a PHP object, depending on the passed argument.
The request response is always a full API response.
Here is an example:

Get Response Status

This method allows to directly get the [status] property of the request response.
The status is the HTTP status code associated with the response.

getResponseStatus()

This method always returns an int.

Usage example:

Get Response Headers

This method allows to get the response headers.

getResponseHeaders(bool <$array>)

• The array argument defines if the headers must be returned as array or not.
  The array argument allows to get a parsed associative array instead of a raw headers string.
  The array argument is set to true by default.

This method returns a parsed associative array or a raw headers string, depending on the passed argument.

Usage examples:

Get Response Data

This method allows to directly get the [data] property of the request response.

getResponseData()

This method always returns a PHP object.

Usage example:

Get Response Messages

This method allows to directly get the [messages] property of the request response.

getResponseMessages()

This method always returns a PHP array.

Usage example:

Get Sent

This method allows to get the complete sent request.

getSent(bool <$object>)

• The object argument defines if the sent request must be returned as object or not.
  The object argument allows to get a PHP object instead of a raw string.
  The object argument is set to true by default.

This method returns a raw string or a PHP object, depending on the passed argument.
The sent request includes the method, endpoint, headers, and payload.

Usage examples:

Get Sent Headers

This method allows to get the sent headers.

getSentHeaders(bool <$array>)

• The array argument defines if the headers must be returned as array or not.
  The array argument allows to get a parsed associative array instead of a raw headers string.
  The array argument is set to true by default.

This method returns a parsed associative array or a raw headers string, depending on the passed argument.

Usage examples:

Get Sent Payload

This method allows to get the sent payload.

getSentPayload(bool <$object>)

• The object argument defines if the payload must be returned as object or not.
  The object argument allows to get a PHP object instead of a raw string.
  The object argument is set to true by default.

This method returns a raw string or a PHP object, depending on the passed argument.

Usage examples:

Get cURL Info

This method allows to get the cURL request information.
Each request is made using the PHP cURL extension, and this method returns the result of curl_getinfo().
See the official PHP.net documentation for details.

getCurlInfo()

This method always returns a PHP array.

Usage example:

Debug Start

This method allows to start the debugging mode.
Every request executed after this method call will be taken into account for the debugging.

debugStart()

This method returns the class instance itself.
For convenience, this method is chainable.

Example:

Debug Stop

This method allows to stop the debugging mode.
Every request executed after this method call will not be taken into account for the debugging.

debugStop()

This method returns the class instance itself.
For convenience, this method is chainable.

Example:

Debug Get

This method allows to get the result of the debugging data.
This method call doesn't stop the debugging mode, so it can be called every time needed.
This is just a debugging output at the time "t".

debugGet()

This method returns a PHP array.

Example:

Debug Reset

This method allows to reset the debugging data.
This method call doesn't stop the debugging mode, but it erases all collected data.

debugReset()

This method returns the class instance itself.
For convenience, this method is chainable.

Example #1:

Example #2:

Accept Unsafe Certificates

This method allows to disable the cURL SSL verify peer.
For example: accepting self-signed SSL certificates in development.

acceptUnsafeCertificatesByDisablingCurlSslVerifyPeer()

WARNING:
This method is intended for API development and testing purposes only.
It should NEVER be used when consuming production APIs, as it disables SSL verification.
Only use this when testing against local API instances with self-signed certificates.

This method returns the class instance itself.
For convenience, this method is chainable.

Example:

License

MIT