Skip to main content

PHP SDK

The Staqr PHP SDK provides native PHP access to Staqr Platform and Commerce APIs with PSR-4 compliance and Guzzle HTTP client.

Installation​

Composer​

# Staqr Platform API
composer require staqr/api-client:@dev

# Commerce APIs
composer require staqr/commerce-v1:@dev  # Recommended - structured APIs
composer require staqr/commerce-v2:@dev  # Generic CRUD
composer require staqr/commerce-v0:@dev  # Legacy (if needed)

From Local SDK​

# Add to composer.json repositories
{
    "repositories": [
        {
            "type": "path",
            "url": "./sdks/staqr-php"
        }
    ]
}

composer require staqr/api-client:@dev

Quick Start​

<?php

require_once 'vendor/autoload.php';

use Staqr\ApiClient\Configuration;
use Staqr\ApiClient\Api\FlowsApi;

// Configure the client
$config = Configuration::getDefaultConfiguration()
    ->setHost('https://my.staqr.com/api/v1')
    ->setAccessToken(getenv('STAQR_API_KEY'));

// Create API instance
$flowsApi = new FlowsApi(null, $config);

// List flows
$flows = $flowsApi->listFlows();
foreach ($flows as $flow) {
    echo "Flow: " . $flow->getDisplayName() . "\n";
}

Authentication​

API Key Authentication​

<?php

use Staqr\ApiClient\Configuration;

$config = Configuration::getDefaultConfiguration()
    ->setHost('https://my.staqr.com/api/v1')
    ->setAccessToken(getenv('STAQR_API_KEY'))
    ->addDefaultHeader('x-seller-id', getenv('STAQR_SELLER_ID'));

OAuth2 (Commerce APIs)​

<?php

use Staqr\CommerceV1\Configuration;

// For Commerce Direct access (Keycloak OAuth2)
$config = Configuration::getDefaultConfiguration()
    ->setHost('https://commerce.staqr.com/api')
    ->setAccessToken($commerceOAuthToken)
    ->addDefaultHeader('X-Tenant', 'YOUR_TENANT_CODE');

Available Packages​

PackageAPIComposer Require
staqr/api-clientStaqr Platformcomposer require staqr/api-client
staqr/commerce-v1Commerce v1 (Structured)composer require staqr/commerce-v1
staqr/commerce-v2Commerce v2 (Generic CRUD)composer require staqr/commerce-v2
staqr/commerce-v0Commerce v0 (Legacy)composer require staqr/commerce-v0

Common Operations​

Working with Customers (Commerce)​

<?php

use Staqr\CommerceV1\Api\CustomerManagementApi;

$customerApi = new CustomerManagementApi(null, $config);

// List customers
$customers = $customerApi->listCustomers();

// Get customer by code
$customer = $customerApi->getCustomerByCode('CUST001');

// Create customer
$newCustomer = new \Staqr\CommerceV1\Model\CustomerDto();
$newCustomer->setCode('CUST002');
$newCustomer->setDescription('New Customer');
$customerApi->createCustomer($newCustomer);

Working with Subscriptions​

<?php

use Staqr\CommerceV1\Api\SubscriptionApi;

$subscriptionApi = new SubscriptionApi(null, $config);

// List subscriptions
$subscriptions = $subscriptionApi->listSubscriptions();

// Get subscription details
$subscription = $subscriptionApi->getSubscription($subscriptionId);

Error Handling​

<?php

use Staqr\ApiClient\ApiException;

try {
    $result = $flowsApi->getFlow('invalid-id');
} catch (ApiException $e) {
    echo "API Error: " . $e->getMessage() . "\n";
    echo "Status Code: " . $e->getCode() . "\n";
    echo "Response Body: " . $e->getResponseBody() . "\n";
}

Laravel Integration​

Service Provider​

<?php
// app/Providers/StaqrServiceProvider.php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Staqr\CommerceV1\Api\CustomerManagementApi;
use Staqr\CommerceV1\Configuration;

class StaqrServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton(CustomerManagementApi::class, function ($app) {
            $config = Configuration::getDefaultConfiguration()
                ->setHost(config('staqr.commerce.url'))
                ->setAccessToken(config('staqr.commerce.token'));

            return new CustomerManagementApi(null, $config);
        });
    }
}

Controller Usage​

<?php

namespace App\Http\Controllers;

use Staqr\CommerceV1\Api\CustomerManagementApi;

class CustomerController extends Controller
{
    public function __construct(
        private CustomerManagementApi $customerApi
    ) {}

    public function index()
    {
        $customers = $this->customerApi->listCustomers();
        return view('customers.index', compact('customers'));
    }
}

Symfony Integration​

Service Configuration​

# config/services.yaml
services:
    Staqr\CommerceV1\Configuration:
        factory: ['Staqr\CommerceV1\Configuration', 'getDefaultConfiguration']
        calls:
            - [setHost, ['%env(COMMERCE_API_URL)%']]
            - [setAccessToken, ['%env(COMMERCE_API_TOKEN)%']]

    Staqr\CommerceV1\Api\CustomerManagementApi:
        arguments:
            - null
            - '@Staqr\CommerceV1\Configuration'

PHP Requirements​

  • PHP 8.1 or higher
  • Composer
  • ext-curl
  • ext-json
  • ext-mbstring

Examples​

See the examples directory for complete usage examples:

  • Basic API calls
  • Laravel integration
  • Symfony bundle
  • Error handling patterns
  • Pagination handling

API Reference​

For complete API documentation, see:

Troubleshooting​

SSL Certificate Issues​

If you encounter SSL certificate errors:

<?php

// Disable SSL verification (development only!)
$config = Configuration::getDefaultConfiguration()
    ->setHost('https://my.staqr.com/api/v1')
    ->setSslVerification(false);  // NOT for production!

Memory Limits​

For large responses, increase PHP memory limit:

ini_set('memory_limit', '256M');