- How do I integrate Sign in with Apple into my Laravel app using this package?
- Install via Composer with `composer require patrickbussmann/oauth2-apple`, then configure your Apple Developer credentials (Service ID, AuthKey, Team ID) in the provider setup. Use it with Laravel Socialite or directly with the OAuth2 client. Ensure your redirect URI is whitelisted in the Apple Developer portal.
- Does this package work with Laravel Socialite or only standalone?
- This package is a standalone OAuth2 provider but is fully compatible with Laravel Socialite. You can use it as a drop-in replacement for Socialite’s providers or integrate it directly with the `league/oauth2-client` library. It also works alongside Laravel Passport or Sanctum for hybrid auth flows.
- What Laravel and PHP versions does this package support?
- The package requires PHP 8.3 or 8.5 and is optimized for Laravel 10.x. Laravel 9.x may work but lacks long-term support. Ensure your entire stack (Laravel, dependencies like Passport) aligns with these PHP version requirements before upgrading.
- How does this handle Apple’s private email requirement (is_private_email flag)?
- The package automatically validates Apple’s `is_private_email` claim during authentication. If the user opts for a private email, the flag is preserved in the returned user data. This ensures compliance with Apple’s privacy policies and avoids manual handling of sensitive email attributes.
- What if Apple’s OAuth2 API returns an error? How do I debug it?
- The package now includes `error_description` in exception messages, making debugging easier. Log both the error and `error_description` (e.g., using Monolog) to identify issues like invalid scopes, expired tokens, or rate-limiting (429 errors). Example: `Log::error($e->getErrorDescription())` for quick troubleshooting.
- Can I use this with Laravel Passport for JWT-based authentication?
- Yes, but test thoroughly. The package uses `firebase/php-jwt` (v5.2–7.0) for JWT validation, which may conflict if your app also relies on JWT for Passport. Verify compatibility by running integration tests in staging, especially if you use custom JWT claims or token storage.
- What’s the best way to handle rate-limiting (429 errors) from Apple’s API?
- Implement retries with exponential backoff when encountering 429 errors. Use the `error_description` field to distinguish between rate-limiting and other failures. Libraries like `guzzlehttp/guzzle` support retry logic, or build a custom middleware to handle OAuth2 rate-limiting gracefully.
- Do I need to update my Laravel app if I’m already using an older version of firebase/php-jwt?
- Yes, update `firebase/php-jwt` to ^5.2, ^6.0, or ^7.0 to avoid compatibility issues. Run `composer require firebase/php-jwt:^7.0` and test your existing JWT-based auth flows (e.g., Passport) in staging. No breaking changes are reported, but validation is critical for edge cases like token expiration or signature validation.
- How do I test Sign in with Apple in a sandbox environment before going live?
- Use Apple’s sandbox environment by configuring the provider with sandbox-specific credentials (e.g., AuthKey from the sandbox Developer account). Test edge cases like null emails, private emails, and failed authentications. The package’s improved error messages will help validate sandbox behavior before production deployment.
- What alternatives exist for Sign in with Apple in Laravel, and why choose this package?
- Alternatives include custom implementations using `league/oauth2-client` or third-party packages like `hybridauth/hybridauth`. This package stands out for its Laravel-native integration, Apple-specific compliance (JWT validation, privacy flags), and enhanced error handling. It’s modular, works with Socialite/Passport, and is actively maintained for modern PHP/Laravel stacks.