README

This extension is a Yii2 Queue driver for queues based on Microsoft Azure Service Bus.

It uses the Azure Service Bus REST API

Installation

Install this extension with composer.

Either run

php composer.phar require --prefer-dist sagacorp/yii2-queue-azure-service-bus

or add the extension to your composer json.

"sagacorp/yii2-queue-azure-service-bus": "^5.0"

Basic Usage

First, you may configure your Azure service Bus.

Then, configure yii2 queue, and the service bus like the following:

return [
    'components' => [
        'queue' => [
            'class' => \saga\queue\azure\Queue::class,
            'as log' => \yii\queue\LogBehavior,
            'serializer' => \yii\queue\serializers\JsonSerializer::class,
            'serviceBus' => [
                'class' => \saga\queue\azure\service\ServiceBus::class,

                // Where to connect. Either a connection string...
                'connectionString' => 'Endpoint=sb://(namespace).servicebus.windows.net/;EntityPath=(queue)',

                // ...or the namespace and queue directly.
                'namespace' => 'your service bus namespace',
                'queue' => 'the name of your Azure Service Bus queue (can be different than the name used as config key)',

                // Required: how to authenticate (see below). When SharedAccessKeyName and SharedAccessKey are present in connectionString, a SasTokenProvider is configured automatically.
                'tokenProvider' => [
                    'class' => \saga\queue\azure\service\SasTokenProvider::class,
                    'sharedAccessKeyName' => 'your shared access key name',
                    'sharedAccessKey' => 'your shared access key',
                ],
            ],
        ],
    ],
];

Authentication

Authentication is handled by a dedicated tokenProvider component, so the ServiceBus component itself only carries the connection parameters. It is required — unless a connection string with a shared access key is supplied, in which case a SasTokenProvider is configured automatically. The tokenProvider accepts a configuration array (as shown below), a shared application component id, or an already built TokenProvider instance. Two providers are shipped:

SasTokenProvider — Shared Access Signature authentication:

'tokenProvider' => [
    'class' => \saga\queue\azure\service\SasTokenProvider::class,
    'sharedAccessKeyName' => '...',
    'sharedAccessKey' => '...',
],

When the ServiceBus connectionString already contains SharedAccessKeyName and SharedAccessKey, this provider is configured automatically and tokenProvider can be omitted.

AzureAdTokenProvider — Azure AD authentication via azure-oss/identity's DefaultAzureCredential (environment variables, then workload identity). The acquired access token is used as a Bearer token against the Service Bus REST API. When the Azure Workload Identity mutating webhook is enabled, the credentials are injected automatically through the AZURE_* environment variables, so no configuration is needed:

'tokenProvider' => \saga\queue\azure\service\AzureAdTokenProvider::class,

Optionally tune the scope and token caching:

'tokenProvider' => [
    'class' => \saga\queue\azure\service\AzureAdTokenProvider::class,
    'scope' => 'https://servicebus.azure.net/.default', // default
    // Shared token cache. Defaults to the application `cache` component when available, otherwise
    // the token is only kept in memory for the lifetime of the worker. Set to false to opt out, or
    // pass another cache component id / configuration / instance.
    'cache' => 'cache',
    'expiryLeeway' => 300, // seconds before expiry at which the cached token is refreshed
],

This provider requires a PSR-18 HTTP client and PSR-17 factories to be installed, for example composer require guzzlehttp/guzzle.

The targeted identity must be granted a Service Bus data plane role (e.g. Azure Service Bus Data Sender / Data Receiver) on the namespace or queue.

Once configured, you can send a task into the queue:

Yii::$app->queue->push(new DownloadJob([
    'url' => 'http://example.com/image.jpg',
    'file' => '/tmp/image.jpg',
]));