Getting Started

Minimal Setup

Install the Bundle:

composer require async-aws/async-aws-bundle

Enable the Bundle: Add to config/bundles.php (Symfony):
```
return [
    // ...
    AsyncAws\Bundle\AsyncAwsBundle::class => ['all' => true],
];
```
For Laravel, manually register a ServiceProvider (see Implementation Patterns).

Configure AWS Clients: Create config/packages/async_aws.yaml (Symfony) or config/async_aws.php (Laravel):

# Symfony example
async_aws:
    clients:
        s3:
            region: 'us-east-1'
            version: 'latest'
            credentials:
                provider: 'static'
                key: '%env(AWS_ACCESS_KEY_ID)%'
                secret: '%env(AWS_SECRET_ACCESS_KEY)%'

Autowire a Client:

// Symfony
use AsyncAws\S3\S3ClientInterface;

class MyService {
    public function __construct(private S3ClientInterface $s3) {}
}

For Laravel, use a ClientFactory or bind the interface manually.

First Use Case: Upload a file asynchronously:

$result = $this->s3->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'file.txt',
    'Body'   => fopen('local-file.txt', 'r'),
]);

Implementation Patterns

Symfony-Specific Workflows

Environment-Specific Configs: Override defaults per environment (e.g., config/packages/dev/async_aws.yaml):
```
async_aws:
    clients:
        s3:
            region: 'eu-west-1'  # Override for dev
```

Credential Providers: Use SSM or Secrets Manager for dynamic credentials:

async_aws:
    credential:
        provider: 'ssm'
        parameters:
            - '/prod/aws/access_key'
            - '/prod/aws/secret_key'

Client Overrides: Extend or replace a client in a service:

// config/services.yaml
services:
    App\Service\CustomS3Client:
        parent: asyncAws.s3Client
        arguments:
            - '@custom_s3_config'  # Custom config service

Event-Driven Patterns: Combine with Symfony Messenger for async processing:

use AsyncAws\Sqs\SqsClientInterface;
use Symfony\Component\Messenger\MessageBusInterface;

class SqsConsumer {
    public function __construct(
        private SqsClientInterface $sqs,
        private MessageBusInterface $bus
    ) {}

    public function consume(): void {
        $messages = $this->sqs->receiveMessage(['QueueUrl' => 'my-queue']);
        foreach ($messages as $message) {
            $this->bus->dispatch(new ProcessMessage($message));
        }
    }
}

Laravel Adaptation

Service Provider: Create AsyncAwsServiceProvider.php:

use AsyncAws\Bundle\DependencyInjection\AsyncAwsExtension;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class AsyncAwsServiceProvider extends \Illuminate\Support\ServiceProvider {
    public function register() {
        $container = $this->app->make(ContainerBuilder::class);
        $extension = new AsyncAwsExtension();
        $extension->load([], $container);
        $this->app->set('asyncAws', $container->get('asyncAws'));
    }
}

Configuration Binding: Bind the config in config/async_aws.php:

return [
    'clients' => [
        's3' => [
            'region' => env('AWS_REGION', 'us-east-1'),
            'credentials' => [
                'provider' => 'static',
                'key' => env('AWS_ACCESS_KEY_ID'),
                'secret' => env('AWS_SECRET_ACCESS_KEY'),
            ],
        ],
    ],
];

Autowiring: Extend Laravel’s autowiring in app/Providers/AppServiceProvider.php:

use Illuminate\Contracts\Container\BindingResolutionException;

public function register(): void {
    app()->resolving(AsyncAws\S3\S3ClientInterface::class, function ($client) {
        return app('asyncAws')->get('s3Client');
    });
}

Async Handling: Use Spatie\Async or Laravel Queues to bridge async/await:

use Spatie\Async\Async;

Async::onQueue('aws')->run(function () {
    $result = $this->s3->putObject([...]);
    return $result;
});

Integration Tips

Logging: Enable the async_aws Monolog channel in config/packages/monolog.yaml:
```
monolog:
    channels: ['async_aws']
```

Retry Strategies: Configure retries per client:

async_aws:
    clients:
        sqs:
            retry:
                max_attempts: 3
                delay: 100  # ms

Testing: Use MockClient for unit tests:

use AsyncAws\S3\MockS3Client;

$mock = new MockS3Client();
$mock->shouldReceive('putObject')->andReturn(new PutObjectResponse());
$this->container->set('asyncAws.s3Client', $mock);

Performance:
- Credential Caching: Enable async_aws.credential.cache to avoid repeated IAM calls.
- Connection Pooling: Reuse clients (e.g., S3ClientInterface) across requests.

Gotchas and Tips

Pitfalls

PHP Version Mismatch:
- Error: Class 'AsyncAws\...' not found or PHP 8.2 required.
- Fix: Ensure php >=8.2 and async-aws/core: ^3.0 in composer.json.
Symfony vs. Laravel DI Conflicts:
- Error: Extension class "AsyncAws\Bundle\DependencyInjection\AsyncAwsExtension" not found in Laravel.
- Fix: Manually register the AsyncAwsExtension in a ServiceProvider (see Implementation Patterns).
Async/Await Misuse:
- Error: Call to undefined function await() or hung requests.
- Fix: Use Spatie\Async or Laravel Queues to handle async operations in a synchronous framework.
Credential Provider Conflicts:
- Error: Invalid credential provider configuration.
- Fix: Ensure credential_provider and credential_provider_cache are not both defined (see Changelog 1.12.3).
Missing Services:
- Error: Service "asyncAws.<client>Client" not found.
- Fix: Verify the client is listed in async_aws.clients and the async-aws/<service> package is installed (e.g., async-aws/s3).

Debugging Tips

Enable Debug Mode: Set debug: true in config/packages/async_aws.yaml to log client configurations:
```
async_aws:
    debug: true
```
Check Logs: Monitor the async_aws channel for credential cache failures or client errors:
```
bin/console debug:config async_aws
```
Validate Config: Use Symfony’s config validator:
```
bin/console debug:config-validator async_aws
```
Async Debugging: For Laravel, use Spatie\Async\Debugging to inspect async jobs:
```
Async::debug();
```

Extension Points

Custom Clients: Extend the bundle by creating a custom Extension:

use Symfony\Component\DependencyInjection\Extension\ExtensionInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
use Symfony\Component\Config\FileLocator;

class CustomAsyncAwsExtension extends AsyncAwsExtension {
    public function load(array $configs, ContainerBuilder $container) {
        parent::load($configs, $container);
        $loader = new YamlFileLoader(
            $container,
            new FileLocator(__DIR__.'/../Resources/config')
        );
        $loader->load('custom_clients.yaml');
    }
}

Middleware: Add custom middleware to AWS clients:

async_aws:
    clients:
        s3:
            middleware:
                - '@custom_middleware'

Event Listeners:

Async Aws Bundle Laravel Package