README

A small, framework-agnostic PHP client for the Azure Service Bus REST API. It covers the message operations you need for a worker: sending (including scheduled delivery), peek-lock receive, completing and abandoning locked messages, purging, and reading message counts. Authentication uses Shared Access Signature (SAS) tokens, regenerated per request.

No PHP extensions are required — it speaks HTTP via Guzzle.

Looking for a Laravel queue driver built on this client? See paulemich/laravel-asb.

Requirements

PHP 8.3+
An Azure Service Bus namespace and a SAS policy with the appropriate claims (Send, Listen, and Manage for counts).

Installation

composer require paulemich/azure-service-bus

Usage

Creating a client

use PaulEmich\AzureServiceBus\ServiceBusClient;

// From a connection string (copy it from the Azure portal):
$client = ServiceBusClient::fromConnectionString(
    'Endpoint=sb://my-namespace.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=your-key'
);

Or wire it up explicitly (handy for injecting your own Guzzle client in tests):

use PaulEmich\AzureServiceBus\Auth\SasTokenGenerator;
use PaulEmich\AzureServiceBus\ServiceBusClient;

$client = ServiceBusClient::make(
    'https://my-namespace.servicebus.windows.net',
    new SasTokenGenerator('RootManageSharedAccessKey', 'your-key'),
);

Sending messages

// A plain message
$client->send('orders', json_encode(['id' => 42]));

// Scheduled delivery + a custom TTL, plus a custom application property
$client->send(
    queue: 'orders',
    body: json_encode(['id' => 42]),
    brokerProperties: [
        'MessageId' => 'order-42',
        'ScheduledEnqueueTimeUtc' => gmdate('D, d M Y H:i:s \G\M\T', time() + 600),
        'TimeToLive' => 3600,
    ],
    properties: ['Priority' => 'high'],
);

Receiving, completing and abandoning (peek-lock)

$message = $client->receive('orders', waitSeconds: 30);

if ($message !== null) {
    // $message->body, ->messageId(), ->deliveryCount(),
    // ->lockToken(), ->sequenceNumber(), ->property('Priority')

    try {
        handle($message->body);
        $client->complete($message);   // remove it from the queue
    } catch (\Throwable $e) {
        $client->abandon($message);    // unlock -> redelivered, DeliveryCount++
    }
}

Counts and purging

$counts = $client->countMessages('orders');
// ['active' => int, 'scheduled' => int, 'deadLetter' => int, 'total' => int]

$removed = $client->purge('orders'); // destructively drains active messages

API summary

Method	Description
`send($queue, $body, $brokerProperties = [], $properties = [])`	Send a message; returns the supplied `MessageId` (or `null`)
`receive($queue, $waitSeconds = 30)`	Peek-lock receive; returns a `ReceivedMessage` or `null`
`receiveAndDelete($queue, $waitSeconds = 0)`	Destructive read
`complete($message)`	Delete (settle) a locked message
`abandon($message)`	Unlock a locked message for redelivery
`purge($queue)`	Drain active messages; returns the count removed
`countMessages($queue)`	Active / scheduled / dead-letter / total counts

Errors from the REST API are wrapped in PaulEmich\AzureServiceBus\Exceptions\ServiceBusException.

Testing

composer install
vendor/bin/pest

Tests run entirely against a mocked Guzzle handler — no Azure account or network access required.

License

The MIT License (MIT). See LICENSE.md.

paulemich / azure-service-bus

Maintainers

Package info

Statistics

Security