Read the forced URL origin set by useOrigin()

[ipsocode]

Before submitting

• I have read the contribution guide in full and searched existing discussions, issues, and documentation.
• This proposal is specific to Hypervel, rather than a general upstream feature or a request to port existing functionality.
• I will not open a feature pull request unless a maintainer explicitly approves this proposal.

Problem and use case

UrlGenerator::useOrigin() sets the forced origin for the current coroutine, but nothing reads it back. So code that forces its own origin for a while cannot put back the one that was set before it.

A realistic case: an Artisan command that generates API documentation calls useOrigin() so the generated URLs use the documentation's base URL. When it runs in-process, through Artisan::call() from a queued job, a schedule or a request, it runs in the caller's coroutine. On exit it can only call useOrigin(null), which also clears an origin the caller had set, for example a job that set a tenant's URL before calling the command.

Today the only way to save the caller's origin is to read the protected UrlGenerator::FORCED_ROOT_CONTEXT_KEY by reflection and pass it to CoroutineContext::get(). That couples the caller to a private name.

Proposed behavior

A read accessor beside useOrigin(), returning the origin forced for the current coroutine, or null when none is:

$previous = URL::forcedOrigin(); // ?string

URL::useOrigin('https://docs.example.com');

try {
    // generate URLs against the forced origin
} finally {
    URL::useOrigin($previous); // restores the caller's origin, or clears it if there was none
}

It returns exactly what resolveRoot() reads from coroutine context under FORCED_ROOT_CONTEXT_KEY, without consulting the request or the origin resolver, so passing it back to useOrigin() restores the previous state. The name is open: forcedOrigin() keeps it apart from the resolved root.

Why this belongs in Hypervel

The forced origin lives in coroutine context because Hypervel stores it per coroutine ("so one request, job, or command cannot affect concurrent work"), under a key Hypervel defines. Laravel keeps a protected $forcedRoot property on the generator, with no getter. A getter added to Laravel would read that property and would not port onto Hypervel's coroutine-context storage.

Saving and restoring within one coroutine matters more in Hypervel's long-lived workers, where commands run in-process from jobs, schedules and requests that set their own origin.

Existing options and tradeoffs

• Reflection on UrlGenerator::FORCED_ROOT_CONTEXT_KEY, then CoroutineContext::get(). This works today, but it depends on a protected constant and breaks at runtime if the constant is renamed.
• Run the work in a child coroutine, so its useOrigin() does not reach the caller. This moves the command's entire run into another coroutine, which starts without the caller's context unless it is copied. That is much heavier than reading one value.
• Call useOrigin(null) on exit. This loses the caller's origin.

Cost of the proposal: one public method that reads an existing context key, plus its line in the URL facade's docblock. It adds no state and no work on the URL generation path.

[binaryfire]

Addressed in #731. See: https://github.com/hypervel/components/blob/0.4/src/docs/urls.md#customizing-url-origins