Static Service Client Facades

Version 2.4 of the AWS SDK for PHP adds the ability to enable and use static client facades. These “facades” provide an easy, static interface to service clients available in the service builder. For example, when working with a normal client instance, you might have code that looks like the following:

// Get the configured S3 client from the service builder
$s3 = $aws->get('s3');

// Execute the CreateBucket command using the S3 client
$s3->createBucket(array('Bucket' => 'your-new-bucket-name'));

With client facades enabled, you can also accomplish this with the following code:

// Execute the CreateBucket command using the S3 client
S3::createBucket(array('Bucket' => 'your-new-bucket-name'));

Enabling and using client facades

To enable static client facades to be used in your application, you must use the AwsCommonAws::enableFacades method when you setup the service builder.

// Include the Composer autoloader
require 'vendor/autoload.php';

// Instantiate the SDK service builder with my config and enable facades
$aws = Aws::factory('/path/to/my_config.php')->enableFacades();

This will setup the client facades and alias them into the global namespace. After that, you can use them anywhere to have more simple and expressive code for interacting with AWS services.

// List current buckets
echo "Current Buckets:n";
foreach (S3::getListBucketsIterator() as $bucket) {
    echo "{$bucket['Name']}n";
}

$args = array('Bucket' => 'your-new-bucket-name');
$file = '/path/to/the/file/to/upload.jpg';

// Create a new bucket and wait until it is available for uploads
S3::createBucket($args) and S3::waitUntilBucketExists($args);
echo "nCreated a new bucket: {$args['Bucket']}.n";

// Upload a file to the new bucket
$result = S3::putObject($args + array(
    'Key'  => basename($file),
    'Body' => fopen($file, 'r'),
));
echo "nCreated a new object: {$result['ObjectURL']}n";

You can also mount the facades into a namespace other than the global namespace. For example, if you want to make the client facades available in the “Services” namespace, you can do the following:

Aws::factory('/path/to/my_config.php')->enableFacades('Services');

$result = ServicesDynamoDb::listTables();

Why use client facades?

The use of static client facades is completely optional. We included this feature in the SDK in order to appeal to PHP developers who prefer static notation or who are familiar with PHP frameworks like CodeIgnitor, Laravel, or Kohana where this style of method invocation is common.

Though using static client facades has little real benefit over using client instances, it can make your code more concise and prevent you from having to inject the service builder or client instance into the context where you need the client object. This can make your code easier to write and understand. Whether or not you should use the client facades is purely a matter of preference.

How client facades work in the AWS SDK for PHP is similar to how facades work in the Laravel 4 Framework. Even though you are calling static classes, all of the method calls are proxied to method calls on actual client instances—the ones stored in the service builder. This means that the usage of the clients via the client facades can still be mocked in your unit tests, which removes one of the general disadvantages to using static classes in object-oriented programming. For information about how to test code that uses client facades, please see the Testing Code that Uses Client Facades section of the AWS SDK for PHP User Guide.

Though we are happy to offer this new feature, we we don’t expect you to change all of your code to use the static client facades. We are simply offering it as an alternative that may be more convenient or familiar to you. We still recommend using client instances as you have in the past and support the use of dependency injection. Be sure to let us know in the comments if you like this new feature and if you plan on using it.