## Getting Started

### **Minimal Setup**
1. **Installation**
   Add the package via Composer (though it's primarily a dependency for other Azure Storage SDKs):
   ```bash
   composer require azure-oss/storage-common

Note: This package is rarely installed directly—it’s a dependency for packages like azure-oss/storage-blob-php. If you’re using the full Azure Blob Storage SDK, this is auto-installed.

First Use Case If you’re working with Azure Blob Storage, Azure Data Lake Storage, or Azure File Share, this package provides:
- Core HTTP client utilities (for retries, signing requests).
- Shared models (e.g., StorageUri, StorageCredentials).
- Low-level SDK primitives (e.g., StorageException, StorageError).
- SAS Token Generation: Now uses a shared date helper across storage-common, blob, and file share packages for consistent timestamp formatting.
Example (if using azure-oss/storage-blob-php):
```
use Azure\Storage\Blob\BlobServiceClient;
use Azure\Storage\Common\StorageSharedKeyCredential;

$connectionString = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...";
$credential = new StorageSharedKeyCredential(
    'account-name',
    'account-key'
);
$blobServiceClient = new BlobServiceClient(
    'https://account-name.blob.core.windows.net',
    $credential
);
```
Where to Look First
- Source Code: src/Common (models, exceptions, utilities, and SAS helpers).
- Tests: tests (real-world usage patterns).
- Dependent Packages: Check storage-blob-php or storage-file-php for integration examples.

Implementation Patterns

1. Credential Management

SharedKeyCredential (for account keys):

use Azure\Storage\Common\StorageSharedKeyCredential;
$credential = new StorageSharedKeyCredential('account-name', 'account-key');

SAS Token Support:

use Azure\Storage\Common\StorageSasCredential;
$sasToken = "sv=2020-08-04&ss=bfqt&srt=sco...";
$credential = new StorageSasCredential($sasToken);

Note: SAS token generation now uses a shared date helper for consistent timestamp formatting across packages.

Integration Tip: Reuse credentials across services (Blob, Queue, File) to avoid duplication.

2. SAS Token Generation (New/Updated)

Shared Date Helper: The package now uses a unified date helper for SAS token generation, ensuring consistency across storage-common, blob, and file share packages.

use Azure\Storage\Common\StorageSharedKeyCredential;
use Azure\Storage\Common\Models\SharedAccessSignature;

$credential = new StorageSharedKeyCredential('account-name', 'account-key');
$sasToken = $credential->generateSharedAccessSignature(
    'https://account-name.blob.core.windows.net/container/blob',
    [
        'startsAt' => new DateTime('2023-01-01'),
        'expiresAt' => new DateTime('2023-12-31'),
        'permissions' => 'rwdl'
    ]
);

Use Case: Generate time-limited SAS tokens for secure access to Azure Storage resources.

3. URI Handling

Parse/Construct Storage URIs:

use Azure\Storage\Common\StorageUri;
$uri = StorageUri::parse('https://account.blob.core.windows.net/container/blob');
$containerName = $uri->getContainerName(); // 'container'

Use Case: Validate or reconstruct URIs before making requests.

4. Retry Policies

Exponential Backoff: Configured in dependent SDKs (e.g., BlobServiceClient).

$blobClient = new BlobServiceClient(
    'https://account.blob.core.windows.net',
    $credential,
    [
        'retry' => [
            'maxRetries' => 5,
            'delay' => 3, // seconds
        ]
    ]
);

Custom Retry Logic: Extend Azure\Storage\Common\RetryPolicy for edge cases.

5. Error Handling

Standardized Exceptions:

try {
    $blobClient->getBlobProperties('container', 'blob');
} catch (Azure\Storage\Common\StorageException $e) {
    if ($e->getStatusCode() === 404) {
        // Handle "not found"
    }
}

Logging: Use $e->getErrorCode() and $e->getMessage() for debugging.

6. Workflow: Uploading a Blob

use Azure\Storage\Blob\BlobServiceClient;
use Azure\Storage\Common\StorageSharedKeyCredential;

// 1. Initialize client
$blobServiceClient = new BlobServiceClient(
    'https://account.blob.core.windows.net',
    new StorageSharedKeyCredential('account-name', 'account-key')
);

// 2. Get container client
$containerClient = $blobServiceClient->getContainerClient('my-container');

// 3. Upload file
$blobClient = $containerClient->getBlockBlobClient('file.txt');
$blobClient->upload('local-file.txt');

Gotchas and Tips

1. Pitfalls

No Direct Usage: This package is not meant to be used standalone. It’s a dependency for other Azure Storage SDKs (e.g., Blob, Queue, File). Installing it alone won’t work.
Deprecated Methods: Some methods (e.g., StorageUri::createFromParts()) may change. Check the Blob SDK docs for breaking changes.
Thread Safety: The SDK is thread-safe, but credentials and clients should not be shared across threads without synchronization.
SAS Token Inconsistencies: If using multiple packages (e.g., blob and file share), ensure the shared date helper is used consistently. Older code might rely on package-specific implementations.

2. Debugging

Enable Logging:
```
putenv('AZURE_STORAGE_LOG_LEVEL=debug');
```
Logs will appear in stderr (useful for CLI scripts).
Common Issues:
- 403 Forbidden: Verify StorageSharedKeyCredential or SAS token permissions.
- 404 Not Found: Check StorageUri parsing (e.g., missing / in paths).
- Timeouts: Increase retry.maxRetries or adjust network settings.
- SAS Token Errors: Ensure the shared date helper is used for timestamp formatting. Older code might fail if relying on package-specific implementations.

3. Configuration Quirks

Connection Strings: The package supports parsing connection strings, but manual credential setup is often clearer:

// Instead of parsing a connection string:
$connectionString = "DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...";
$credential = StorageSharedKeyCredential::fromConnectionString($connectionString);

Environment Variables: No built-in support, but you can wrap credentials in a service container (e.g., Laravel’s bind):

$app->bind(StorageSharedKeyCredential::class, function () {
    return new StorageSharedKeyCredential(
        env('AZURE_ACCOUNT_NAME'),
        env('AZURE_ACCOUNT_KEY')
    );
});

SAS Token Generation: If migrating from older versions, ensure your SAS token generation code uses the shared date helper for consistent timestamp formatting.

4. Extension Points

Custom Retry Policies: Implement Azure\Storage\Common\RetryPolicyInterface for custom logic (e.g., jitter delays).
Mocking for Tests: Use Azure\Storage\Common\Mock\MockStorageUri or dependency injection to stub dependencies.
Async Support: The package itself is synchronous, but dependent SDKs (e.g., Blob) support async via ReactPHP or Guzzle.
SAS Token Customization: Extend the shared date helper logic if you need custom timestamp formatting.

5. Laravel-Specific Tips

Service Provider Binding:

public function register()
{
    $this->app->singleton(BlobServiceClient::class, function ($app) {
        return new BlobServiceClient(
            config('azure.blob.endpoint'),
            new StorageSharedKeyCredential(
                config('azure

Storage Common Laravel Package