S3 Laravel Package

Getting Started

Install the package via Composer:

composer require async-aws/s3

Initialize the client using default credentials (e.g., environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and optionally AWS_REGION):

use AsyncAws\S3\S3Client;

$s3 = new S3Client();

The fastest first use case is uploading a small file:

$s3->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'path/to/object.txt',
    'Body' => 'Hello world',
]);

Check documentation at https://async-aws.com/clients/s3.html for core operations and request builders.

Implementation Patterns

• Stream large uploads/downloads: Use GuzzleHttp\Psr7\StreamWrapper or PHP stream resources for memory-efficient handling:

  $s3->putObject([
      'Bucket' => 'my-bucket',
      'Key' => 'large-file.dat',
      'Body' => fopen('/tmp/large-file.dat', 'r'),
  ]);
  

• Presigned URLs: Generate time-limited access links:

  $presigner = new \AsyncAws\S3\Presigner($s3);
  $url = $presigner->getPresignedUrl('GetObject', [
      'Bucket' => 'my-bucket',
      'Key' => 'private-file.txt',
  ], '+10 minutes');
  

• Multipart uploads: Use createMultipartUpload() + uploadPart() + completeMultipartUpload() for reliability with large objects.
• Batch operations: Leverage listObjectsV2() with pagination or deleteObjects() for bulk deletions.
• Regional optimization: Explicitly configure region early—especially for newer or local zones (ap-southeast-7, mx-central-1, etc.)—to avoid routing overhead:

  $s3 = new S3Client(['region' => 'ap-southeast-7']);
  

Gotchas and Tips

• Type safety in v2+: getContentLength() and similar fields now use int. Ensure your validation/error handling reflects this—especially if migrating from v1.
• Metadata naming: Starting in v2.10+, internally prepended AWS prefixes (e.g., x-amz-meta-) appear on GetObject/HeadObject metadata keys. Normalize keys if accessing raw metadata.
• Checksums & integrity: v2.8.0+ enables CRC64NVME and full-object checksums by default for uploads—verify your pipelines expect extra headers.
• Path-style vs. host-style: If using custom endpoints or buckets with dots (e.g., my.bucket), explicitly enable s3PathStyleEndpoint: true in client config.
• Enums: Prefer typed enums (e.g., StorageClass::GLACIER) over strings—unknown values fall back to UNKNOWN_TO_SDK to avoid silent failures.
• Nullability: Explicit null is now accepted for optional fields (e.g., 'Tagging' => null), useful for resetting configurations.
• Region naming: New regions (eu-isoe-west-1, us-isof-*, mx-central-1) require up-to-date SDK versions—check changelogs when testing compliance/fips endpoints.