README

^{Official PHP Mascot for XYO.Financial Generated by Adobe AI and Imagined by Syniol Limited}

The official XYO.Financial PHP SDK, meticulously engineered by Syniol Limited to meet the rigorous demands of tier-1 financial institutions, payment gateways, and mission-critical banking infrastructure.

Built exclusively for PHP 8.2+, this SDK guarantees zero-mutation data states, robust typed exception hierarchies, and seamless integration into highly secure, heavily monitored enterprise environments.

🏛️ Enterprise-Grade Architecture

Immutability by Design: All Data Transfer Objects (DTOs) utilize PHP 8.2 readonly properties and constructor promotion. Once a transaction is enriched, its state is cryptographically locked in memory—eliminating entire classes of data tampering vulnerabilities.
Transport Agnostic & PSR-Compliant: By decoupling the configuration from the transport layer, you can inject fully customized GuzzleHttp\ClientInterface instances. Effortlessly bind corporate proxies, Mutual TLS (mTLS) certificates, or your own telemetry middleware without altering the SDK.
RFC 7807 Structured Errors: Gone are the days of blind string parsing. The SDK fully implements RFC 7807 error structures. Every exception payload is typed, predictable, and iterable, empowering your circuit breakers and alerting systems.
Typed Exception Hierarchy: Network timeouts (NetworkException), upstream degradation (ServerException), and payload rejections (ClientException) are strictly segregated. Your retry logic will never mistake a 503 Service Unavailable for a 401 Unauthorized.

📦 Installation

Install via Packagist using Composer:

composer require xyo/sdk

🚀 Quickstart Guide

1. Client Initialization

The Client acts as your secure facade. For enterprise deployments, we strongly recommend injecting a tailored HTTP client to handle your network egress rules.

use XYO\SDK\Client;
use XYO\SDK\ClientConfig;
use GuzzleHttp\Client as GuzzleClient;

// Optional: Configure your own transport with strict timeouts or proxy routing
$customHttpClient = new GuzzleClient([
    'timeout'         => 10.0,
    'connect_timeout' => 3.0,
    // 'proxy'        => 'tcp://proxy.internal.corp:8080'
]);

$config = new ClientConfig("YOUR_API_KEY", $customHttpClient);
$client = new Client($config);

2. Synchronous Transaction Enrichment

Enrich raw settlement data with pinpoint accuracy. The SDK validates payloads client-side before egressing to the XYO AI engine.

use XYO\SDK\Enrichment\DTO\EnrichmentRequest;
use XYO\SDK\ClientException;
use XYO\SDK\ServerException;
use XYO\SDK\NetworkException;

try {
    $request = new EnrichmentRequest(
        content: "Costa PICKUP", 
        countryCode: "GB" // Strict ISO 3166-1 alpha-2 validation
    );

    $enrichment = $client->enrichTransaction($request);

    echo "Merchant: " . $enrichment->merchant . "\n";
    echo "Category: " . implode(', ', $enrichment->categories) . "\n";

} catch (ClientException $e) {
    // Inspect structured RFC 7807 errors
    foreach ($e->getErrors() as $apiError) {
        error_log(sprintf("Validation Failure [%s]: %s", $apiError['title'], $apiError['detail']));
    }
} catch (NetworkException $e) {
    // Trigger localized circuit breaker logic
} catch (ServerException $e) {
    // Log upstream degradation
}

3. Asynchronous Bulk Processing

For massive daily reconciliation batches, utilize the collection endpoints to dispatch thousands of records concurrently.

Dispatch the Batch:

$batch = [
    new EnrichmentRequest("Costa PickUp", "GB"),
    new EnrichmentRequest("STRBUKS GREENWICH", "GB")
];

$collectionResponse = $client->enrichTransactionCollection($batch);

// Securely store the Tracking ID
$trackingId = $collectionResponse->id;

Poll for Completion:

use XYO\SDK\Enrichment\DTO\EnrichmentCollectionStatusResponse;

$statusResponse = $client->enrichTransactionCollectionStatus($trackingId);

if ($statusResponse->getStatus() === EnrichmentCollectionStatusResponse::READY) {
    // The batch is processed and ready for secure retrieval
    echo "Batch processing complete.";
} elseif ($statusResponse->getStatus() === EnrichmentCollectionStatusResponse::FAILED) {
    // Investigate failure
} else {
    // Status is PENDING. Backoff and retry.
}

🔒 Security & Compliance

This SDK enforces strict boundary validation. Malformed inputs throw \InvalidArgumentException locally, ensuring junk data never traverses your outbound network boundary. All internal dependencies are continuously audited for vulnerabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.

xyo / sdk

Maintainers

Package info

Statistics

Security