README

Apirone SDK PHP

This Library provides classes for working with Apirone invoices. Easy integration of cryptocurrency payments.

Requirements
Installation and preparation for use
- Assets configure
- Database and Logs handlers
Settings
Create an Invoice
Get an existing invoice
Callbacks handler
Show invoice
- Render loader
- Render AJAX response
Examples and playground
Support
License
Changelog

Requirements

PHP 7.4 or higher with cURL and JSON extentions. Tested up to 8.2.
MySQL or MariaDB
Apirone API PHP

Installation and preparation for use

Use composer for library installation.

composer require apirone/apirone-sdk-php

Assets configure

Copy src/assets folder into your public html. On the invoice display page you need to add css/styles.css and js/script.js from assets folder. Also, you can use minimized versions.

Database and Logs handlers

To connect library to your database-engine you need to create two callback functions and pass them to the library.

Db handler example for php MySQLi

// Our MySQL engine example
$conn = new mysqli('host', 'user', 'pass', 'database');
$conn->select_db('database');

// DB MySQL handler example
$db_handler = static function($query) {
    global $conn;
    $result = $conn->query($query, MYSQLI_STORE_RESULT);

    if (!$result) {
        return $conn->error;
    }
    if (gettype($result) == 'boolean') {
        return $result;
    }
    return $result->fetch_all(MYSQLI_ASSOC);
};

For logging you can use a callback function or logger implementation Psr/Log/LoggerInterface

Log callback example:

$logger = static function($level, $message, $context) {
    print_r([$level, $message, $context]);
};

Psr/Log example:

$logger = new /Psr/Log/LoggerInterface();

Set handlers to the library:

use Apirone\SDK\Invoice;

Invoice::db($db_handler, 'table_prefix_');
Invoice::setLogger($logger);

Create an invoice table:

use Apirone\SDK\Service\InvoiceDb;

// Create the invoice table if it doesn't exist
InvoiceDb::install('table_prefix', $charset = 'urf8', $collate = 'utf_general_ci');

You can create a common file to set up an account class and include it in your code

// Setup invoice handlers and Settings
Invoice::db($db_handler, $table_prefix);
Invoice::log($log_handler);
Invoice::settings(Settings::fromFile('/absolute/path/to/settings.json'));

Settings

The settings class is used to create an account, manage currency settings, and save and restore the settings object.

Create a new settings object:

use Apirone\SDK\Model\Settings;

$settings = Settings::init();
$settings->createAccount();

// Save the settings object to the file
$settings->toFile('absolute/path/to/settings.json');

// Get settings as JSON-object to save it to the database
$json = $settings->toJson();

Load an existing settings object

$fromFile = Settings::fromFile('/absolute/path/to/settings.json');

// For example you have get_option function
$json = get_option('apirone_settings');

$fromJson = Settings::fromJson($json);

Create an Invoice

use Apirone\SDK\Invoice;
use Apirone\SDK\Model\Settings;

// Setup invoice handlers and Settings
Invoice::db($db_handler, $table_prefix);
Invoice::log($log_handler);
Invoice::settings(Settings::fromFile('/absolute/path/to/settings.json'));

$invoice = Invoice::init('btc', 25000);

$invoice->callbackUrl('https://example.com/callback_page');
$invoice->lifetime(1800);

$invoice->crete();

// You can see the created invoice JSON data
$json = $invoice->toJson();

Get an existing invoice

use Apirone\SDK\Invoice;
use Apirone\SDK\Model\Settings;

// Setup invoice handlers and Settings
Invoice::db($db_handler, $table_prefix);
Invoice::log($log_handler);
Invoice::settings(Settings::fromFile('/absolute/path/to/settings.json'));

$id = '9qAs2OQao43VWz72';
$invoice = Invoice::getInvoice($id);

Callbacks handler

Apirone service interacts with the library through callbacks. To get invoice statuses, you need to create a URL and add a callback handler to your code. This address must be set when creating a new invoice.

If you need to process the order status based on the status of the invoice, you can create a callback function to handle the status change.

// Create an order process function
$order_status_handler = static function ($invoice) {
    // You need to set the order_id when creating an invoice.
    $order_id = $invoice->order();
    // ... Write here your business logic
}
// ... Setup invoice handlers and settings


Invoice::callbackHandler($order_status_handler);

Show invoice

Render loader

To display the invoice, use the renderLoader() function. Also, a style file and js script should be added to the page template from the assets folder.

use Apirone\SDK\Invoice;
use Apirone\SDK\Model\Settings;

// Setup invoice handlers and Settings
Invoice::db($db_handler, $table_prefix);
Invoice::log($log_handler);
Invoice::settings(Settings::fromFile('/absolute/path/to/settings.json'));

// Set invoice data url - render ajsx response page
Invoice::dataUrl('render_ajax_response.php');

// In case when $invoice_id does not set function try to find id from request params - $_GET['invoice']
$ = Invoice::renderLoader();

// If you got the required invoice ID any other way, just pass it to the function
$id = 'MyInvoiceId';
Invoice::renderLoader($id);

Render AJAX response

To update the invoice data, you need to create a URL and add the renderAjaxResponse() function to the code. This URL used as Invoice::dataUrl() parameter.

use Apirone\SDK\Invoice;
use Apirone\SDK\Model\Settings;

// Setup invoice handlers and Settings
Invoice::db($db_handler, $table_prefix);
Invoice::log($log_handler);
Invoice::settings(Settings::fromFile('/absolute/path/to/settings.json'));

Invoice::renderAjax();

Examples and playground

In the examples folder, you can find a ready-made implementation of the library usage.

You can also run the playground. To run the playground, you need Docker and Docker Compose installed.

To do this, you need to copy the docker-compose.yml file from the docker folder to the library root folder and run the command:

docker-compose up -d --build

After the start of the containers, the playground will be available in the browser at http://localhost

Support

License

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Changelog

Version 1.1.6 | 21/11/2024

Isolated styles from sdk root element
Clear unused styles & code cleanup
Minimized styles assets

Version 1.1.5 | 20/11/2024

Fixed render ajax response when offset exists and is zero
Added mobile view for address strings & mobile styles improved
Added changelog, code cleanup & fixed misprints

Version 1.1.4 | 14/11/2024

Fixed strlen fatal error

Version 1.1.3 | 14/11/2024

Updated render & docker-compose
Styles updated
Added humanizeAmount method

Version 1.1.2 | 02/08/2024

Workflows updated
Added release-drafter workflow
One address for network and its tokens
Folder structure refactored. Added local UID/GID to Dockerfile

Version 1.1.1 | 05/03/2024

Added USDT icon

Version 1.1.0 | 19/01/2024

Added internal QR code generator
Updated styles
Minor fixes

Version 1.0.4 | 28/12/2023

Added external link icon
Updated script.min.js

Version 1.0.3 | 26/12/2023

Optimized styles assets
Added currency default placeholder icon

Version 1.0.2 | 26/12/2023

Added icons
Updated styles & js

Version 1.0.1 | 30/11/2023

Updated getter for explorer links

Version 1.0.0 | 14/11/2023

First release of the library

apirone / apirone-sdk-php

Maintainers

Details