Aws Bundle Laravel Package

Getting Started

Install and wire it first. The bundle is Symfony 2-era, so confirm your Symfony version before anything else. On a modern app (Symfony 5/6), Composer may still resolve it, but the AWS SDK version it pulls is likely v2 — plan for a compatibility review before writing feature code.

composer require uam/aws-bundle

Register the bundle in app/AppKernel.php (Symfony 2/3) or config/bundles.php (Symfony 4+):

new UAM\AwsBundle\UAMAwsBundle(),

Configure credentials once, in config.yml / config/packages/uam_aws.yaml:

uam_aws:
    key:    "%aws_key%"
    secret: "%aws_secret%"
    region: "%aws_region%"

Keep the raw values in parameters.yml / .env, never in committed YAML. In production prefer instance-profile / IAM-role credentials and leave key/secret null so the SDK's default credential chain wins.

First use case: an S3 upload is the fastest smoke test. Grab the S3 service from the container, call putObject, and confirm the object appears in the bucket. If that works, the bundle is wired correctly and every other service (SQS, SNS, DynamoDB, SES) will use the same underlying client.

Where to look first: the bundle's DependencyInjection/Configuration.php for the exact config keys it accepts, and Resources/config/services.yml for the service IDs you'll inject. These two files tell you everything about what's actually exposed — the README is minimal.

Implementation Patterns

Inject the named services, don't build clients by hand. The whole point of the bundle is that it constructs and configures an Aws\Common\Aws factory (or equivalent) for you. Inject services by their container ID into your own services rather than instantiating S3Client/SqsClient directly — that keeps credentials in one place and makes mocking trivial.

Wrap it in your own application service. Don't spread $s3->putObject(...) calls across controllers. Create a thin StorageService / QueueService that takes the AWS client as a constructor argument and exposes domain methods (storeAvatar, enqueueEmail). This is the single most valuable pattern: when the bundle goes unmaintained (and with 2 stars, assume it might), you swap the implementation behind your wrapper instead of hunting call sites.

Queue consumers follow a loop-and-delete shape. For SQS:

1. receiveMessage with a WaitTimeSeconds of 20 (long polling).
2. Process each message.
3. deleteMessage only after success; on failure let it return to the queue for retry / DLQ.

Run this as a Symfony console command with --env=prod, and treat the bundle as just the transport — your message handling belongs in ordinary services.

Presigned URLs for direct-to-S3 uploads. Use the S3 service to generate a presigned PutObject URL server-side, hand it to the browser, and keep large payloads off your PHP workers. This is where a thin wrapper pays off: one method, one place to change the expiry/TTL policy.

One client, multiple regions. The bundle configures a single default region. For multi-region work, either define multiple Symfony services (each with its own client) or override the region per call if the SDK version supports it. Don't fight the bundle's single-region default in production.

Integration tip: keep AWS clients out of Doctrine transactions. Queue publishes and S3 writes inside a flush()-wrapped transaction will silently succeed or fail independently of the DB commit, and you'll get phantom messages. Publish after commit.

Gotchas and Tips

The biggest risk is abandonment. Two stars, zero dependents, no activity — treat it as a convenience wrapper, not a foundation. Pin the exact version in composer.json, and don't build abstractions that assume it stays current. If you're starting greenfield, using the official aws/aws-sdk-php directly with a small factory service is usually less risk for the same outcome.

Symfony version skew. The bundle's service definitions and bundle class target older Symfony APIs. On Symfony 4+ you may need to register services manually or adapt the bundle class; on Symfony 5/6 expect deprecation noise at minimum. Verify bin/console debug:container shows the AWS services before writing feature code.

AWS SDK version matters more than the bundle version. The bundle pins a specific SDK major. If your app also depends on aws/aws-sdk-php, Composer may resolve a version the bundle's service definitions don't match, producing Class not found or "method does not exist" errors at runtime. Check composer show aws/aws-sdk-php and the bundle's composer.json constraint.

Credentials: never commit them, and prefer roles. Empty key/secret should fall through to the SDK's default provider chain (env vars → instance profile → ECS task role). If the bundle requires non-null keys, that's a sign it predates modern credential handling — wrap it or patch the config.

Errors are SDK exceptions, not Symfony exceptions. Catch Aws\Common\Exception\... (or the v3 Aws\Exception\AwsException) explicitly around network calls. getAwsErrorCode() / getStatusCode() are what you switch on — not the message string, which changes.

Watch for silent pagination. S3 listings, SQS receives, and DynamoDB scans paginate. A single call returns a page, not everything. Use the SDK's iterator paginators or loop on IsTruncated / LastEvaluatedKey, otherwise you'll ship "missing data" bugs that only appear at scale.

Debugging: set debug: true in the bundle config (if supported) to enable SDK request logging, and check CloudTrail for the actual API call your app made — it's faster than guessing whether the bundle or your code dropped a parameter.

Extension point to know: Symfony's service container lets you decorate any bundle service. If the bundle's client construction is wrong for you (wrong region, custom endpoint for LocalStack/testing), decorate it in your own services.yaml rather than forking the bundle. Point the endpoint at http://localhost:4566 to test S3/SQS/DynamoDB locally before touching real AWS.