feat(routes): Auto-register Apple Sign In routes and controller

[mikebronner]

Summary

Moves default routes and controllers into the package for zero-config setup. Routes are auto-registered via the ServiceProvider and can be customized or disabled via config. After setup, users only need to set environment variables.

Changes

• Callback controller refactored: no longer returns raw Socialite user. Instead dispatches AppleSignInCallback event and redirects to a configurable URL (routes.callback_redirect, defaults to /). Apps listen for the event to persist users.
• CSRF exclusion: callback route excludes VerifyCsrfToken middleware since Apple sends a form POST.
• New event: AppleSignInCallback — dispatched with the Socialite user on successful callback.
• Config: added callback_redirect option to services.sign_in_with_apple.routes.
• Tests fixed:
  • Added test for disabling routes (routes.enabled = false)
  • Route customization tests now actually set custom paths and verify they're used
  • Added regression test for controller override via custom route binding
  • Added test verifying CSRF exclusion on callback route

Acceptance Criteria

• Default routes (apple/redirect, apple/callback) are moved into the package and auto-registered
• Default controllers are moved into the package
• Users can override/disable default routes via config
• Existing apps can migrate without breaking changes (or a migration guide is provided)

Test Coverage

• Integration test: routes are registered and accessible without app-side route definitions
• Test: config option to disable package routes works correctly
• Regression test: apps that override controllers still function

Fixes #26

[mikebronner]

Review Checklist

The following items need to be addressed before this is ready:

• Callback controller returns raw Socialite user — AppleSignInController::callback() returns the raw $user object, which serializes to JSON. This isn't practical as a default behavior. Consider redirecting to a configurable route (e.g., config('services.sign_in_with_apple.routes.callback_redirect', '/')) after firing an event, or at minimum document that this controller must be overridden.
• Missing test for disabling routes — AC requires: "config option to disable package routes works correctly." The tests verify routes are registered but never test 'routes.enabled' => false. Add a test that sets services.sign_in_with_apple.routes.enabled to false and verifies the routes are not registered.
• Missing regression test for controller override — AC requires: "apps that override controllers still function." No test covers binding a custom controller to the route names.
• Route customization tests don't actually test customization — testRedirectRoutePathCanBeCustomized and testCallbackRoutePathCanBeCustomized only assert the default config values. They don't set a custom path and verify the route uses it.

AC Verified:

• ✅ Default routes auto-registered via ServiceProvider
• ✅ Default controller in package
• ✅ Config option exists to disable routes
• ✅ Routes use web middleware
• ⚠️ Test coverage gaps noted above

Code quality observations (non-blocking):

• loadRoutesIf() pattern is clean
• Route file is well-structured with configurable paths
• Controller is minimal and focused

[mikebronner]

Review Checklist

• Callback route needs CSRF exclusion. Apple sends a form POST to the callback. The route has web middleware (which includes VerifyCsrfToken), so the callback will 419 unless CSRF is bypassed. The DisableCsrfForAppleCallback middleware exists but isn't applied to this route. Either add it to the route definition or use withoutMiddleware.

• Tests for disabling routes are missing. AC says "config option to disable package routes works correctly" — need a test that sets routes.enabled = false and asserts the routes are not registered.

• Tests for custom route paths don't actually test customization. testRedirectRoutePathCanBeCustomized and testCallbackRoutePathCanBeCustomized only assert the default config values. They need to change the config, re-register routes, and verify the new paths are used.

• Regression test for controller overrides is missing. AC says "apps that override controllers still function" — need a test demonstrating an app can bind its own controller to the routes.

• Default callback() returns a raw Socialite user. For a "zero-config" package, returning a Socialite User object from a web route isn't useful — it'll dump a JSON blob. Consider at least redirecting to a configurable route with the user data flashed to session, or documenting very clearly in the README that apps must override the callback.

[mikebronner]

Review Complete ✅

All acceptance criteria verified against the actual implementation:

• Auto-registered routes — routes/web.php registers apple/redirect (GET) and apple/callback (POST) via loadRoutesFrom in the ServiceProvider
• Package controllers — AppleSignInController handles redirect (Socialite driver) and callback (dispatches AppleSignInCallback event, redirects to configurable URL)
• Config override/disable — routes.enabled, redirect_route, callback_route, and callback_redirect all configurable
• Migration path — Event-based callback (AppleSignInCallback) decouples user persistence; apps override by registering their own routes
• CSRF exclusion — Callback route correctly excludes VerifyCsrfToken middleware (Apple sends a form POST)

Tests: 39 passing (0 failures). Route registration, disable toggle, custom paths, controller override regression, CSRF exclusion — all covered.

CI: GitHub Actions workflow added for PHP 8.2–8.4 × Laravel 12.

No issues found. Ready for merge.