PHPackages truetrial/sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. truetrial/sdk ActiveLibrary[API Development](/categories/api) truetrial/sdk ============= Official PHP SDK for the TrueTrial API v1.0.1(2mo ago)03MITPHPPHP ^8.2 Since May 7Pushed 2mo agoCompare [ Source](https://github.com/TrueTrial/truetrial-php-sdk)[ Packagist](https://packagist.org/packages/truetrial/sdk)[ RSS](/packages/truetrial-sdk/feed)WikiDiscussions main Synced 3w ago READMEChangelogDependencies (2)Versions (3)Used By (0) TrueTrial PHP SDK ================= [](#truetrial-php-sdk) Official PHP SDK for the [TrueTrial](https://truetrial.com) API. Manage orders, shipments, temporal elements (trials, warranties, subscriptions), cancellations, and webhooks. Requirements ------------ [](#requirements) - PHP 8.2 or higher - Guzzle HTTP 7.x Installation ------------ [](#installation) ``` composer require truetrial/sdk ``` Quick Start ----------- [](#quick-start) ### Create a Client [](#create-a-client) ``` use TrueTrial\TrueTrial; $truetrial = new TrueTrial('your-api-key'); // Or with a custom base URL $truetrial = new TrueTrial('your-api-key', 'https://api.truetrial.com/api/v1'); ``` ### Create an Order [](#create-an-order) ``` $order = $truetrial->orders->create([ 'external_order_id' => 'ORD-12345', 'product_name' => 'Premium Supplement', 'product_type' => 'physical', 'product_price_cents' => 4999, 'product_currency' => 'USD', 'consumer_email' => 'customer@example.com', 'consumer_first_name' => 'Jane', 'consumer_last_name' => 'Doe', 'temporal_type' => 'trial', 'temporal_duration_value' => 30, 'temporal_duration_unit' => 'days', ]); echo $order['id']; // ULID ``` ### List Orders [](#list-orders) ``` // All orders $response = $truetrial->orders->list(); // With filters $response = $truetrial->orders->list([ 'status' => 'trial_active', 'page' => 1, 'per_page' => 25, ]); foreach ($response['data'] as $order) { echo $order['product_name'] . ' - ' . $order['status'] . "\n"; } ``` ### Get Order Status [](#get-order-status) ``` $status = $truetrial->orders->status('01HQ4X5K...'); // Returns: order_status, temporal_element_status, shipment_status ``` ### Create a Shipment [](#create-a-shipment) ``` $shipment = $truetrial->shipments->create('01HQ4X5K...', [ 'carrier' => 'ups', 'tracking_number' => '1Z999AA10123456784', ]); ``` ### Confirm Digital Delivery [](#confirm-digital-delivery) ``` $delivery = $truetrial->digitalDelivery->confirm('01HQ4X5K...', [ 'method' => 'link_click', 'delivered_at' => '2026-02-08T12:00:00Z', ]); ``` ### Manage Temporal Elements [](#manage-temporal-elements) ``` // Get temporal element for an order $temporal = $truetrial->temporal->get('01HQ4X5K...'); // Extend a trial $truetrial->temporal->extend('01HQ4X5K...', [ 'additional_days' => 7, 'reason' => 'Customer request - shipping delay', ]); // Adjust temporal element $truetrial->temporal->adjust('01HQ4X5K...', [ 'new_end_time' => '2026-04-01T00:00:00Z', 'reason' => 'Manual adjustment', ]); // Submit a warranty claim $truetrial->temporal->claim('01HQ4X5K...', [ 'description' => 'Product defect - screen crack', 'evidence' => ['photo_url' => 'https://...'], ]); // Resolve a warranty claim $truetrial->temporal->resolveClaim('01HQ4X5K...', [ 'resolution' => 'claim_approved', 'notes' => 'Replacement authorized', ]); ``` ### Cancellations [](#cancellations) ``` // Initiate cancellation $cancellation = $truetrial->cancellations->create('01HQ4X5K...', [ 'reason' => 'Customer changed their mind', ]); // Get cancellation details $cancellation = $truetrial->cancellations->get('01HQ4X5K...'); ``` ### Webhooks [](#webhooks) ``` // List webhook subscriptions $webhooks = $truetrial->webhooks->list(); // Create a webhook subscription $webhook = $truetrial->webhooks->create([ 'url' => 'https://yourapp.com/webhooks/truetrial', 'events' => ['order.delivered', 'trial.started', 'trial.expiring'], ]); // Delete a webhook $truetrial->webhooks->delete('01HQ4WEBHOOK...'); ``` ### System Health [](#system-health) ``` $health = $truetrial->system->carrierHealth(); ``` Webhook Verification -------------------- [](#webhook-verification) Verify incoming webhook signatures to ensure authenticity: ``` use TrueTrial\Webhook; $payload = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_TRUETRIAL_SIGNATURE']; $timestamp = (int) $_SERVER['HTTP_X_TRUETRIAL_TIMESTAMP']; $secret = 'your-webhook-secret'; // Simple verification $isValid = Webhook::verify($payload, $signature, $secret); // With timestamp tolerance (reject webhooks older than 5 minutes) $isValid = Webhook::verify($payload, $signature, $secret, 300, $timestamp); // Verify and decode in one step try { $event = Webhook::constructEvent($payload, $signature, $secret, 300, $timestamp); match ($event['event']) { 'order.delivered' => handleDelivery($event['data']), 'trial.started' => handleTrialStart($event['data']), 'trial.expiring' => handleTrialExpiring($event['data']), default => null, }; } catch (\TrueTrial\Exceptions\TrueTrialException $e) { http_response_code(400); echo 'Invalid signature'; } ``` Data Objects ------------ [](#data-objects) The SDK includes optional data objects for convenience: ``` use TrueTrial\DataObjects\Order; use TrueTrial\DataObjects\PaginatedResponse; $response = $truetrial->orders->list(); $paginated = PaginatedResponse::fromArray($response); echo "Page {$paginated->currentPage} of {$paginated->lastPage}\n"; $order = Order::fromArray($response['data'][0]); echo $order->productName; echo $order->status; ``` Available data objects: - `Order` -- id, tenantId, consumerId, externalOrderId, productName, productType, productPriceCents, productCurrency, status, metadata, createdAt, consumer - `Consumer` -- id, email, firstName, lastName, phone - `Shipment` -- id, orderId, carrier, trackingNumber, status, estimatedDelivery, deliveredAt - `TemporalElement` -- id, orderId, type, status, durationValue, durationUnit, beginTime, endTime, expiresAt - `Cancellation` -- id, orderId, reason, status, cancelledAt - `WebhookSubscription` -- id, url, events, secret, lastTriggeredAt - `OrderStatus` -- orderId, externalOrderId, orderStatus, temporalElementStatus, shipmentStatus - `PaginatedResponse` -- data, currentPage, lastPage, perPage, total Error Handling -------------- [](#error-handling) The SDK throws specific exceptions for different error conditions: ``` use TrueTrial\Exceptions\AuthenticationException; use TrueTrial\Exceptions\NotFoundException; use TrueTrial\Exceptions\ValidationException; use TrueTrial\Exceptions\RateLimitException; use TrueTrial\Exceptions\ServerException; use TrueTrial\Exceptions\TrueTrialException; try { $order = $truetrial->orders->get('01HNONEXISTENT'); } catch (AuthenticationException $e) { // 401 - Invalid or missing API key echo "Auth failed: " . $e->getMessage(); } catch (NotFoundException $e) { // 404 - Resource not found echo "Not found: " . $e->getMessage(); } catch (ValidationException $e) { // 422 - Validation errors echo "Validation failed: " . $e->getMessage(); foreach ($e->errors() as $field => $messages) { echo "{$field}: " . implode(', ', $messages) . "\n"; } } catch (RateLimitException $e) { // 429 - Rate limit exceeded $retryAfter = $e->retryAfter(); // seconds until retry, or null echo "Rate limited. Retry after: {$retryAfter}s"; } catch (ServerException $e) { // 500+ - Server error echo "Server error: " . $e->getMessage(); } catch (TrueTrialException $e) { // Catch-all for any other SDK error echo "Error [{$e->statusCode}]: " . $e->getMessage(); } ``` All exceptions extend `TrueTrialException` and include: - `$statusCode` -- HTTP status code - `$responseBody` -- raw response body string Enums ----- [](#enums) The SDK provides string-backed enums for type safety: ``` use TrueTrial\Enums\OrderStatus; use TrueTrial\Enums\TemporalType; use TrueTrial\Enums\TemporalStatus; $truetrial->orders->list(['status' => OrderStatus::TrialActive->value]); ``` EnumValues`OrderStatus`received, shipped, in\_transit, delivered, trial\_active, converted, returned, expired, cancelled`TemporalType`trial, evaluation, subscription, warranty, guarantee`TemporalStatus`pending, active, expiring, expired, converted, cancelled, suspended, renewed, claimed, claim\_approved, claim\_denied`ShipmentStatus`pending, in\_transit, out\_for\_delivery, delivered, failed, returned\_to\_sender`ProductType`physical, digital`Carrier`ups, fedex, usps, dhl, shippo, aftership`DurationUnit`days, weeks, months, years`DeliverySource`webhook, poll, manual, fallback\_carrier`DigitalDeliveryMethod`link\_click, installation, first\_login, first\_execution, license\_key`WebhookEvent`order.created, order.delivered, trial.started, trial.expiring, trial.expired, trial.converted, cancellation.initiated, risk\_score.changed, subscription.renewed, warranty.claimed, temporal.extended, temporal.adjusted, warranty.claim\_resolved, payment.succeeded, payment.failed, dispute.created, dispute.won, dispute.lostAPI Reference ------------- [](#api-reference) MethodHTTPPath`$client->orders->list($filters)`GET`/orders``$client->orders->create($data)`POST`/orders``$client->orders->get($id)`GET`/orders/{id}``$client->orders->status($id)`GET`/orders/{id}/status``$client->shipments->create($orderId, $data)`POST`/orders/{orderId}/shipments``$client->shipments->list($orderId)`GET`/orders/{orderId}/shipments``$client->digitalDelivery->confirm($orderId, $data)`POST`/orders/{orderId}/digital-delivery``$client->temporal->get($orderId)`GET`/orders/{orderId}/temporal``$client->temporal->extend($orderId, $data)`POST`/orders/{orderId}/temporal/extend``$client->temporal->adjust($orderId, $data)`POST`/orders/{orderId}/temporal/adjust``$client->temporal->claim($orderId, $data)`POST`/orders/{orderId}/temporal/claim``$client->temporal->resolveClaim($orderId, $data)`POST`/orders/{orderId}/temporal/resolve-claim``$client->cancellations->create($orderId, $data)`POST`/orders/{orderId}/cancellations``$client->cancellations->get($orderId)`GET`/orders/{orderId}/cancellations``$client->webhooks->list()`GET`/webhooks``$client->webhooks->create($data)`POST`/webhooks``$client->webhooks->delete($id)`DELETE`/webhooks/{id}``$client->system->carrierHealth()`GET`/carrier-health`License ------- [](#license) MIT ### Health Score 37 — LowBetter than 81% of packages Maintenance86 Actively maintained with recent releases Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~12 days Total 2 Last Release 66d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/2931452?v=4)[T ST](/maintainers/tpharaoh)[@tpharaoh](https://github.com/tpharaoh) --- Top Contributors [![tpharaoh](https://avatars.githubusercontent.com/u/2931452?v=4)](https://github.com/tpharaoh "tpharaoh (1 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/truetrial-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/truetrial-sdk/health.svg)](https://phpackages.com/packages/truetrial-sdk) ``` ### Alternatives [tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3661.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[eslazarev/wildberries-sdk Wildberries OpenAPI clients (generated). 293.1k](/packages/eslazarev-wildberries-sdk)[files.com/files-php-sdk Files.com PHP SDK 2481.1k](/packages/filescom-files-php-sdk)[aimeos/prisma A powerful PHP package for integrating media related Large Language Models (LLMs) into your applications 1943.1k5](/packages/aimeos-prisma)[volcengine/volcengine-php-sdk 118.7k](/packages/volcengine-volcengine-php-sdk) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)