Cloud Storage

<?php

declare(strict_types=1);

use Illuminate\Support\Arr;
use Illuminate\Support\Str;

// The whole difference between a local disk and a bucket is this array.
// Reading it as data makes the shape obvious before any AWS call happens.
$s3 = [
    'driver' => 's3',
    'bucket' => 'app-uploads-eu',
    'region' => 'eu-west-1',
    'key' => '',
    'secret' => '',
    'url' => 'https://cdn.example.com',
    'use_path_style_endpoint' => false,
];

// An empty key is not a mistake. The driver only builds a credentials array
// when key and secret are both non-empty, so blank means "use the host role".
echo (! empty($s3['key']) && ! empty($s3['secret'])) ? 'static keys' : 'host role', PHP_EOL;

// With 'url' set, url() is that host plus the object key.
echo Str::finish(Arr::get($s3, 'url'), '/').'invoices/2026-03.pdf', PHP_EOL;

// Without it, the SDK builds the bucket's own virtual-hosted address.
echo sprintf('https://%s.s3.%s.amazonaws.com/%s', $s3['bucket'], $s3['region'], 'invoices/2026-03.pdf'), PHP_EOL;

// Output:
// host role
// https://cdn.example.com/invoices/2026-03.pdf
// https://app-uploads-eu.s3.eu-west-1.amazonaws.com/invoices/2026-03.pdf

<?php
// app/Http/Controllers/ReportController.php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Models\Report;
use Illuminate\Http\RedirectResponse;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Storage;

final class ReportController extends Controller
{
    public function download(Report $report): RedirectResponse
    {
        // Gate::authorize(), not $this->authorize(): the Laravel 13 base
        // controller ships without the AuthorizesRequests trait.
        Gate::authorize('view', $report);

        // Mark the object private at write time, not at read time.
        //   Storage::disk('s3')->put($path, $bytes, 'private');
        //
        // Then hand out a presigned URL. The client fetches the bytes from
        // S3; this request only issues the signature and redirects, so a
        // two-gigabyte report does not occupy a PHP worker.
        return redirect(
            Storage::disk('s3')->temporaryUrl($report->path, now()->addMinutes(5))
        );
    }
}

// The s3 driver always reports providesTemporaryUrls() as true, so no guard
// is needed here. A local disk does not, unless it has 'serve' => true --
// which is why code that works in production can throw in development:
//   RuntimeException: This driver does not support creating temporary URLs.

<?php
// app/Console/Commands/MigrateUploadsToS3.php

declare(strict_types=1);

namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Storage;

final class MigrateUploadsToS3 extends Command
{
    protected $signature = 'uploads:migrate {--dry-run}';

    public function handle(): int
    {
        $from = Storage::disk('local');
        $to = Storage::disk('s3');

        // Paths are relative to the disk root on both sides, which is the
        // reason this copy needs no rewriting of database columns: the same
        // string identifies the file on either disk.
        foreach ($from->allFiles('uploads') as $path) {
            if ($to->exists($path)) {
                continue;
            }

            $this->line($path);

            if ($this->option('dry-run')) {
                continue;
            }

            // readStream keeps memory flat for large files; put() accepts a
            // resource as well as a string.
            $stream = $from->readStream($path);
            $to->writeStream($path, $stream);
        }

        // Only after this has run clean should FILESYSTEM_DISK change. Flip
        // it first and every old path becomes a miss.
        return self::SUCCESS;
    }
}