[bahdanhal]

Closes #75

Summary

Adds support for inspecting visible Azure Storage Queue messages without changing their visibility.

The new API follows the existing synchronous/asynchronous method pairs used by QueueClient:

• peekMessage()
• peekMessageAsync()
• peekMessages()
• peekMessagesAsync()

A separate PeekedMessage model is used because the Azure Peek Messages response does not contain PopReceipt or TimeNextVisible. Peeked messages therefore cannot be passed directly to update or delete operations.

Implementation

• Sends GET /messages?peekonly=true.
• Supports the optional numofmessages parameter.
• Returns null when peekMessage() finds no visible message.
• Deserializes message ID, text, insertion and expiration times, and dequeue count.
• Updates the Queue package README, documentation, and changelog.

REST API reference:
https://learn.microsoft.com/en-us/rest/api/storageservices/peek-messages

Tests

Verified locally with PHP 8.5, Guzzle 8, and Azurite:

• Queue unit tests: 24 passed, 68 assertions.
• Queue integration tests: 22 passed, 40 assertions.
• Architecture tests: 8 passed, 86 assertions.
• PHPStan: passed with no errors.
• Pint: passed for all 260 files.
• git diff --check: passed.

The integration tests verify that:

• a peeked message remains immediately available to receiveMessage();
• batch peeking does not change visibility;
• peekMessage() returns null for an empty queue.

Compatibility

This is an additive change. No existing public API is modified and no upgrade instructions are required.

Before submitting, replace #ISSUE in the first line of the description with the actual issue number.

[brecht-vermeersch]

Thanks for this! Changed some parameter naming to align closer to the .NET library.

[brecht-vermeersch]

https://github.com/php-oss-for-azure/azure-storage-queue-php/releases/tag/1.3.0