Weave Code
Workos Php Laravel Package
workos/workos-php
Official WorkOS PHP SDK for integrating SSO, Directory Sync, Admin Portal, Magic Links, and more. Configure with your WorkOS API key and client ID to access the WorkOS API from PHP applications via a convenient, maintained client.
Official PHP SDK for interacting with the WorkOS API
Frequently asked questions about Workos Php
- How do I install and configure the WorkOS PHP SDK in a Laravel project?
- Run `composer require workos/workos-php` to install. Configure it using environment variables (`WORKOS_API_KEY` and `WORKOS_CLIENT_ID`) or add them to your Laravel `.env` file. The SDK auto-detects these values, and no additional Laravel service provider setup is required for basic usage.
- Does this SDK support Laravel’s Eloquent for role assignments (e.g., UserRoleAssignmentSource)?
- Yes. The SDK introduces `UserRoleAssignmentSource` and polymorphic typing to align with Laravel’s Eloquent. You can map sources to models using `morphTo()` or store them in pivot tables with extra attributes (e.g., `source_id`, `source_type`). Example: `user->roleAssignments()->wherePivot('source_type', 'App\Models\Source')`.
- Can I dynamically fetch WorkOS CORS origins or redirect URIs in Laravel middleware?
- Absolutely. Use the SDK to fetch allowed origins/URIs at runtime: `$origins = app(WorkOS::class)->userManagement()->corsOrigins()->list();`. Then validate against Laravel’s `Cors` or `TrustProxies` middleware. Cache results in `config('services.workos.cors_origins')` if needed for performance.
- How does the `max_age` parameter for `authorize()` work in Laravel sessions?
- The `max_age` parameter (e.g., `3600` for 1 hour) syncs with Laravel’s session lifetime. Configure it via the SDK: `app(WorkOS::class)->setUserManagementClient(new UserManagementClient($httpClient, ['max_age' => 3600]))`. This ensures WorkOS auth tokens align with Laravel’s session timeout (e.g., `config('session.lifetime')`).
- Will this SDK conflict with existing magic link implementations (e.g., Laravel Breeze)?
- The SDK restores `CreateMagicAuth` logic but may conflict if you’ve customized magic links. Use the v8 Migration Guide to adapt. For Laravel Breeze, extend the `MagicLinkGuard` or override the `createMagicLink` method to integrate WorkOS’s `MagicAuth` flow without breaking existing logic.
- How do I handle WorkOS webhooks for role assignment events in Laravel?
- Listen for events like `user_role_assignment.created` using Laravel’s `Event::listen()`: `Event::listen(UserRoleAssigned::class, fn($event) => Auth::user()->syncRoles($event->role));`. For webhooks, route them to a Laravel controller and dispatch events. The SDK emits events for all role assignment changes.
- Which Laravel versions are supported, and are there breaking changes in v8+?
- The SDK supports Laravel 8.0+ and follows SemVer. Major versions (e.g., v8) may introduce breaking changes like `UserRoleAssignmentSource` or new endpoints (`/cors_origins`). Always check the [changelog](https://github.com/workos/workos-php/blob/main/CHANGELOG.md) and use the v8 Migration Guide for updates.
- How do I test the SDK’s new enums (e.g., `UserRoleAssignmentSourceType`) in PHPUnit?
- Mock enums using PHPUnit’s `createMock()` or fake data: `$sourceType = UserRoleAssignmentSourceType::from('SCIM');`. For HTTP clients, use Laravel’s `Http::fake()` to stub API responses. Example: `Http::fake([ 'workos.com/*' => Http::response(['data' => []]) ])`.
- Are there alternatives to this SDK for Laravel SSO/Directory Sync?
- For SSO, alternatives include Laravel Socialite (OAuth) or Auth0’s PHP SDK. For Directory Sync, consider custom SCIM implementations or Okta’s PHP SDK. However, WorkOS’s SDK is the *official* choice for WorkOS-specific features like Magic Links, Admin Portal, and polymorphic role assignments—offering deeper integration with Laravel’s auth system.
- How should I structure database tables for `UserRoleAssignmentSource`?
- Use a polymorphic relationship: add `source_id` and `source_type` columns to your pivot table (e.g., `user_role_assignments`). For direct tables, create a `user_role_assignment_sources` table with `id`, `source_type`, and `sourceable_id`. Laravel’s `morphTo()` will handle the mapping automatically.
Weaver
How can I help you explore Laravel packages today?