Edwin Laravel Package

Getting Started

Minimal Setup

1. Installation Run composer require superdupercybertechno/edwin in your Laravel project.

2. Configuration Add the spaces driver to config/filesystems.php:

   'spaces' => [
       'driver' => 'spaces',
       'key' => env('DIGITAL_OCEAN_SPACES_KEY'),
       'secret' => env('DIGITAL_OCEAN_SPACES_SECRET'),
       'region' => env('DIGITAL_OCEAN_SPACES_REGION'),
       'bucket' => env('DIGITAL_OCEAN_SPACES_BUCKET'),
   ],
   

3. Environment Variables Populate .env with your DigitalOcean Spaces credentials:

   DIGITAL_OCEAN_SPACES_KEY=your_access_key
   DIGITAL_OCEAN_SPACES_SECRET=your_secret_key
   DIGITAL_OCEAN_SPACES_REGION=your_region (e.g., nyc3)
   DIGITAL_OCEAN_SPACES_BUCKET=your_bucket_name
   

4. First Use Case Use the spaces driver in your code:

   use Illuminate\Support\Facades\Storage;
   
   Storage::disk('spaces')->put('file.txt', 'Hello, Spaces!');
   

Implementation Patterns

Core Workflows

1. File Uploads

   // Upload a file from a local path
   Storage::disk('spaces')->putFile('folder', $request->file('file'));
   
   // Upload a file from a string
   Storage::disk('spaces')->put('file.txt', $content);
   

2. File Retrieval

   // Get file contents
   $contents = Storage::disk('spaces')->get('file.txt');
   
   // Download a file
   return Storage::disk('spaces')->download('file.pdf');
   

3. Directory Operations

   // Create a directory
   Storage::disk('spaces')->makeDirectory('new-folder');
   
   // List files in a directory
   $files = Storage::disk('spaces')->files('folder');
   

4. URL Generation

   // Get a temporary URL
   $url = Storage::disk('spaces')->temporaryUrl('file.jpg', now()->addMinutes(30));
   
   // Get a permanent URL
   $url = Storage::disk('spaces')->url('file.jpg');
   

Integration Tips

• Fallback Logic Use the spaces disk as a fallback in config/filesystems.php:

  'default' => env('FILESYSTEM_DRIVER', 'spaces'),
  

• Custom Disk Configuration Extend the driver for specific use cases (e.g., per-environment buckets):

  'spaces-dev' => [
      'driver' => 'spaces',
      'key' => env('DIGITAL_OCEAN_SPACES_KEY'),
      'secret' => env('DIGITAL_OCEAN_SPACES_SECRET'),
      'region' => env('DIGITAL_OCEAN_SPACES_REGION'),
      'bucket' => env('DIGITAL_OCEAN_SPACES_BUCKET_DEV'),
  ],
  

• Event Handling Listen for file system events (e.g., storage:file-published) and integrate with Spaces:

  Storage::disk('spaces')->dispatcher()->listen('*', function ($event) {
      // Custom logic for Spaces events
  });
  

Gotchas and Tips

Common Pitfalls

1. Credentials and Permissions

   • Ensure your Spaces access key has the correct permissions (e.g., Read/Write).
   • If using temporary URLs, validate the key’s Write permissions for the bucket.

2. Region Mismatch

   • Double-check the region in .env matches your Spaces endpoint (e.g., nyc3, sfo2).
   • Errors like Connection refused often stem from incorrect regions.

3. Bucket Existence

   • The bucket must exist before use. Create it via the DigitalOcean Control Panel or API.

4. Deprecated Methods

   • Avoid using Storage::cloud() or Storage::disk('spaces')->getAdapter() directly, as the package may not support all Flysystem methods.

5. CORS Issues

   • If serving files via a CDN or custom domain, configure CORS rules on the Spaces bucket.

Debugging Tips

• Enable Debugging Add this to config/filesystems.php to log errors:

  'spaces' => [
      'driver' => 'spaces',
      'debug' => env('APP_DEBUG', false),
      // ... other config
  ],
  

• Check HTTP Status Codes Use Storage::disk('spaces')->getAdapter()->getClient()->getLastResponse() to inspect API responses.

• Test Locally Use the local driver for development and switch to spaces in staging/production:

  'default' => env('APP_ENV') === 'local' ? 'local' : 'spaces',
  

Extension Points

1. Custom Metadata Extend the driver to add metadata (e.g., cache-control headers):

   Storage::disk('spaces')->put('file.jpg', $content, [
       'cache-control' => 'public, max-age=31536000',
   ]);
   

2. Presigned URLs Generate presigned URLs for private files:

   $url = Storage::disk('spaces')->temporaryUrl('private-file.pdf', now()->addHours(1));
   

3. Event Listeners Hook into Spaces events (e.g., file uploads) for analytics or notifications:

   Storage::disk('spaces')->dispatcher()->listen('file.stored', function ($event) {
       Log::info("File uploaded: {$event->path()}");
   });
   

4. Flysystem Adapter Access the underlying Flysystem adapter for advanced use cases:

   $adapter = Storage::disk('spaces')->getAdapter();
   $client = $adapter->getClient(); // League\Flysystem\AwsS3v3\AwsS3Adapter