Weave Code
Workos Php Laravel Laravel Package
workos/workos-php-laravel
Laravel integration for WorkOS that provides a configured singleton client, facade, and helper for easy access to the WorkOS API, including user management and SSO. Configure via API key and client ID.
WorkOS PHP Laravel Library provides convenient access to the WorkOS API from Laravel applications. It includes a service provider, publishable configuration, and environment-based credentials via WORKOS_API_KEY and WORKOS_CLIENT_ID.
- Singleton
\WorkOS\WorkOSclient bound in the container - Access via facade,
workos()helper, or dependency injection - Publishable config with
php artisan vendor:publish - Laravel-native configuration and integration
- Supports WorkOS services such as User Management
Frequently asked questions about Workos Php Laravel
- What is workos/workos-php-laravel used for?
- It is the official Laravel integration for WorkOS, giving you a service provider, a WorkOS facade, and a workos() helper that return an instantiated WorkOS PHP client. You use it to call WorkOS APIs for SSO (SAML/OIDC), Directory Sync (SCIM), Admin Portal, Magic Link, MFA, user management, and RBAC. It is a thin client wrapper, not an authentication solution.
- How do I install and configure it in a Laravel app?
- Run composer require workos/workos-php-laravel, then publish the config with php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider". Set the WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables, which the package reads by default. After that the client is bound as a container singleton and is ready to inject or call via the facade.
- Does this package provide an auth guard, user provider, or login scaffolding?
- No. The package contains only a service provider, a publishable config file, and a facade/helper; it ships no guard, no user provider, no session handling, and no Blade views. You still need to implement the mapping between WorkOS users and your Eloquent users, plus callback and webhook handling. Expect the actual project effort to live in that integration layer, not in the SDK.
- Which Laravel and PHP versions are supported?
- Version 5 of the package requires Laravel 10 or higher, and later majors track the upstream workos/workos-php client requirements. The README does not state an explicit Laravel ceiling, so check the composer.json constraints on the specific tagged release you install. Pin a version and verify it against your PHP and illuminate/* targets before adopting.
- How do I access the WorkOS client: facade, helper, or dependency injection?
- All three resolve the same container singleton. Use WorkOS::userManagement()->getUser($id) with the WorkOS\Laravel\Facades\WorkOS facade, workos()->userManagement()->getUser($id) with the helper, or type-hint \WorkOS\WorkOS in a constructor or method signature. Many teams wrap the facade in their own interface so call sites stay stable across major upgrades.
- Why have there been so many major versions, and how hard are upgrades?
- The changelog shows a fast cadence: v5 required Laravel 10+, v6 was a full rewrite that removed WorkOSService and renamed accessors (mfa() to multiFactorAuth(), portal() to adminPortal(), rbac() to authorization(), webhook() split into webhooks() and webhookVerification()), and v7 tracks upstream workos-php v6. Upgrades are mostly mechanical renames but still require planning and testing. Budget for upgrade work rather than treating it as set-and-forget, and read the changelog and V6 migration guide first.
- Should I wrap the facade in my own abstraction?
- Yes, it is cheap insurance. Because the package is a thin shim over the upstream SDK and accessor names have changed across majors, hiding it behind an internal IdentityProvider contract limits the blast radius of upgrades. Your application code then depends on your own DTOs and methods rather than WorkOS-specific method names. Swapping the HTTP layer for facade calls later also becomes straightforward.
- How should I handle timeouts, retries, and errors?
- Nearly all behavior, including error semantics, retries, and timeouts, lives in the underlying workos/workos-php client, not in this Laravel wrapper. Configure those concerns where the upstream client supports them and catch WorkOS exceptions at your boundary, translating them into your own error types. Also decide explicitly whether to fail closed or degrade to local auth when WorkOS is unreachable.
- Does it work with config caching, Laravel Octane, and Vapor?
- The singleton binding is compatible with Octane and Vapor, but configuration is resolved at boot. If you run php artisan config:cache, changes to WORKOS_API_KEY or WORKOS_CLIENT_ID require a redeploy rather than an in-place env edit. Confirm this matches your deploy pipeline, and use distinct keys per environment so staging traffic never reaches the production WorkOS project.
- Is this package production ready, and what are the alternatives?
- It is officially maintained by WorkOS under the MIT license with tagged releases and changelogs, so abandonment risk is low, but adoption signals are thin (around 39 stars and no dependents) and Beta features carry breaking changes between versions. If you need beta features, hard-pin an exact version. Alternatives include calling WorkOS REST endpoints directly with Guzzle or using the framework-agnostic workos/workos-php client, both of which keep behavior in your own HTTP layer.
Weaver
How can I help you explore Laravel packages today?