Weave Code
Workos Php Laravel Package
workos/workos-php
The official WorkOS PHP library gives PHP applications convenient access to the WorkOS API. Install via Composer, configure WORKOS_API_KEY and WORKOS_CLIENT_ID, and integrate SSO, Directory Sync, Admin Portal, Magic Link, and more.
WorkOS PHP Library is the official PHP SDK for the WorkOS API, giving PHP applications convenient access to enterprise-ready authentication and directory features. Install it via Composer (composer require workos/workos-php) and configure it with your API Key and Client ID — read automatically from the WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables.
- Single Sign-On (SAML/OIDC) for enterprise authentication
- Directory Sync with SCIM-based user provisioning
- Admin Portal and Magic Link flows
- SemVer versioning with stable and Beta releases
Frequently asked questions about Workos Php
- How do I install workos/workos-php in a Laravel application?
- Install the official SDK with composer require workos/workos-php. Then set the WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables that the package reads by default. Laravel can resolve the WorkOS client through its container bindings, so you can inject it into services, controllers, or jobs.
- How should I configure WorkOS API keys and Client ID in Laravel?
- Set WORKOS_API_KEY and WORKOS_CLIENT_ID in your .env file and reference them from config/services.php if you prefer config caching. For session authentication in v9, also add WORKOS_ISSUER and pass it as the issuer option. Keep issuer validation enabled outside local/testing so tokens are not silently accepted from the wrong environment.
- Does workos/workos-php support Laravel 10, 11, or 12?
- The package is a framework-agnostic PHP SDK installed through Composer, so Laravel compatibility depends on the PHP version and dependency constraints in its composer.json rather than a Laravel-specific support matrix. The v9 notes mention container bindings and Eloquent-friendly response objects, but you should verify the package requirements before upgrading. Check composer.json and the v9 changelog for the exact PHP and dependency versions.
- How do I upgrade workos/workos-php from v8 to v9?
- Move the Composer constraint from ^8 to ^9.4 and read the v9 changelog before deploying. Because v9 includes a regenerated spec, re-verify every integration point instead of assuming v8 behavior carries over. Audit session authentication, error mapping, Pipes parameters, and any stored WorkOS response fields; the older v8 migration guide is historical, not the upgrade path.
- How do I wire WorkOS session authentication and issuer validation in Laravel?
- Call userManagement()->authenticate($token, ['issuer' => config('services.workos.issuer')]) and keep WORKOS_ISSUER required in non-local environments. In v9, JWT expiration is mandatory, so Laravel's session.lifetime is not the source of truth for token validity. Put issuer validation alongside your config('services.workos.client_id') comparison so both checks live in the same authentication path.
- How should I handle AccountSelectionRequiredError in Laravel?
- Treat AccountSelectionRequiredError as a domain exception for Pipes connections that require the user to choose an account. Map it to a named exception and render it in bootstrap/app.php or with Handler::renderable() so it returns a redirect or account-selection response instead of a raw 500. This keeps the error actionable for the end user and consistent with the rest of your Laravel error handling.
- What changed for WorkOS Pipes data integration ownership in v9?
- v9 adds PipesOwnership, CreateDataIntegrationOwnership, and DataIntegrationOwnership enums, makes user a valid ownership target, and adds GET, PUT, and DELETE endpoints under /data-integrations/{slug}/organization. These changes fit Laravel multi-tenant patterns where integrations can be organization-owned or user-owned. Review your tenancy scopes and authorization rules if you expose these ownership choices to users.
- How should I store WorkOS response fields like MagicAuth.code or password_reset_url after v9?
- Treat these values as opaque strings: do not regex-validate them, assume a fixed length, or parse internal structure. v9 changed formats across MagicAuth.code, VerifyEmailAddress.code, password_reset_url, invitation URLs, TOTP fields, API key values, portal links, logout URLs, and device authorization responses. Size database columns generously and audit any code that cached, persisted, or double-encoded these values.
- How do I test a WorkOS integration in a Laravel application?
- Set WORKOS_API_KEY, WORKOS_CLIENT_ID, and WORKOS_ISSUER in phpunit.xml or your test environment, and avoid calling the live WorkOS API from CI. The SDK does not document Laravel-specific fakes, so bind a fake or mock WorkOS client in the container, or use Laravel HTTP fakes around your own wrapper. Test the AccountSelectionRequiredError rendering and issuer validation paths explicitly because those are important v9 behaviors.
- Is workos/workos-php production-ready and actively maintained?
- It is the official WorkOS PHP library and follows SemVer, with breaking changes reserved for major versions, so stable releases are suitable for production with normal dependency pinning. Beta features may change between Beta releases, so pin the exact Beta version if you depend on one. Keep an eye on the changelog and move to stable releases when your Beta feature reaches general availability.
Weaver
How can I help you explore Laravel packages today?