Ezplatform Aws S3 Adapter Laravel Package

Getting Started

Minimal Setup

1. Installation Add the package via Composer:

   composer require contextualcode/ezplatform-aws-s3-adapter
   

2. Configuration Publish the package config:

   php artisan vendor:publish --provider="ContextualCode\EzPlatformAwsS3Adapter\EzPlatformAwsS3AdapterServiceProvider" --tag="config"
   

   Update config/ezplatform-aws-s3-adapter.php with your AWS credentials and bucket settings:

   'buckets' => [
       'default' => [
           'key'    => env('AWS_ACCESS_KEY_ID'),
           'secret' => env('AWS_SECRET_ACCESS_KEY'),
           'bucket' => env('AWS_S3_BUCKET'),
           'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
       ],
   ],
   

3. First Use Case: File Upload Inject the adapter into a service or controller:

   use ContextualCode\EzPlatformAwsS3Adapter\S3FileAdapter;
   
   public function __construct(S3FileAdapter $s3Adapter) {
       $this->s3Adapter = $s3Adapter;
   }
   
   public function uploadFile($filePath, $destinationPath) {
       $this->s3Adapter->save($filePath, $destinationPath);
   }
   

Implementation Patterns

Core Workflows

1. File Operations

   • Upload/Download:

     $this->s3Adapter->save($localPath, $s3Path); // Upload
     $this->s3Adapter->load($s3Path, $localPath); // Download
     

   • Streaming for Large Files: Use streamSave() and streamLoad() to handle large files without memory issues:

     $this->s3Adapter->streamSave($localPath, $s3Path);
     

2. Integration with eZ Platform

   • Content File Storage: Configure the adapter as the default file system in config/ezplatform.yml:

     system:
       site:
         file_system:
           default: s3
     

   • Custom Field Types: Extend ezplatform-aws-s3-adapter for custom field types (e.g., ezplatform-aws-s3-adapter:file in field type definitions).

3. URL Generation

   • Generate pre-signed URLs for temporary access:

     $url = $this->s3Adapter->getUrl($s3Path, '+1 hour');
     

Advanced Patterns

• Bucket-Specific Adapters: Instantiate adapters for different buckets:

  $adapter = new S3FileAdapter('custom_bucket');
  

• Event Listeners: Hook into FileSystemEvents (e.g., FileSystemCreated, FileSystemDeleted) for post-upload actions:

  $this->events->listen(
      \EzSystems\PlatformHttpCache\Event\FileSystemCreatedEvent::class,
      function ($event) {
          // Log or process the uploaded file
      }
  );
  

Gotchas and Tips

Common Pitfalls

1. Permissions

   • Ensure IAM roles have s3:PutObject, s3:GetObject, and s3:DeleteObject permissions.
   • Fix: Test credentials with aws s3 ls or the AWS CLI.

2. CORS Configuration

   • If direct uploads from browsers fail, configure CORS on the S3 bucket:

     <?xml version="1.0" encoding="UTF-8"?>
     <CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
       <CORSRule>
         <AllowedOrigin>*</AllowedOrigin>
         <AllowedMethod>PUT</AllowedMethod>
         <AllowedMethod>POST</AllowedMethod>
         <AllowedMethod>GET</AllowedMethod>
         <AllowedHeader>*</AllowedHeader>
       </CORSRule>
     </CORSConfiguration>
     

3. Path Handling

   • S3 paths are case-sensitive. Use consistent casing (e.g., lowercase) in save()/load() calls.
   • Tip: Normalize paths before upload:

     $normalizedPath = strtolower($s3Path);
     

4. Large File Timeouts

   • Default PHP timeouts may fail for large files. Increase max_execution_time or use streaming:

     ini_set('max_execution_time', 300); // 5 minutes
     

Debugging Tips

• Enable Debugging: Set debug: true in the config to log AWS SDK errors:

  'debug' => env('APP_DEBUG', false),
  

• AWS SDK Logging: Configure the AWS SDK to log requests:

  \Aws\setLogger(new \Monolog\Logger('aws'));
  

Extension Points

1. Custom Metadata Add metadata during upload:

   $this->s3Adapter->save($localPath, $s3Path, [
       'ContentType' => 'image/jpeg',
       'CacheControl' => 'max-age=31536000',
   ]);
   

2. Lifecycle Policies Use S3 lifecycle rules (via AWS Console) to auto-archive or delete old files.

3. Custom Storage Classes Override the default storage class (e.g., STANDARD_IA):

   $this->s3Adapter->save($localPath, $s3Path, [], 'STANDARD_IA');
   

Performance

• Batch Operations: Use S3Client directly for bulk operations (e.g., multiUpload):

  $s3 = $this->s3Adapter->getClient();
  $result = $s3->createMultiPartUpload(['Bucket' => $bucket, 'Key' => $key]);
  

• CDN Integration: Configure CloudFront or Cloudflare in front of S3 for faster delivery.