README

Initial release 0.1.0. Supports PHP 8.3–8.5, Composer, PSR-4 autoloading, and synchronous PSR-18 HTTP clients. MIT licensed.

Install

composer require wasil/integrations:^0.1

Submit a delivery request

<?php
require 'vendor/autoload.php';

use Wasil\Integrations\WasilClient;

$token = getenv('WASIL_API_TOKEN');
if (!$token) throw new RuntimeException('Configure your staging server key');
$client = new WasilClient($token, baseUrl: WasilClient::STAGING_BASE_URL, maxRetries: 2);
$options = $client->getDeliveryOptions(['latitude' => 32, 'longitude' => 35]);
if (!$options['available'] || !$options['availableDeliveryDates']) {
    throw new RuntimeException('Resolve delivery option issues');
}

// Persist your own original payload and key before sending. Values below are fictional.
$originalPayload = [
    'storeId' => 'website', 'externalOrderId' => 'ORDER-1001',
    'customer' => ['name' => 'Example Customer', 'phone' => '+972500000000'],
    'deliveryAddress' => '10 Example Street, Example Town',
    'deliveryPoint' => ['latitude' => 32, 'longitude' => 35],
    'deliveryDate' => $options['availableDeliveryDates'][0],
    'items' => [['title' => 'Example product', 'quantity' => 2]],
    'totalMinor' => 14990, 'paymentMethod' => 'cash_on_delivery',
];
$persistedKey = 'website_ORDER-1001_0001';
$request = $client->createDeliveryRequest($originalPayload, $persistedKey);
// Persist $request['id']. Only status === 'booked' confirms booking.

Methods and configuration

All methods return associative arrays with generated PHPDoc shapes:

Method	Arguments
`getDeliveryOptions`	optional array with `latitude`, `longitude`
`createDeliveryRequest`	original payload, persisted idempotency key
`listDeliveryRequests`	optional array with `page`, `status`, `q`
`getDeliveryRequest`	Wasil request ID
`updateDeliveryRequest`	Wasil request ID, correction including current `version`
`cancelDeliveryRequest`	Wasil request ID

Constructor arguments are token, baseUrl, timeoutMs, maxRetries, and optional httpClient. Default Guzzle configuration uses a 30-second timeout and disables redirects. An injected PSR-18 client owns its timeout, redirects and middleware retries; configure these deliberately to preserve SDK retry semantics.

Default base URL is production. Use WasilClient::STAGING_BASE_URL with separate staging credentials while testing. Keep the key in server secret storage and do not log authenticated requests.

Errors and recovery

WasilApiError exposes status, errorCode, and nullable requestId. WasilTransportError.kind is network or timeout (recognized Guzzle cURL timeout). Generic PSR-18 failures may not distinguish timeout from network failure. WasilResponseError exposes status and nullable requestId. Errors do not chain HTTP exceptions or retain raw request/response bodies. PHP sensitive-parameter attributes protect payloads and keys in SDK exception traces.

Retries default to zero. Set maxRetries: 2 for at most three attempts; the allowed range is 0–10. Reads, creation and cancellation retry network failures, timeouts and HTTP 500/502/503/504. Backoff uses full jitter starting at 250 ms, capped at two seconds. Creation reuses the same serialized bytes and key. Other HTTP errors and malformed responses are not retried.

PATCH is never automatically retried. Fetch current state after a lost response before reapplying corrections. Omitted fields retain their values; explicit null clears delivery point/date. A needs_attention result is saved but not booked. Unknown future issue/status codes pass through; treat unknown issues as blockers.

Poll from a background job, one read at a time, then persist/reconcile state and schedule the next read with backoff. V1 has no webhooks. Pagination, polling schedules and durable recovery belong to your application. See the complete SDK workflows, idempotency guide, and API reference.

Development and releases

This repository is a reviewed distribution of the PHP SDK maintained in the Wasil monorepo. Make SDK changes there, run its contract and documentation checks, and export the package with pnpm sdk:export:php. Do not develop independent SDK changes in this distribution repository.

Run composer install, composer validate --strict, composer check, and composer check:package from this repository root. CI validates PHP 8.3, 8.4 and 8.5. The package check requires the ZIP extension. Contract fixtures are included under tests/fixtures.

Publish reviewed exports to the staging branch. Tag a release only after CI passes; Composer obtains its version from the Git tag. Packagist indexes wasil/integrations from this repository.

wasil / integrations

Package info

Security

Statistics