Aws S3 Adapter Laravel Package

Getting Started

1. Validate fit before installing. This package is a Gaufrette adapter, not a Laravel filesystem driver. For a modern Laravel app, the default Storage::disk('s3') / Flysystem path is almost always the better day-to-day choice. Use this package only if you already have Gaufrette-based code or a legacy integration.
2. Check dependency viability. Last release was 2017. Confirm that gaufrette/aws-s3-adapter, knplabs/gaufrette, and aws/aws-sdk-php resolve under your PHP/Laravel version:

   composer require gaufrette/aws-s3-adapter aws/aws-sdk-php
   composer show gaufrette/aws-s3-adapter
   

   If Composer pulls an old AWS SDK or conflicts with Laravel’s Flysystem dependencies, stop and use Laravel’s native S3 disk instead.
3. Look first at:
   • The adapter README and vendor/gaufrette/aws-s3-adapter/src/AwsS3.php for the exact constructor signature.
   • Gaufrette’s Filesystem API (read, write, exists, delete, listKeys, etc.).
   • Laravel’s config/filesystems.php S3 disk for bucket/region/credentials, so you do not duplicate env configuration.
4. First use case: write/read a file under a prefix.

   use Aws\S3\S3Client;
   use Gaufrette\Adapter\AwsS3;
   use Gaufrette\Filesystem;
   
   $s3 = new S3Client([
       'version' => 'latest',
       'region'  => config('filesystems.disks.s3.region'),
       'credentials' => [
           'key'    => config('filesystems.disks.s3.key'),
           'secret' => config('filesystems.disks.s3.secret'),
       ],
   ]);
   
   // Confirm constructor args in the installed adapter version.
   $adapter = new AwsS3($s3, config('filesystems.disks.s3.bucket'), 'imports');
   $filesystem = new Filesystem($adapter);
   
   $filesystem->write('example.txt', 'hello');
   $contents = $filesystem->read('example.txt');
   

5. Bind it once. Create a small service provider binding Gaufrette\Filesystem or a domain-specific wrapper as a singleton, keyed by bucket/prefix. Avoid constructing S3 clients throughout controllers and jobs.

Implementation Patterns

• Wrap Gaufrette behind an application service. Do not inject Gaufrette\Filesystem everywhere. Create DocumentStorage, UploadStorage, or similar with methods like store(), get(), delete(), exists(). This keeps Gaufrette replaceable.
• One filesystem per bucket/prefix. Use separate bindings for different concerns:

  $this->app->singleton('storage.uploads', function ($app) {
      $client = new S3Client([...]);
      return new Filesystem(new AwsS3($client, $bucket, 'uploads'));
  });
  

• Use Laravel config as the source of truth. Reuse filesystems.disks.s3 values for bucket, region, endpoint, and credentials. In production prefer IAM roles/instance profiles over long-lived keys.
• Prefix by tenant/feature. Since S3 has no real directories, enforce isolation with prefixes such as tenants/{tenant_id}/documents/. Normalize keys before writing.
• Use S3Client directly for presigned URLs. Gaufrette is for object CRUD, not URL signing. Generate temporary download/upload URLs with the same S3Client:

  $cmd = $s3->getCommand('GetObject', [
      'Bucket' => $bucket,
      'Key'    => 'uploads/example.pdf',
  ]);
  $url = (string) $s3->createPresignedRequest($cmd, '+15 minutes')->getUri();
  

• Use Gaufrette for simple reads/writes, S3 SDK for large or advanced operations. For multipart uploads, streaming, object metadata, storage class, or server-side encryption, call the AWS SDK directly. Gaufrette’s write() takes a string, so avoid loading large files into memory.
• Queue-friendly usage. Pass bucket/key strings to jobs, not Filesystem instances. Rebuild or resolve the filesystem inside the job. This keeps payloads serializable and avoids stale credentials.
• Testing pattern. Bind an in-memory Gaufrette filesystem for tests when possible:

  use Gaufrette\Adapter\InMemory;
  use Gaufrette\Filesystem;
  
  $this->app->instance('storage.uploads', new Filesystem(new InMemory()));
  

  If you need to test S3-specific behavior, mock S3Client or use a local S3-compatible service such as MinIO.
• Laravel integration boundary. You can use this package inside Laravel services, commands, jobs, and actions. Do not assume it plugs into Storage::disk(), Storage::fake(), or Laravel’s filesystem macros. If you need Laravel-native APIs, use Flysystem/Laravel Storage instead.
• Migration pattern. If existing code uses Gaufrette, introduce a wrapper interface and migrate call sites to it. Later you can swap the Gaufrette implementation for Laravel Storage without changing domain code.

Gotchas and Tips

• Stale package risk is the main gotcha. Last release in 2017 means PHP 8+, AWS SDK v3, and modern Laravel compatibility are not guaranteed. Check the adapter’s constructor and AWS SDK version before committing. If it works, pin versions and isolate it.
• Constructor and option quirks. The adapter signature and supported options vary by version. Confirm whether it expects S3Client, bucket, prefix, and options in that order. Do not assume support for ACLs, storage classes, content types, or custom endpoints.
• Prefix handling. Leading/trailing slashes can produce surprising keys. Normalize prefixes and keys consistently, and test exists()/read() with exact keys.
• S3 has no real directories. Gaufrette’s directory-like methods are prefix simulations. Rename/copy operations may be copy-then-delete and are not atomic. Do not rely on rename semantics for critical workflows.
• Do not list large prefixes casually. keys()/listKeys() over a large bucket can be slow and expensive. For large inventories, use the AWS SDK paginator directly and filter by prefix.
• Handle two exception families. Gaufrette throws filesystem exceptions such as file-not-found; the AWS SDK throws Aws\Exception\AwsException. Catch both at the boundary and log the S3 error code/request ID.
• IAM permissions matter. Typical needs are s3:GetObject, s3:PutObject, s3:DeleteObject, and s3:ListBucket scoped to the bucket/prefix. Multipart uploads may also need abort permissions.
• Local S3/MinIO needs explicit client config. If using an S3-compatible endpoint, configure endpoint, use_path_style_endpoint, and region correctly on S3Client. The Gaufrette adapter may not expose all client options.
• Public URLs and ACLs are not Gaufrette’s job. Many buckets now block ACLs. Prefer private buckets plus presigned URLs, CloudFront, or a bucket policy. Do not expect write() to set Content-Type or public-read automatically unless the adapter version supports it.
• Debug at the AWS SDK layer. Enable SDK debug logging temporarily, inspect AwsException messages, and verify with a direct headObject() call. Laravel logs alone often hide the S3 request ID.
• Avoid user-controlled bucket names. Keep bucket and prefix configuration server-side. Validate object keys and scope them under a tenant prefix.
• Extension point: decorate, don’t fork. If you need logging, key normalization, retries, or metrics, wrap the Gaufrette filesystem or S3 client in a decorator/service. Forking a 2017 adapter is usually a maintenance trap.
• Laravel config caching. If credentials come from env(), run php artisan config:cache consistently and remember queue workers may need restarts after config changes. Prefer IAM roles in production to reduce credential handling.