README

A PHP client library for Azure Service Bus. It manages namespace topology (topics, subscriptions, rules) and message operations (send, peek-lock receive, unlock, renew lock, delete) over the Service Bus REST API, authenticating via Shared Access Signature (SAS).

Framework-agnostic — no dependency on Magento, Laravel, Symfony, or any other framework. Use it in any PHP application that needs to talk to Azure Service Bus.

Table of contents

• Features
• Requirements
• Installation
• Quick start
• Key classes
• Usage
  • Topology: create a topic, subscription, and rule
  • Send a message
  • Receive a message (peek-lock)
  • Long-running processing: renew the lock
  • Reading dead-lettered messages
  • Listing topics and subscriptions
• Examples
• Testing
• Limitations
• License

Features

• Topic, subscription, and rule management (create, get, list, delete)
• Message send/receive with peek-lock and receive-and-delete modes
• Explicit lock lifecycle control: unlock (abandon), renew, delete (complete)
• Native Azure dead-letter sub-queue access
• SAS-based authentication via connection string, matching the format shown in the Azure Portal
• No framework dependencies; installable and testable standalone

Requirements

• PHP 7.3 or later (including PHP 8.x)
• guzzlehttp/guzzle ^6.5 or ^7.0
• pear/net_url2 ^2.2

Installation

composer require magetips/windowsazure

If this package isn't published to a registry you use, add it as a path or VCS repository in your project's composer.json.

Quick start

Everything starts from a connection string for one Service Bus namespace, in the format shown in the Azure Portal under Shared access policies:

$connectionString = 'Endpoint=https://<namespace>.servicebus.windows.net/;'
    . 'SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=<key>';

$serviceBus = \MageTips\WindowsAzure\Common\ServicesBuilder::getInstance()
    ->createServiceBusService($connectionString);

$serviceBus is a MageTips\WindowsAzure\ServiceBus\Internal\IServiceBus (concretely a ServiceBusRestProxy) — every example below is a method call on this object.

Tip: building the client is cheap, but there's no connection pooling built in. If you're sending or receiving many messages, reuse a single $serviceBus instance rather than rebuilding it per call.

Key classes

Usage

Topology: create a topic, subscription, and rule

use MageTips\WindowsAzure\ServiceBus\Models\TopicInfo;
use MageTips\WindowsAzure\ServiceBus\Models\SubscriptionInfo;
use MageTips\WindowsAzure\ServiceBus\Models\RuleInfo;

$serviceBus->createTopic(new TopicInfo('orders-export'));
$serviceBus->createSubscription('orders-export', new SubscriptionInfo('defaultsub'));
$serviceBus->createRule('orders-export', 'defaultsub', new RuleInfo('$Default'));

Creating a resource that already exists throws a ServiceException. Check for existence first (e.g. via listTopics()) if you need idempotent setup.

Send a message

use MageTips\WindowsAzure\ServiceBus\Models\BrokeredMessage;

$message = new BrokeredMessage(json_encode(['orderId' => 1001]));
$message->setContentType('application/json');
$message->setProperty('EventType', 'order.exported'); // custom property, arbitrary key/value

$serviceBus->sendTopicMessage('orders-export', $message);

Receive a message (peek-lock)

Peek-lock is the mode to use for anything that needs acknowledge/retry semantics — the message stays on the subscription, invisible to other receivers, until you explicitly delete or unlock it.

use MageTips\WindowsAzure\ServiceBus\Models\ReceiveMessageOptions;
use MageTips\WindowsAzure\ServiceBus\Models\ReceiveMode;

$options = new ReceiveMessageOptions();
$options->setReceiveMode(ReceiveMode::PEEK_LOCK);

$message = $serviceBus->receiveSubscriptionMessage('orders-export', 'defaultsub', $options);

if ($message === null) {
    // The subscription had no messages available.
}

$body = (string) $message->getBody();
$deliveryCount = $message->getDeliveryCount(); // number of times Azure has (re)delivered this message

After processing, do exactly one of the following:

// Success: remove the message from the subscription for good.
$serviceBus->deleteMessage($message);

// Transient failure: release the lock immediately so the message is redeliverable.
// Azure automatically dead-letters it once the subscription's MaxDeliveryCount is exceeded.
$serviceBus->unlockMessage($message);

unlockMessage(), deleteMessage(), and renewLock() all operate on $message->getLockLocation() (a URL Azure returns with the message), not the topic/subscription name — always call them with the same BrokeredMessage instance you received, not a reconstructed one.

Long-running processing: renew the lock

Azure's default lock duration is short (30–60 seconds). If a handler might run longer, extend the lock periodically so the message doesn't become redeliverable mid-processing:

$serviceBus->renewLock($message); // call again before $message->getLockedUntilUtc() is reached

Reading dead-lettered messages

Once a subscription's MaxDeliveryCount is exceeded, Azure automatically moves the message into a built-in, per-subscription dead-letter sub-queue. There's no separate API for it — append /$DeadLetterQueue to the subscription name passed to receiveSubscriptionMessage():

$deadLetter = $serviceBus->receiveSubscriptionMessage(
    'orders-export',
    'defaultsub/$DeadLetterQueue',
    $options
);

Listing topics and subscriptions

$topics = $serviceBus->listTopics()->getTopicInfos();
$subscriptions = $serviceBus->listSubscriptions('orders-export')->getSubscriptionInfos();

Examples

Runnable, end-to-end scripts against a real Service Bus namespace — see examples/:

• 01-send-and-receive-message.php — the core lifecycle: create topic/subscription, send, receive, acknowledge.
• 02-dead-letter-handling.php — forcing a message into the dead-letter sub-queue and requeuing it.

Testing

The test suite mocks the HTTP layer, so it runs without network access or Azure credentials:

composer install
vendor/bin/phpunit

Limitations

• Protocol: this library uses the classic Service Bus REST API (SAS authentication, Atom/XML topology payloads), the same surface long-supported for backward compatibility. It does not use AMQP and is not built on Microsoft's modern Track 2 SDK protocol.
• Receive modes: ReceiveMode::PEEK_LOCK supports retry and dead-letter semantics via unlockMessage()/deleteMessage()/renewLock(). ReceiveMode::RECEIVE_AND_DELETE removes the message immediately on receipt — there is no second chance if the handler fails afterward.
• Topology calls return values: createTopic(), createSubscription(), and createRule() parse Azure's response body as an Atom entry and return the created resource; they are not void.
• No connection pooling: callers are responsible for reusing client instances where appropriate.

License

Apache License 2.0. See LICENSE.txt.