README.md

Carbone PHP

Unofficial port of the Carbone API SDK to Saloon v3

Getting started

composer require open-southeners/carbone-sdk

Laravel installation

To make this work within a Laravel app you just need to add the following at the very bottom of your .env file:

CARBONE_API_KEY='your-carbone-api-key'

To customise the API version and more you can simply add carbone array item to the config/services.php:

<?php

return [

    // rest of services.php items here...

    'carbone' => [
        'key' => env('CARBONE_API_KEY', ''),
        'version' => '4',
    ],

];

Usage

Within Laravel you've it injected into your application's container:

$response = app('carbone')->template()->base64Upload($templateBase64);

if ($response->failed()) {
    throw new \Exception('Template upload failed!');
}

// This is extracted from official Carbone SDK: https://carbone.io/api-reference.html#upload-a-template-carbone-cloud-sdk-php
$templateId = $response->getTemplateId();

Any other framework (or not)

If you are using another framework (or just pure PHP), you can still use this as a standalone library:

$carbone = new Carbone('your-carbone-api-key');

// Use this if you want to use a different API version: https://carbone.io/api-reference.html#api-version
// $carbone = new Carbone('your-carbone-api-key', '4');

$templateBase64 = base64_encode(file_get_contents('path_to_your_template_here'));

$response = $carbone->template()->base64Upload($templateBase64);

if ($response->failed()) {
    throw new \Exception('Template upload failed!');
}

// This is extracted from official Carbone SDK: https://carbone.io/api-reference.html#upload-a-template-carbone-cloud-sdk-php
$templateId = $response->getTemplateId();

Differences between official SDK and this

• Full Laravel support (optionally as this supports any framework or even raw PHP)
• Use of Saloon v3 not the v1 (which improves at everything typed for better IDE autocompletion support, etc)
• Replaced the template()->upload() method with template()->base64Upload() so the upload method can be used to send multipart/form-data POST request instead of a application/json with all the file contents base64 encoded
• Added template()->exists() to get if template with ID exists in Carbone (just a HEAD request so no content fetch at all)
• Added status()->fetch() to get status (not currently publicly documented, only on the OpenAPI, Postman, etc. Can check them here)

You can still check the official one here.

Partners

License

This package is open-sourced software licensed under the MIT license.