feature: Add guard assignment helper middleware

[evansims]

Changes

This PR adds a convenience helper middleware that simplifies the assignment of specific guards for handling request routing.

Example usage:

<?php

use Auth0\Laravel\Http\Controller\Stateful\{Login, Logout, Callback};

Route::middleware('guard:someGuardName')->group(function () {
    Route::get('/login', Login::class)->name('login');
    Route::get('/logout', Logout::class)->name('logout');
    Route::get('/callback', Callback::class)->name('callback');
});

This ensures that the example guard, someGuardName, is used to handle the routing of requests for the specified group of routes.

This streamlines our documentation by ensuring that downstream applications are configured to use the Auth0 Laravel SDK guard, regardless of other installed guards or configurations.

References

N/A

Testing

This PR adds tests to cover the new middleware.

Contributor Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 code of conduct

[codecov]

Codecov Report

Patch coverage: 100.00% and no project coverage change.

Comparison is base (844b6c9) 98.97% compared to head (28bc2f8) 98.97%.

Additional details and impacted files

@@            Coverage Diff            @@
##               main     #362   +/-   ##
=========================================
  Coverage     98.97%   98.97%           
  Complexity      289      289           
=========================================
  Files            20       20           
  Lines           783      783           
=========================================
  Hits            775      775           
  Misses            8        8           

Flag	Coverage Δ
unittests	98.97% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/Auth/Guard.php	96.58% <100.00%> (ø)
src/ServiceProvider.php	100.00% <100.00%> (ø)

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[Widcket]

Isn't this assertion done above? On L43.

[Widcket]

Apologies if this is intentional.

[evansims]

Hey @Widcket 👋 No worries! It's repeated a few times to ensure the guard changes are properly persisted between requests. Here's the breakdown of what it's doing:

// Ensure the active guard is the default/unspecified one, 'web' ($defaultGuardClass' value.)
$this->get($routeUnspecifiedGuard)
     ->assertStatus(Response::HTTP_OK)
     ->assertSee($defaultGuardClass);

// Attempt to change the active guard to one that doesn't exist; throws an error.
$this->get($routeNonexistentGuard)
     ->assertStatus(Response::HTTP_INTERNAL_SERVER_ERROR);

// Change the guard to 'testGuard' ($sdkGuardClass' value.)
$this->get($routeMiddlewareAssignedGuard)
     ->assertStatus(Response::HTTP_OK)
     ->assertSee($sdkGuardClass);

// Ensure the active guard was correctly persisted as `testGuard` following the previous request.
$this->get($routeUnspecifiedGuard)
     ->assertStatus(Response::HTTP_OK)
     ->assertSee($sdkGuardClass);

// Clear the active guard we specified, resetting it to the app's default, `web`.
$this->get($routeMiddlewareUnassignedGuard)
     ->assertStatus(Response::HTTP_OK)
     ->assertSee($defaultGuardClass);

// Ensure the active guard was correctly persisted as `web` following the previous request.
$this->get($routeUnspecifiedGuard)
     ->assertStatus(Response::HTTP_OK)
     ->assertSee($defaultGuardClass);

[Widcket]

Thanks for the clarification!