Microsoft Azure Storage PHP Client Libraries
This project will be in Community Support and Azure Storage team commits to validate and release every quarter, as long as there are PRs from community. Azure Storage team is unable to continue to add new features or provide bugfixes.
This project provides a set of PHP client libraries that make it easy to access Microsoft Azure Storage services (blobs, tables, queues and files). For documentation on how to host PHP applications on Microsoft Azure, please see the Microsoft Azure PHP Developer Center.
- azure-storage-blob
- azure-storage-table
- azure-storage-queue
- azure-storage-file
- azure-storage-common
Note
- If you are looking for the Service Bus, Service Runtime, Service Management or Media Services libraries, please visit https://github.com/Azure/azure-sdk-for-php.
- If you need big file (larger than 2GB) or 64-bit integer support, please install PHP 7 64-bit version.
Features
- Blobs
- create, list, and delete containers, work with container metadata and permissions, list blobs in container
- create block and page blobs (from a stream or a string), work with blob blocks and pages, delete blobs
- work with blob properties, metadata, leases, snapshot a blob
- Tables
- create and delete tables
- create, query, insert, update, merge, and delete entities
- batch operations
- Queues
- create, list, and delete queues, and work with queue metadata and properties
- create, get, peek, update, delete messages
- Files
- create, list, and delete file shares and directories
- create, delete and download files
Please check details on API reference documents.
Getting Started
Minimum Requirements
-
PHP 5.6 or above
-
See composer.json for dependencies
-
Required extension for PHP:
- php_fileinfo.dll
- php_mbstring.dll
- php_openssl.dll
- php_xsl.dll
-
Recommended extension for PHP:
- php_curl.dll
Download Source Code
To get the source code from GitHub, type
git clone https://github.com/Azure/azure-storage-php.git
cd ./azure-storage-php
Install via Composer
- Create a file named composer.json in the root of your project and add the following code to it:
{
"require": {
"microsoft/azure-storage-blob": "*",
"microsoft/azure-storage-table": "*",
"microsoft/azure-storage-queue": "*",
"microsoft/azure-storage-file": "*"
}
}
-
Download composer.phar in your project root.
-
Open a command prompt and execute this in your project root
php composer.phar install
Usage
There are four basic steps that have to be performed before you can make a call to any Microsoft Azure Storage API when using the libraries.
- First, include the autoloader script:
require_once "vendor/autoload.php";
-
Include the namespaces you are going to use.
To create any Microsoft Azure service client you need to use the rest proxy classes, such as BlobRestProxy class:
use MicrosoftAzure\Storage\Blob\BlobRestProxy;
To process exceptions you need:
use MicrosoftAzure\Storage\Common\ServiceException;
- To instantiate the service client you will also need a valid connection string. The format is:
DefaultEndpointsProtocol=[http|https];AccountName=[yourAccount];AccountKey=[yourKey]
Or:
BlobEndpoint=myBlobEndpoint;QueueEndpoint=myQueueEndpoint;TableEndpoint=myTableEndpoint;FileEndpoint=myFileEndpoint;SharedAccessSignature=sasToken
Or if AAD authentication is used:
BlobEndpoint=myBlobEndpoint;QueueEndpoint=myQueueEndpoint;TableEndpoint=myTableEndpoint;FileEndpoint=myFileEndpoint;AccountName=[yourAccount]
Note that account name is required.
- Instantiate a client object - a wrapper around the available calls for the given service.
$blobClient = BlobRestProxy::createBlobService($connectionString);
$tableClient = TableRestProxy::createTableService($connectionString);
$queueClient = QueueRestProxy::createQueueService($connectionString);
$fileClient = FileRestProxy::createFileService($connectionString);
Or for AAD authentication:
$blobClient = BlobRestProxy::createBlobServiceWithTokenCredential($token, $connectionString);
$queueClient = QueueRestProxy::createQueueServiceWithTokenCredential($token, $connectionString);
Note that Blob and Queue service supports AAD authentication.
Using Middlewares
To specify the middlewares, user have to create an array with middlewares and put it in the $requestOptions with key 'middlewares'. The sequence of the array will affect the sequence in which the middleware is invoked. The $requestOptions can usually be set in the options of an API call, such as MicrosoftAzure\Storage\Blob\Models\ListBlobOptions.
The user can push the middleware into the array with key 'middlewares' in services' $_options instead when creating them if the middleware is to be applied to each of the API call for a rest proxy. These middlewares will always be invoked after the middlewares in the $requestOptions. e.g.:
$tableClient = TableRestProxy::createTableService(
$connectionString,
$optionsWithMiddlewares
);
Each of the middleware should be either an instance of a sub-class that implements MicrosoftAzure\Storage\Common\Internal\IMiddleware, or a callable that follows the Guzzle middleware implementation convention.
User can create self-defined middleware that inherits from MicrosoftAzure\Storage\Common\Internal\Middlewares\MiddlewareBase.
Retrying failures
You can use bundled middlewares to retry requests in case they fail for some reason. First you create the middleware:
$retryMiddleware = RetryMiddlewareFactory::create(
RetryMiddlewareFactory::GENERAL_RETRY_TYPE, // Specifies the retry logic
3, // Number of retries
1000, // Interval
RetryMiddlewareFactory::EXPONENTIAL_INTERVAL_ACCUMULATION, // How to increase the wait interval
true // Whether to retry connection failures too, default false
);
Then you add the middleware when creating the service as explained above:
$optionsWithMiddlewares = [
'middlewares' = [
$retryMiddleware
],
];
$tableClient = TableRestProxy::createTableService(
$connectionString,
$optionsWithMiddlewares
);
Or by pushing it to the existing service:
$tableClient->pushMiddleware($retryMiddleware);
Following errors are not retried in current retry middleware:
- Authentication failures.
- "Resource Not Found" errors.
- Guzzle request exceptions that does not bear an HTTP response, e.g. failed to open stream, or cURL Connection reset by peer, etc. Note: Community contribution to cover the Guzzle request exceptions are welcomed.
Retry types
RetryMiddlewareFactory::GENERAL_RETRY_TYPE- General type of logic that handles retryRetryMiddlewareFactory::APPEND_BLOB_RETRY_TYPE- For the append blob retry only, currently the same as the general type
Interval accumulations
RetryMiddlewareFactory::LINEAR_INTERVAL_ACCUMULATION- The interval will be increased linearly, the nth retry will have a wait time equal to n * intervalRetryMiddlewareFactory::EXPONENTIAL_INTERVAL_ACCUMULATION- The interval will be increased exponentially, the nth retry will have a wait time equal to pow(2, n) * interval
Using proxies
To use proxies during HTTP requests, set system variable HTTP_PROXY and the proxy will be used.
Troubleshooting
Error: Unable to get local issuer certificate
cURL can't verify the validity of Microsoft certificate when trying to issue a request call to Azure Storage Services. You must configure cURL to use a certificate when issuing https requests by the following steps:
-
Download the cacert.pem file from cURL site.
-
Then either:
- Open your php.ini file and add the following line:
OR
curl.cainfo = "<absolute path to cacert.pem>"
- Point to the cacert in the options when creating the Relevant Proxy.
//example of creating the FileRestProxy $options["http"] = ["verify" => "<absolute path to cacert.pem>"]; FileRestProxy::createFileService($connectionString, $options);
- Open your php.ini file and add the following line:
Code samples
You can find samples in the samples folder.
Migrate from Azure SDK for PHP
If you are using Azure SDK for PHP to access Azure Storage Service, we highly recommend you to migrate to this SDK for faster issue resolution and quicker feature implementation. We are working on supporting the latest service features as well as improvement on existing APIs.
For now, Microsoft Azure Storage PHP client libraries share almost the same interface as the storage blobs, tables, queues and files APIs in Azure SDK for PHP. However, there are some minor breaking changes need to be addressed during your migration. You can find the details in BreakingChanges.md.
Need Help?
Be sure to check out the Microsoft Azure Developer Forums on Stack Overflow and github issues if you have trouble with the provided code.
Please note this project will be in Community Support and Azure Storage team commits to validate and release every quarter, as long as there are PRs from community. Azure Storage team is unable to continue to add new features or provide bugfixes.
Contribute Code or Provide Feedback
If you would like to become an active contributor to this project please follow the instructions provided in Azure Projects Contribution Guidelines. You can find more details for contributing in the CONTRIBUTING.md.
If you encounter any bugs with the library please file an issue in the Issues section of the project.
218 Sep 25, 2022
4 May 13, 2022
2 Oct 17, 2022
2 Nov 27, 2021
303 Oct 7, 2022
281 Nov 10, 2022
80 Nov 6, 2022
245 Dec 18, 2022
2 Oct 13, 2021
463 Dec 6, 2022
12 Nov 13, 2022
23 Oct 3, 2022
14 May 17, 2022
1.7k Dec 27, 2022
1 Dec 12, 2022
6 Jun 11, 2023
474 Dec 31, 2022
464 Dec 28, 2022
5 Aug 15, 2022