Getting Started

Minimal Steps to First Use

Install the Package

composer require superdupercybertechno/crawford

Publish the config (if needed) with:

php artisan vendor:publish --provider="SuperDuperCyberTechno\Crawford\CrawfordServiceProvider"

Configure the Driver Add the scaleway filesystem to config/filesystems.php:

'scaleway' => [
    'driver' => 'scaleway',
    'key' => env('SCALEWAY_OBJECT_STORAGE_KEY'),
    'secret' => env('SCALEWAY_OBJECT_STORAGE_SECRET'),
    'region' => env('SCALEWAY_OBJECT_STORAGE_REGION'),
    'bucket' => env('SCALEWAY_OBJECT_STORAGE_BUCKET'),
],

Set Environment Variables Add credentials to .env:

SCALEWAY_OBJECT_STORAGE_KEY=your_access_key
SCALEWAY_OBJECT_STORAGE_SECRET=your_secret_key
SCALEWAY_OBJECT_STORAGE_REGION=your_region (e.g., "fr-par")
SCALEWAY_OBJECT_STORAGE_BUCKET=your_bucket_name

First Usage Use the filesystem in your code:

use Illuminate\Support\Facades\Storage;

// Upload a file
Storage::disk('scaleway')->put('path/to/file.txt', 'contents');

// Get a file URL
$url = Storage::disk('scaleway')->url('path/to/file.txt');

// Download a file
return Storage::disk('scaleway')->download('path/to/file.txt');

Implementation Patterns

Core Workflows

File Uploads Leverage Laravel’s put() and putFile() methods for seamless uploads:

// Upload a string
Storage::disk('scaleway')->put('file.txt', 'Hello, Scaleway!');

// Upload a file from a request
$file = request()->file('avatar');
Storage::disk('scaleway')->putFile('avatars', $file);

File Retrieval Use get() and download() for reading files:

// Get file contents
$contents = Storage::disk('scaleway')->get('file.txt');

// Stream a file for download
return Storage::disk('scaleway')->download('file.pdf');

URL Generation Generate public URLs for files:

$url = Storage::disk('scaleway')->url('public/image.jpg');

Directory Operations Manage directories with mkdir(), exists(), and delete():

// Create a directory
Storage::disk('scaleway')->mkdir('new-folder');

// Check if a file/directory exists
if (Storage::disk('scaleway')->exists('file.txt')) {
    // Handle file
}

File Metadata Retrieve file metadata (size, last modified, etc.):
```
$metadata = Storage::disk('scaleway')->metadata('file.txt');
```

Integration Tips

Fallback Filesystems: Use the fallback option in filesystems.php to redirect to another disk if Scaleway fails:

'scaleway' => [
    'driver' => 'scaleway',
    'key' => env('SCALEWAY_OBJECT_STORAGE_KEY'),
    'fallback' => 'local', // Fallback to local disk if Scaleway is unavailable
],

Custom Disk Names: Define multiple Scaleway disks (e.g., scaleway-primary, scaleway-backup) for different buckets or regions.

Event Handling: Listen to filesystem events (e.g., filesystem.creating, filesystem.deleting) for logging or notifications:

Storage::disk('scaleway')->put('file.txt', 'contents');
// Triggered events can be listened to via Laravel's event system.

Temporary URLs: Generate time-limited URLs for private files using Scaleway’s presigned URLs (if the package supports it; may require custom extension).

Gotchas and Tips

Pitfalls

Deprecated or Missing Features
- The package is last updated in 2019 and may not support newer Laravel versions (e.g., 10.x) or Scaleway API changes. Test thoroughly.
- No built-in support for presigned URLs: If you need temporary access links, you’ll need to implement this manually using Scaleway’s SDK or extend the package.
Region/Bucket Sensitivity
- Ensure the region and bucket in .env match exactly (case-sensitive) with your Scaleway setup. Typos here will cause silent failures.

Error Handling

Scaleway may return cryptic errors (e.g., 403 Forbidden for invalid credentials). Wrap operations in try-catch blocks:

try {
    Storage::disk('scaleway')->put('file.txt', 'contents');
} catch (\Exception $e) {
    Log::error("Scaleway upload failed: " . $e->getMessage());
    // Fallback logic
}

Large File Uploads
- Scaleway has limits on file sizes and upload speeds. For large files, consider:
  - Chunked uploads (not natively supported; may require custom logic).
  - Using Scaleway’s SDK directly for advanced options.
CORS and Public Access
- If files need to be publicly accessible, ensure the bucket’s CORS policy is configured in the Scaleway console. The package does not handle this automatically.

Debugging Tips

Enable Debugging: Add 'debug' => true to the filesystem config to log requests/responses:

'scaleway' => [
    'driver' => 'scaleway',
    'debug' => true, // Logs HTTP requests/responses
    'key' => env('SCALEWAY_OBJECT_STORAGE_KEY'),
],

Check Laravel logs (storage/logs/laravel.log) for details.

Test with a Small Bucket: Use a non-production bucket during development to avoid accidental data loss.
Validate Credentials: Test credentials manually via Scaleway’s CLI or SDK before integrating:
```
swoosh bucket list --key YOUR_KEY --secret YOUR_SECRET --region YOUR_REGION
```

Extension Points

Customize HTTP Client Override the underlying HTTP client (e.g., Guzzle) by binding a custom instance to the container:

$this->app->singleton(\Illuminate\Http\Client\Factory::class, function () {
    return new \Illuminate\Http\Client\Factory(new \GuzzleHttp\Client([
        'timeout' => 30,
        'connect_timeout' => 5,
    ]));
});

Add Presigned URL Support Extend the SuperDuperCyberTechno\Crawford\ScalewayAdapter class to add methods for generating temporary URLs:

// Example pseudo-code
public function temporaryUrl($path, $minutes = 30) {
    // Use Scaleway SDK to generate a presigned URL
    return $url;
}

Event Dispatching Extend the adapter to dispatch events for critical operations (e.g., file.uploaded):

use Illuminate\Support\Facades\Event;

// Inside the adapter's put() method
Event::dispatch('file.uploaded', ['disk' => 'scaleway', 'path' => $path]);

Fallback Logic Implement custom fallback behavior when Scaleway fails. For example, retry or log the failure:

'scaleway' => [
    'driver' => 'scaleway',
    'fallback' => function () {
        Log::warning("Scaleway unavailable, falling back to local disk.");
        return 'local';
    },
],

Crawford Laravel Package