How disks work in Laravel Cloud

I had a Get Unstuck call with someone recently, and it finally pushed me to set up a project in Laravel Cloud. Part of my goal was to see how disks work in that environment, and how I could set up a local development that would work seamlessly.

I'm used to setting up my own object storage manually (usually an S3 bucket), configuring that as a filesystem in my application and env variables, and then using it in my application.

While you could still do that with Laravel Cloud, the recommended approach in the docs is to use their UI to set up the object storage resource. Part of that process involves naming the bucket and specifying a disk name that you will use in your application via the Storage methods.

But this is where I bumped into my first question: How can I name this disk in the Laravel Cloud UI, and refer to it in my application, but not also set it up in config/filesystems? Aren't I missing a step? How does this work?

Under the hood, Laravel has some special hooks that allow Laravel Cloud to work without any extra configuration in your application. These hooks are in the Illuminate\Foundation\Cloud class, and one of them is a method to configure your disks.

This method looks for a special environment variable called LARAVEL_CLOUD_DISK_CONFIG which Laravel Cloud sets. The value is a JSON-encoded object which represents the exact configuration you'd normally put in config/filesystems.php.

If present, this hook decodes the JSON string and injects it into your filesystem configuration, so you can use it as normal.

But what about local development?

If you create a local disk in your configuration with the exact same name as the Laravel Cloud disk, you can use that locally while developing. And when you deploy into Laravel Cloud, the environment variable it injects will override that disk configuration to use the UI-configured object storage.

Here to help,

Joel

P.S. This was a great use of a paid Get Unstuck call. And even if it's something I haven't bumped into before, we will dig in together and figure it out.