Skip to content

[13.x] Introduce a Cloud facade - #61275

Merged
taylorotwell merged 4 commits into
laravel:13.xfrom
jackbayliss:13.x--cloud-facade
Aug 24, 2026
Merged

taylorotwell merged 4 commits into
laravel:13.xfrom
jackbayliss:13.x--cloud-facade

Conversation

@jackbayliss

@jackbayliss jackbayliss commented Aug 20, 2026 •

Copy link
Copy Markdown
Contributor

This PR introduces a Cloud facade and renames the existing Cloud bootstrapping class to CloudBootstrapper, to avoid any confusion and I also cleaned up some method names / any imports not needed.

I'd like a nice way to see how our app relates to cloud, ie are we in cloud / using managed queues .. pushing to the cloud connection etc.

Right now we have to combine a bunch of logic like laravel_cloud() / driver checks, feature flags etc.

With this PR, we can simply...

  use Illuminate\Support\Facades\Cloud;

  Cloud::hosted();            // running on Laravel Cloud?
  Cloud::usesManagedQueues(); // using Cloud managed queues?
  Cloud::queue();             //  Easy access to the cloud connection ie Cloud::queue()->totalReservedSize()..

There's lot of room for this to expand, such as files, buckets etc, but I don't use those features (yet) and would rather not guess at an API for it.

Feel free to adjust as you see fit method names etc ,i've not added it to the default aliases so it won't clash with any other facades, also not added any contracts or fakes, as I'm not sure we need it as I kinda wouldnt want people to override it

This is probably also worth porting back to 12.x 11.x? (where ever cloud stuff is) if u like it ofc

@github-actions

Copy link
Copy Markdown

Thanks for submitting a PR!

Note that draft PRs are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

@timacdonald

timacdonald commented Aug 20, 2026 •

Copy link
Copy Markdown
Member

I wonder if we should rename Illuminate\Foundation\Cloud to something else to avoid IDE suggestion conflicts, e.g., Illuminate\Foundation\CloudBootstrapper.

@jackbayliss

jackbayliss commented Aug 21, 2026 •

Copy link
Copy Markdown
Contributor Author

@timacdonald seems like a reasonable idea, was kinda afraid to change anything just cos I'm not sure how it's all used internally, i'll give it a spin. Ty for the feedback 🙏

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names
@jackbayliss
jackbayliss marked this pull request as ready for review August 21, 2026 20:45
@jackbayliss
jackbayliss marked this pull request as draft August 23, 2026 17:40
@jackbayliss
jackbayliss marked this pull request as ready for review August 23, 2026 17:47
@taylorotwell
taylorotwell merged commit 5fbd12d into laravel:13.x Aug 24, 2026
54 checks passed
@jackbayliss
jackbayliss deleted the 13.x--cloud-facade branch August 24, 2026 14:07
timacdonald pushed a commit to timacdonald/framework that referenced this pull request Oct 9, 2026
Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)
timacdonald pushed a commit to timacdonald/framework that referenced this pull request Oct 9, 2026
Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)
(cherry picked from commit 4029930)
timacdonald pushed a commit to timacdonald/framework that referenced this pull request Oct 19, 2026
Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)
timacdonald pushed a commit to timacdonald/framework that referenced this pull request Oct 19, 2026
Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)
(cherry picked from commit 4029930)
taylorotwell added a commit that referenced this pull request Oct 21, 2026
* [13.x] Introduce a Cloud facade (#61275)

Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)
(cherry picked from commit 4029930)

* [13.x] Cloud enhancements (#61360)

* Improve testing story

* Return if event writing was successful

* Return whether job was successfully forgotten or not

* Register cloud events earlier

* Make Stan happy

* Update tests

* Improve doc blocks

* Update CloudBootstrapper.php

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>
(cherry picked from commit cb7494d)
(cherry picked from commit 1498177)

* Allow retrieving command by name without resolving all commands (#61361)

(cherry picked from commit ca0e114)
(cherry picked from commit 2a41a03)

* rename to find command

(cherry picked from commit 2795df5)
(cherry picked from commit 027b3db)

* [13.x] Expose methods (#61362)

* Expose methods publicly

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>
(cherry picked from commit 48ac5b8)
(cherry picked from commit 8ab250f)

* [13.x] Cloud exceptions (#61704)

On 11.x, GuardHelpers::id() retrieves the user before reading its identifier, so the user-retrieval count expected by testItCapturesTheUserResolvedByLaravelsExceptionContext is one higher than on 12.x.

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Extract Cloud command UUID for use as exception trace

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Improve test names

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* formatting

* tweak user handling for octaned

* Propagate the request trace ID to jobs dispatched from requests

Jobs are meant to be reported under the trace of the execution that
dispatched them. The trace is carried to the job in hidden Context,
written by the ContextDehydrating listener when the job's payload is
created.

That listener was only registered for console processes, so jobs
dispatched from HTTP requests never carried a trace. Their exceptions
were reported with a null trace_id. Worse, when one of those jobs
dispatched another job, the worker filled the gap with its own
process-wide command trace, grouping every such child job handled by
the worker under a single, unrelated trace.

The listener is now registered for requests as well. When the Context
does not already hold a trace, it falls back to the Cloud-Request-ID
header in requests (the same value the request's own exception reports
use) and to the command trace in the console.

This mirrors what Nightwatch does on Laravel Cloud, where the request
trace is also the Cloud-Request-ID and is propagated to jobs through
hidden Context. Unlike Nightwatch, the trace is written lazily when a
job is dispatched rather than when the execution starts, since only
job payloads need it and the framework has no hook before middleware.
Requests without a Cloud-Request-ID continue to report no trace, and
their jobs now match them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: jradtilbrook <jarryd@tilbrooktech.com>
Co-authored-by: Taylor Otwell <taylor@laravel.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit fee86a4)
(cherry picked from commit 1df0544)

* Add mime type to the files reportable details (#61772)

(cherry picked from commit 1003c6e)
(cherry picked from commit 342e070)

* Update facade docblocks

* Improve exception reporting

* Exception enhancements (#61791)

* Collapses into single listener

* Additional tests

* Capture correct execution time for Octane

* Introduce dehydration hook

* use class directly

(cherry picked from commit f6bcad9)

---------

Co-authored-by: Jack Bayliss <jjbayliss@icloud.com>
Co-authored-by: Taylor Otwell <taylor@laravel.com>
Co-authored-by: jradtilbrook <jarryd@tilbrooktech.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Sabrina Bourouis <bourouis.sabrina@laposte.net>
taylorotwell added a commit that referenced this pull request Oct 24, 2026
* [13.x] Introduce a Cloud facade (#61275)

Backported as the rename only, without the facade and CloudManager.

* cloud facade

Update CloudManager.php

dont need this import after alll

Rename Cloud foundation to bootstrapper

holy pr feedback

facade bits

test

clean method names

* Update CloudBootstrapperTest.php

* cs

(cherry picked from commit 5fbd12d)

* [13.x] Cloud enhancements (#61360)

* Improve testing story

* Return if event writing was successful

* Return whether job was successfully forgotten or not

* Register cloud events earlier

* Make Stan happy

* Update tests

* Improve doc blocks

* Update CloudBootstrapper.php

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>
(cherry picked from commit cb7494d)

* Allow retrieving command by name without resolving all commands (#61361)

(cherry picked from commit ca0e114)

* rename to find command

(cherry picked from commit 2795df5)

* [13.x] Expose methods (#61362)

* Expose methods publicly

* formatting

---------

Co-authored-by: Taylor Otwell <taylor@laravel.com>
(cherry picked from commit 48ac5b8)

* [13.x] Cloud exceptions (#61704)

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Extract Cloud command UUID for use as exception trace

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* Improve test names

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* wip

* formatting

* tweak user handling for octaned

* Propagate the request trace ID to jobs dispatched from requests

Jobs are meant to be reported under the trace of the execution that
dispatched them. The trace is carried to the job in hidden Context,
written by the ContextDehydrating listener when the job's payload is
created.

That listener was only registered for console processes, so jobs
dispatched from HTTP requests never carried a trace. Their exceptions
were reported with a null trace_id. Worse, when one of those jobs
dispatched another job, the worker filled the gap with its own
process-wide command trace, grouping every such child job handled by
the worker under a single, unrelated trace.

The listener is now registered for requests as well. When the Context
does not already hold a trace, it falls back to the Cloud-Request-ID
header in requests (the same value the request's own exception reports
use) and to the command trace in the console.

This mirrors what Nightwatch does on Laravel Cloud, where the request
trace is also the Cloud-Request-ID and is propagated to jobs through
hidden Context. Unlike Nightwatch, the trace is written lazily when a
job is dispatched rather than when the execution starts, since only
job payloads need it and the framework has no hook before middleware.
Requests without a Cloud-Request-ID continue to report no trace, and
their jobs now match them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: jradtilbrook <jarryd@tilbrooktech.com>
Co-authored-by: Taylor Otwell <taylor@laravel.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit fee86a4)

* Add mime type to the files reportable details (#61772)

(cherry picked from commit 1003c6e)

* Update facade docblocks

* Improve exception reporting

* Exception enhancements (#61791)

* Collapses into single listener

* Additional tests

* Capture correct execution time for Octane

* Introduce dehydration hook

* use class directly

(cherry picked from commit f6bcad9)

* Resolve the Blade mapper for each reported view exception.

(cherry picked from commit 5ccdd3b)

* Match the registration spacing of 13.x.

* Add missing @throws \JsonException annotations (#60514)

(cherry picked from commit a6ce2a7)

* Foundation\Cloud\Events: remove an unused import and fix docblock (#60378)

(cherry picked from commit 7433202)

* Resolve the Blade mapper through a resolver closure.

(cherry picked from commit 058631e)

---------

Co-authored-by: Jack Bayliss <jjbayliss@icloud.com>
Co-authored-by: Taylor Otwell <taylor@laravel.com>
Co-authored-by: jradtilbrook <jarryd@tilbrooktech.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Sabrina Bourouis <bourouis.sabrina@laposte.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants