Merge pull request #18 from aws/refactor-config

Refactoring config to support package-level configuration. Fixes #17.

.gitignore

@@ -1,4 +1,3 @@
 composer.lock
 composer.phar
-phpunit.xml
 vendor

README.md

@@ -18,24 +18,28 @@ The AWS Service Provider can be installed via [Composer](http://getcomposer.org)
 }
 ```
 
-## Usage
+## Configuration
+
+To use the AWS Service Provider, you must register the provider when bootstrapping your Laravel application.
 
-To use the AWS Service Provider, you must register the provider when bootstrapping your Laravel application. There are
-essentially two ways to do this.
+Publish the package configuration using Artisan.
 
-### 1. Use Laravel Configuration
+```sh
+php artisan config:publish aws/aws-sdk-php-laravel
+```
 
-Create a new `app/config/aws.php` configuration file with the following options:
+Update your settings in the generated `app/config/packages/aws/aws-sdk-php-laravel` configuration file.
 
 ```php
 return array(
-    'key'    => '<your-aws-access-key-id>',
-    'secret' => '<your-aws-secret-access-key>',
-    'region' => Aws\Common\Enum\Region::US_WEST_2,
+    'key'         => 'YOUR_AWS_ACCESS_KEY_ID',
+    'secret'      => 'YOUR_AWS_SECRET_KEY',
+    'region'      => 'us-east-1',
+    'config_file' => null,
 );
 ```
 
-Find the `providers` key in `app/config/app.php` and register the AWS Service Provider.
+Find the `providers` key in your `app/config/app.php` and register the AWS Service Provider.
 
 ```php
     'providers' => array(
@@ -44,7 +48,7 @@ Find the `providers` key in `app/config/app.php` and register the AWS Service Pr
     )
 ```
 
-Find the `aliases` key in `app/config/app.php` and add the AWS facade alias.
+Find the `aliases` key in your `app/config/app.php` and add the AWS facade alias.
 
 ```php
     'aliases' => array(
@@ -53,64 +57,29 @@ Find the `aliases` key in `app/config/app.php` and add the AWS facade alias.
     )
 ```
 
-### 2. Manual Instantiation
-
-You can also register the provider and configuration options at runtime. This could be done in your global bootstrapping
-process in `app/start/global.php`.
-
-```php
-use Aws\Common\Enum\Region;
-use Aws\Laravel\AwsServiceProvider;
-use Illuminate\Foundation\Application;
-
-// Instantiate a new application. This is normally done by the Laravel framework and the instance is available in
-// `app/start/global.php` for you to use.
-$app = new Application;
-
-// Register the AWS service provider and provide your configuration
-$app->register(new AwsServiceProvider($app), array(
-    'config' => array(
-        'aws' => array(
-            'key'    => '<your-aws-access-key-id>',
-            'secret' => '<your-aws-secret-access-key>',
-            'region' => Region::US_WEST_2,
-        ),
-    ),
-));
-```
-
-You can alternatively specify the path to an AWS config file (see [AWS SDK for PHP](http://github.com/aws/aws-sdk-php)
-for details about how to format this type of file).
-
-```php
-$app->register(new AwsServiceProvider($app), array('config' => array('aws' => '/path/to/aws/config/file.php')));
-```
-
-Either way, the value of `$app['config']['aws']` is passed directly into `Aws\Common\Aws::factory()`.
-
-### Retrieving and Using a Service Client
+## Usage
 
-In order to use the SDK from within your app, you need to retrieve it from the [Laravel IoC
+In order to use the AWS SDK for PHP within your app, you need to retrieve it from the [Laravel IoC
 Container](http://four.laravel.com/docs/ioc). The following example uses the Amazon S3 client to upload a file.
 
 ```php
 $s3 = App::make('aws')->get('s3');
 $s3->putObject(array(
-    'Bucket'     => '<your-bucket>',
-    'Key'        => '<the-name-of-your-object>',
-    'SourceFile' => '/path/to/the/file/you/are/uploading.ext',
+    'Bucket'     => 'YOUR_BUCKET',
+    'Key'        => 'YOUR_OBJECT_KEY',
+    'SourceFile' => '/the/path/to/the/file/you/are/uploading.ext',
 ));
 ```
 
-If the AWS Facade is registered within the `aliases` section of the application configuration, you can use
-the following more expressive method.
+If the AWS facade is registered within the `aliases` section of the application configuration, you can also use the
+following technique.
 
 ```php
 $s3 = AWS::get('s3');
 $s3->putObject(array(
-    'Bucket'     => '<your-bucket>',
-    'Key'        => '<the-name-of-your-object>',
-    'SourceFile' => '/path/to/the/file/you/are/uploading.ext',
+    'Bucket'     => 'YOUR_BUCKET',
+    'Key'        => 'YOUR_OBJECT_KEY',
+    'SourceFile' => '/the/path/to/the/file/you/are/uploading.ext',
 ));
 ```
 

phpunit.xml

@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit backupGlobals="false"
+         backupStaticAttributes="false"
+         bootstrap="./tests/bootstrap.php"
+         colors="false"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false"
+         syntaxCheck="false">
+
+    <testsuites>
+        <testsuite name="AwsServiceProvider Test Suite">
+            <directory>./tests/</directory>
+        </testsuite>
+    </testsuites>
+
+    <filter>
+        <whitelist addUncoveredFilesFromWhitelist="false">
+            <directory suffix=".php">src</directory>
+            <exclude>
+                <directory suffix=".php">vendor</directory>
+            </exclude>
+        </whitelist>
+    </filter>
+</phpunit>

src/Aws/Laravel/AwsFacade.php

@@ -19,7 +19,7 @@
 use Illuminate\Support\Facades\Facade;
 
 /**
- * AWS SDK for PHP service provider for Laravel applications
+ * Facade for the AWS service
  */
 class AwsFacade extends Facade
 {

src/Aws/Laravel/AwsServiceProvider.php

@@ -28,26 +28,32 @@
  */
 class AwsServiceProvider extends ServiceProvider
 {
+    const VERSION = '1.1.0';
+
     /**
-     * @inheritdoc
+     * Register the service provider.
+     *
+     * @return void
      */
     public function register()
     {
         $this->app['aws'] = $this->app->share(function ($app) {
+            // Retrieve the config
+            $config = $app['config']['aws'] ?: $app['config']['aws::config'];
+            if (isset($config['config_file'])) {
+                $config = $config['config_file'];
+            }
+
             // Instantiate the AWS service builder
-            $config = !empty($app['config']['aws']) ? $app['config']['aws'] : array();
             $aws = Aws::factory($config);
 
-            // Attach an event listener that will append the Laravel version number in the user agent string
+            // Attach an event listener that will append the Laravel and module version numbers to the user agent string
             $aws->getEventDispatcher()->addListener('service_builder.create_client', function (Event $event) {
-                // The version number is only available in BETA4+, so an extra check is needed
-                $version = defined('Illuminate\Foundation\Application::VERSION') ? Application::VERSION : '4.0.0';
-
-                // Add the listener to modify the UA string
                 $clientConfig = $event['client']->getConfig();
                 $commandParams = $clientConfig->get(Client::COMMAND_PARAMS) ?: array();
+                $userAgentSuffix = 'Laravel/' . Application::VERSION . ' L4MOD/' . AwsServiceProvider::VERSION;
                 $clientConfig->set(Client::COMMAND_PARAMS, array_merge_recursive($commandParams, array(
-                    UserAgentListener::OPTION => "Laravel/{$version}",
+                    UserAgentListener::OPTION => $userAgentSuffix,
                 )));
             });
 
@@ -56,9 +62,22 @@ public function register()
     }
 
     /**
-     * @inheritdoc
+     * Bootstrap the application events.
+     *
+     * @return void
      */
     public function boot()
     {
+        $this->package('aws/aws-sdk-php-laravel', 'aws');
+    }
+
+    /**
+     * Get the services provided by the provider.
+     *
+     * @return array
+     */
+    public function provides()
+    {
+        return array('aws');
     }
 }

src/config/config.php

@@ -0,0 +1,67 @@
+<?php
+/**
+ * Copyright 2013 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ * http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+return array(
+
+    /*
+    |--------------------------------------------------------------------------
+    | Your AWS Credentials
+    |--------------------------------------------------------------------------
+    |
+    | In order to communicate with an AWS service, you must provide your AWS
+    | credentials including your AWS Access Key ID and your AWS Secret Key. You
+    | can obtain these keys by logging into your AWS account and visiting
+    | https://console.aws.amazon.com/iam/home?#security_credential.
+    |
+    | To use credentials from your environment or to use IAM Instance Profile
+    | credentials, please remove these config settings from your config. For
+    | more information see http://docs.aws.amazon.com/aws-sdk-php-2/guide/latest/configuration.html
+    |
+    */
+    'key'    => 'YOUR_AWS_ACCESS_KEY_ID',
+    'secret' => 'YOUR_AWS_SECRET_KEY',
+
+    /*
+    |--------------------------------------------------------------------------
+    | AWS Region
+    |--------------------------------------------------------------------------
+    |
+    | Many AWS services are available in multiple regions. You should specify
+    | the AWS region you would like to use, but please remember that not every
+    | service is available in every region.
+    |
+    | These are the regions: us-east-1, us-west-1, us-west-2, us-gov-west-1
+    | eu-west-1, sa-east-1, ap-northeast-1, ap-southeast-1, ap-southeast-2
+    |
+    */
+    'region' => 'us-east-1',
+
+    /*
+    |--------------------------------------------------------------------------
+    | AWS Config File Location
+    |--------------------------------------------------------------------------
+    |
+    | Instead of specifying your credentials and region here, you can specify
+    | the location of an AWS SDK for PHP config file to use. These files provide
+    | more granular control over what credentials and regions you are using for
+    | each service. If you specify a filepath for this configuration setting,
+    | the others in this file will be ignored. See the SDK user guide for more
+    | information: http://docs.aws.amazon.com/aws-sdk-php-2/guide/latest/configuration.html#using-a-custom-configuration-file
+    |
+    */
+    'config_file' => null,
+
+);

tests/Aws/Laravel/Tests/AwsFacadeTest.php → tests/Aws/Laravel/Test/AwsFacadeTest.php

@@ -14,29 +14,24 @@
  * permissions and limitations under the License.
  */
 
-namespace Aws\Laravel\Tests;
+namespace Aws\Laravel\Test;
 
 use Aws\Laravel\AwsFacade as AWS;
-use Aws\Laravel\AwsServiceProvider;
-use Illuminate\Foundation\Application;
 
 /**
  * AwsFacade test cases
  */
-class AwsFacadeTest extends \PHPUnit_Framework_TestCase
+class AwsFacadeTest extends AwsServiceProviderTestCase
 {
     public function testFacadeCanBeResolvedToServiceInstance()
     {
-        // Setup the Laravel app and AWS service provider
-        $app = new Application();
-        $app['config'] = array();
-        $provider = new AwsServiceProvider($app);
-        $app->register($provider);
-        $provider->boot();
+        $app = $this->setupApplication();
+        $this->setupServiceProvider($app);
 
+        // Mount facades
         AWS::setFacadeApplication($app);
 
-        // Get an instance of a client (S3) to use for testing
+        // Get an instance of a client (S3) via its facade
         $s3 = AWS::get('s3');
         $this->assertInstanceOf('Aws\S3\S3Client', $s3);
     }