README

A modern PHP library for interacting with Azure Blob Storage, with support for local Azurite emulator.

Features

• List all files in a blob storage container
• Delete specific files
• Upload new files
• Download specific files
• Support for local Azurite blob storage emulator
• Multiple authentication methods (Shared Key and SAS Token)
• Modern PHP 8.1+ syntax with strict typing
• Professional OOP design
• Comprehensive error handling

Installation

Install the package via composer:

composer require mutario/azure-storage-php

Usage

Initialize with Cloud Storage (Shared Key Authentication)

use Mutario\AzureStorage\BlobStorage;
use Mutario\AzureStorage\Config\BlobStorageConfig;

// Initialize with cloud storage credentials
$config = new BlobStorageConfig(
    accountName: 'your-account-name',
    containerName: 'your-container-name',
    blobEndpoint: 'https://your-account.blob.core.windows.net',
    authType: BlobStorageConfig::AUTH_TYPE_SHARED_KEY,
    accountKey: 'your-account-key'
);

$storage = new BlobStorage($config);

Initialize with SAS Token Authentication

use Mutario\AzureStorage\BlobStorage;
use Mutario\AzureStorage\Config\BlobStorageConfig;

// Initialize with SAS token
$config = BlobStorageConfig::createSasConfig(
    accountName: 'your-account-name',
    containerName: 'your-container-name',
    sasToken: 'sv=2020-08-04&ss=b&srt=sco&sp=rwdlacitfx&se=2023-12-31T23:59:59Z&st=2023-01-01T00:00:00Z&spr=https&sig=...'
);

$storage = new BlobStorage($config);

Initialize with Azurite (Local Development)

use Mutario\AzureStorage\BlobStorage;
use Mutario\AzureStorage\Config\BlobStorageConfig;

// Initialize with Azurite emulator
$config = BlobStorageConfig::createAzuriteConfig('your-container-name');
$storage = new BlobStorage($config);

List All Blobs

try {
    $blobs = $storage->listBlobs();
    foreach ($blobs as $blob) {
        echo "Name: {$blob['name']}\n";
        echo "Last Modified: {$blob['lastModified']}\n";
        echo "Size: {$blob['contentLength']} bytes\n";
        echo "Content Type: {$blob['contentType']}\n";
        echo "-------------------\n";
    }
} catch (RuntimeException $e) {
    echo "Error listing blobs: " . $e->getMessage();
}

Upload a File

try {
    $storage->uploadBlob(
        blobName: 'path/to/remote/file.txt',
        filePath: '/path/to/local/file.txt',
        contentType: 'text/plain' // optional
    );
    echo "File uploaded successfully!";
} catch (RuntimeException $e) {
    echo "Error uploading file: " . $e->getMessage();
}

Download a File

try {
    $storage->downloadBlob(
        blobName: 'path/to/remote/file.txt',
        destinationPath: '/path/to/local/destination.txt'
    );
    echo "File downloaded successfully!";
} catch (RuntimeException $e) {
    echo "Error downloading file: " . $e->getMessage();
}

Delete a File

try {
    $storage->deleteBlob('path/to/remote/file.txt');
    echo "File deleted successfully!";
} catch (RuntimeException $e) {
    echo "Error deleting file: " . $e->getMessage();
}

Error Handling

All methods throw RuntimeException when an error occurs. The exception message contains details about what went wrong. It's recommended to always wrap calls in try-catch blocks as shown in the examples above.

Authentication Methods

Shared Key Authentication

This is the traditional authentication method using your storage account key. It's recommended for server-side applications where you can securely store the account key.

SAS Token Authentication

SAS (Shared Access Signature) tokens provide limited access to your storage account resources. They are ideal for:

• Client-side applications where you don't want to expose your account key
• Providing temporary access to specific resources
• Implementing fine-grained access control

When using SAS tokens, make sure to:

• Generate tokens with the minimum required permissions
• Set appropriate expiration times
• Rotate tokens regularly for security
• Remove the leading '?' from the SAS token string if present

Development with Azurite

When developing locally, you can use the Azurite emulator. The library includes built-in support for Azurite with the correct default credentials and endpoint. Simply use the BlobStorageConfig::createAzuriteConfig() factory method to create a configuration for local development.

Make sure you have Azurite running locally on the default ports before using the library in local mode.

Requirements

• PHP 8.1 or higher
• ext-json
• GuzzleHttp 7.0 or higher

License

MIT License