WorkOS PHP Laravel

https://github.com/workos/workos-php-laravel
Admin
The WorkOS PHP Laravel library provides convenient access to the WorkOS API from applications...
Tokens:17,792
Snippets:281
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Beta Release

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

Command to install a specific beta version of the SDK.

```bash
composer require workos/workos-php-laravel:^9.0.0-beta.1
```

--------------------------------

### Handle Missing Configuration Exception

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Example of the RuntimeException thrown when required configuration is missing during bootstrap.

```text
RuntimeException: WorkOS is not configured: `workos.api_key` is missing. 
Set the corresponding environment variable (e.g. WORKOS_API_KEY, WORKOS_CLIENT_ID) 
or publish and edit config/workos.php.
```

--------------------------------

### Install and Configure WorkOS Laravel

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Commands to install the package, publish configuration files, and set required environment variables.

```bash
# Install package
composer require workos/workos-php-laravel

# Publish configuration
php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"

# Set environment variables
echo "WORKOS_API_KEY=pk_test_..." >> .env
echo "WORKOS_CLIENT_ID=org_..." >> .env
```

--------------------------------

### API Request with Versioning

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

Example of an API request and the corresponding HTTP headers.

```php
WorkOS::userManagement()->getUser('user_123');
```

```http
GET /api/v1/users/user_123 HTTP/1.1
Host: api.workos.com
User-Agent: WorkOS PHP Laravel/8.0.1
Authorization: Bearer pk_test_...
```

--------------------------------

### Using workos() in Controllers

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Example of using the helper within a Laravel controller to fetch or create users.

```php
namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    public function show($id)
    {
        $user = workos()->userManagement()->getUser($id);
        return view('user.show', ['user' => $user]);
    }

    public function store(Request $request)
    {
        $newUser = workos()->userManagement()->createUser(
            $request->validated()
        );
        return redirect()->route('users.show', $newUser->id);
    }
}
```

--------------------------------

### Handle Configuration Errors

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/INDEX.md

Example of the exception thrown when WorkOS is not properly configured.

```php
// Thrown if api_key or client_id is not configured
throw new RuntimeException("WorkOS is not configured: `workos.api_key` is missing...");
```

--------------------------------

### User-Agent Header Example

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

The resulting User-Agent header string.

```text
User-Agent: WorkOS PHP Laravel/8.0.1
```

--------------------------------

### Using workos() in Services or Model Observers

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Example of using the helper within a service class.

```php
namespace App\Services;

class UserSyncService
{
    public function sync()
    {
        $users = workos()->userManagement()->listUsers();
        
        foreach ($users as $workosUser) {
            // Sync to local database
        }
    }
}
```

--------------------------------

### Using workos() in Middleware

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Example of using the helper within middleware to ensure a user exists in WorkOS.

```php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class EnsureUserHasWorkOS
{
    public function handle(Request $request, Closure $next)
    {
        if (! auth()->user()->workos_id) {
            $workosUser = workos()->userManagement()->createUser([
                'email' => auth()->user()->email,
            ]);
            
            auth()->user()->update(['workos_id' => $workosUser->id]);
        }
        
        return $next($request);
    }
}
```

--------------------------------

### Verify installation with Tinker

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

Use the Laravel tinker shell to verify the WorkOS service is available.

```bash
php artisan tinker

# In tinker shell:
>>> workos()
WorkOS\WorkOS { ... }

>>> WorkOS::userManagement()
WorkOS\Service\UserManagement { ... }
```

--------------------------------

### Using workos() in Events or Listeners

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Example of using the helper within an event listener to sync user data.

```php
namespace App\Listeners;

use App\Events\UserCreated;

class SyncUserWithWorkOS
{
    public function handle(UserCreated $event)
    {
        $workosUser = workos()->userManagement()->createUser([
            'email' => $event->user->email,
            'first_name' => $event->user->first_name,
            'last_name' => $event->user->last_name,
        ]);
        
        $event->user->update(['workos_id' => $workosUser->id]);
    }
}
```

--------------------------------

### View Project Directory Structure

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

Visual representation of the file layout after installing the WorkOS Laravel package.

```text
your-laravel-app/
├── config/
│   └── workos.php              ← Published configuration
├── .env                        ← Environment variables
├── .env.local                  ← Local overrides (gitignored)
├── composer.json               ← Updated with workos-php-laravel
├── composer.lock               ← Updated dependencies
└── vendor/
    └── workos/
        ├── workos-php/         ← Core SDK (dependency)
        └── workos-php-laravel/ ← This package
```

--------------------------------

### Install WorkOS Laravel Package

Source: https://github.com/workos/workos-php-laravel/blob/main/README.md

Use Composer to add the WorkOS Laravel library to your project dependencies.

```bash
composer require workos/workos-php-laravel
```

--------------------------------

### WorkOS Facade Usage

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

The WorkOS facade acts as a gateway to various WorkOS services. Below are examples of how to invoke these services directly from the facade.

```APIDOC
## WorkOS Facade Methods

### SSO
`WorkOS::sso()->getAuthorizeUrl(array $params)`

### User Management
`WorkOS::userManagement()->getUser(string $id)`
`WorkOS::userManagement()->listUsers()`
`WorkOS::userManagement()->createUser(array $params)`

### Organizations
`WorkOS::organizations()->listOrganizations()`
`WorkOS::organizations()->getOrganization(string $id)`
`WorkOS::organizations()->createOrganization(array $params)`

### Directory Sync
`WorkOS::directorySync()->getDirectory(string $id)`
`WorkOS::directorySync()->listDirectories()`

### Webhooks
`WorkOS::webhookVerification()->verifyEvent(array $params)`

### Admin Portal
`WorkOS::adminPortal()->generatePortalLink(array $params)`
```

--------------------------------

### Override Configuration in Tests

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Programmatically override WorkOS configuration values within a test class setup method.

```php
// In your test class
protected function setUp(): void
{
    parent::setUp();
    
    // Override WorkOS configuration for testing
    config([
        'workos.api_key' => 'pk_test_mock_key',
        'workos.client_id' => 'org_test_mock_id',
    ]);
}
```

--------------------------------

### Accessing WorkOS Services via Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Demonstrates the static facade syntax compared to helper functions and dependency injection.

```php
// Using the facade (static syntax)
WorkOS::userManagement()->getUser('user_123');

// Equivalent to (non-static):
workos()->userManagement()->getUser('user_123');

// Which is equivalent to (dependency injection):
public function show(\WorkOS\WorkOS $workos) {
    $workos->userManagement()->getUser('user_123');
}
```

--------------------------------

### Importing the WorkOS Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Shows how to import the facade or use the fully qualified class name.

```php
use WorkOS\Laravel\Facades\WorkOS;
```

```php
\WorkOS\Laravel\Facades\WorkOS::userManagement()->getUser('user_123');
```

--------------------------------

### Access WorkOS via Helper

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Recommended for quick scripts.

```php
$user = workos()->userManagement()->getUser('user_123');
```

--------------------------------

### Initialize WorkOS Client with User-Agent

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

Usage of version constants within the WorkOSServiceProvider to configure the client.

```php
// In WorkOSServiceProvider::register()
$args = [
    'userAgent' => sprintf('%s/%s', Version::SDK_IDENTIFIER, Version::SDK_VERSION),
    // ... other configuration
];

return new WorkOS(...$args);
```

--------------------------------

### Publish Configuration File

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Commands to publish the default configuration file to the application directory.

```bash
php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"
```

```bash
php artisan vendor:publish --tag=workos-config
```

--------------------------------

### Initialize Pipes Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Access the data pipeline service.

```php
$pipes = workos()->pipes();
```

--------------------------------

### Create a User

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Create a new user with the provided email and password.

```php
$user = workos()->userManagement()->createUser([
    'email' => 'user@example.com',
    'password' => 'secure_password',
]);
```

--------------------------------

### Configure environment variables

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Set the required API key and client ID in your .env file.

```bash
# .env
WORKOS_API_KEY=pk_test_...
WORKOS_CLIENT_ID=org_...
```

--------------------------------

### Testing Services with Dependency Injection

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Demonstrates how to mock the WorkOS client when using dependency injection for unit testing.

```php
use Mockery\Mock;
use Tests\TestCase;

class UserSyncServiceTest extends TestCase
{
    public function test_sync_creates_local_users()
    {
        $mockWorkOS = \Mockery::mock(\WorkOS\WorkOS::class);
        $mockWorkOS->shouldReceive('userManagement')
            ->andReturn(\Mockery::mock()
                ->shouldReceive('listUsers')
                ->andReturn([/* test data */])
                ->getMock()
            );

        $service = new UserSyncService($mockWorkOS);
        $service->sync();

        // Assert local users were created
    }
}
```

--------------------------------

### Method Chaining with workos()

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Demonstrates chaining service calls directly from the helper.

```php
// Services can be chained directly from workos()
$org = workos()->organizations()->getOrganization('org_123');

$members = workos()->directorySync()->listDirectoryUsers('dir_123');

$event = workos()->webhookVerification()->verifyEvent([
    'payload' => $request->getContent(),
    'sigHeader' => $request->header('WorkOS-Signature'),
]);
```

--------------------------------

### Project Directory Structure

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/INDEX.md

Overview of the package file structure.

```text
workos-php-laravel/
├── lib/
│   ├── WorkOSServiceProvider.php    # Laravel service provider
│   ├── Facades/
│   │   └── WorkOS.php              # Facade class
│   ├── helpers.php                 # Global helper function
│   └── Version.php                 # SDK version constant
├── config/
│   └── workos.php                  # Default configuration
└── tests/                          # Test suite
```

--------------------------------

### Initialize Radar Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Access the threat detection service.

```php
$radar = workos()->radar();
```

--------------------------------

### Initialize Passwordless Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Access the passwordless authentication service.

```php
$passwordless = workos()->passwordless();
```

--------------------------------

### Configure WorkOS via config file

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Alternative configuration method using the config/workos.php file.

```php
return [
    'api_key' => 'pk_test_...',
    'client_id' => 'org_...',
    'api_base_url' => null,
];
```

--------------------------------

### Use PKCE Helper

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Generate PKCE code verifiers and challenges for OAuth flows.

```php
$pkce = workos()->pkce();

$codeVerifier = $pkce->getCodeVerifier();
$codeChallenge = $pkce->getCodeChallenge($codeVerifier);
```

--------------------------------

### Initialize Vault Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Access the secure data storage service.

```php
$vault = workos()->vault();
```

--------------------------------

### Helper Function Usage

Source: https://github.com/workos/workos-php-laravel/blob/main/docs/V6_MIGRATION_GUIDE.md

The workos() helper remains available but now returns the WorkOS client instance.

```php
$user = workos()->userManagement()->getUser($id);
```

--------------------------------

### Access WorkOS via Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Recommended for simple calls within the application.

```php
use WorkOS\Laravel\Facades\WorkOS;

$user = WorkOS::userManagement()->getUser('user_123');
```

--------------------------------

### Configuration file path

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

The location of the published configuration file.

```text
config/workos.php
```

--------------------------------

### Method Chaining with Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Services returned by the facade support fluent method chaining.

```php
$users = WorkOS::userManagement()
    ->listUsers()
    ->map(fn($user) => $user->email)
    ->filter(fn($email) => str_ends_with($email, '@acme.com'));
```

--------------------------------

### Initialize Widgets Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Access the embedded widget service.

```php
$widgets = workos()->widgets();
```

--------------------------------

### Access Version Information in Application

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

How to retrieve and combine version constants in application code.

```php
use WorkOS\Laravel\Version;

echo Version::SDK_IDENTIFIER;  // "WorkOS PHP Laravel"
echo Version::SDK_VERSION;     // "8.0.1"

// Combined
$fullVersion = Version::SDK_IDENTIFIER . '/' . Version::SDK_VERSION;
// "WorkOS PHP Laravel/8.0.1"
```

--------------------------------

### Verify Service Instance Caching

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Demonstrates that multiple calls to the same service return the identical instance.

```php
$um1 = workos()->userManagement();
$um2 = workos()->userManagement();

// These are the same instance
assert($um1 === $um2);
```

--------------------------------

### Manage Webhooks

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve, list, and create webhooks.

```php
$webhook = workos()->webhooks()->getWebhook('wh_123');

$webhooks = workos()->webhooks()->listWebhooks();

$newWebhook = workos()->webhooks()->createWebhook([
    'url' => 'https://myapp.com/webhooks/workos',
]);
```

--------------------------------

### Manage Directory Sync

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Retrieve directory information or list existing directories.

```php
// Get a directory
$directory = WorkOS::directorySync()->getDirectory('dir_123');

// List directories
$directories = WorkOS::directorySync()->listDirectories();
```

--------------------------------

### PKCE Helper

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Provides PKCE (Proof Key for Code Exchange) utilities for OAuth flows.

```APIDOC
## PKCEHelper

### Description
Provides PKCE utilities for OAuth flows.

### Methods
- `getCodeVerifier()`: Generate a PKCE code verifier.
- `getCodeChallenge($verifier)`: Generate a code challenge from a verifier.
```

--------------------------------

### Configure WorkOS Settings

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

Default configuration structure for the WorkOS package.

```php
return [
    'api_key' => env('WORKOS_API_KEY'),
    'client_id' => env('WORKOS_CLIENT_ID'),
    'api_base_url' => null,
];
```

--------------------------------

### Clear Application Caches

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

Run these commands to clear configuration, cache, and view files when environment variables fail to load.

```bash
php artisan config:clear
php artisan cache:clear
php artisan view:clear
```

--------------------------------

### Manage Organizations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

List, retrieve, or create organizations.

```php
// List organizations
$orgs = WorkOS::organizations()->listOrganizations();

// Get a specific organization
$org = WorkOS::organizations()->getOrganization('org_123');

// Create an organization
$newOrg = WorkOS::organizations()->createOrganization([
    'name' => 'Acme Corp',
    'domain_data' => [
        'domain' => 'acme.com',
    ],
]);
```

--------------------------------

### Access WorkOS via Helper Function

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

Use the global workos() helper function for a concise way to access services.

```php
$users = workos()->userManagement()->listUsers();
```

--------------------------------

### Configure WorkOS Environment

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/INDEX.md

Set the required API credentials in the environment or configuration file.

```bash
WORKOS_API_KEY=pk_test_...
WORKOS_CLIENT_ID=org_...
```

```php
return [
    'api_key' => 'pk_test_...',
    'client_id' => 'org_...',
    'api_base_url' => null,
];
```

--------------------------------

### Basic Usage of workos()

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Accessing a WorkOS service directly using the helper.

```php
// Access a service
$user = workos()->userManagement()->getUser('user_123');
```

--------------------------------

### Define Testing Environment Variables

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Use a .env.testing file to define mock credentials for automated tests.

```bash
# .env.testing
WORKOS_API_KEY=pk_test_mock_key
WORKOS_CLIENT_ID=org_test_mock_id
```

--------------------------------

### Default Configuration File Structure

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

The default content of the published config/workos.php file.

```php
<?php

return [
    // WorkOS API Key
    "api_key" => env("WORKOS_API_KEY"),

    // WorkOS Client ID
    "client_id" => env("WORKOS_CLIENT_ID"),

    // WorkOS base API URL
    "api_base_url" => null
];
```

--------------------------------

### Retrieve SDK Version Information

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

Access SDK constants for identification and version tracking.

```php
use WorkOS\Laravel\Version;

echo Version::SDK_IDENTIFIER;  // "WorkOS PHP Laravel"
echo Version::SDK_VERSION;     // "8.0.1"
```

--------------------------------

### Configure Environment Variables for WorkOS

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Environment variable configurations for development, production, and staging environments.

```bash
# .env.local or .env.development

WORKOS_API_KEY=pk_test_g7u819wVDZK...
WORKOS_CLIENT_ID=org_dev_01ARZ3NDEKTSV4RRFFQ69G5FAV
WORKOS_API_BASE_URL=null
```

```bash
# .env.production

WORKOS_API_KEY=pk_live_production_key_here...
WORKOS_CLIENT_ID=org_prod_01ARZ3NDEKTSV4RRFFQ69G5FAV
WORKOS_API_BASE_URL=null  # or omit this line
```

```bash
# .env.staging

WORKOS_API_KEY=pk_test_staging_key_here...
WORKOS_CLIENT_ID=org_staging_01ARZ3NDEKTSV4RRFFQ69G5FAV
WORKOS_API_BASE_URL=https://api-staging.workos.com/
```

--------------------------------

### Publish WorkOS Configuration

Source: https://github.com/workos/workos-php-laravel/blob/main/README.md

Run the artisan command to generate the configuration file for the WorkOS service provider.

```bash
php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"
```

--------------------------------

### Environment Variable Security Practices

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Comparison of secure and insecure methods for handling API keys in environment files.

```bash
# Bad: API key in .env (committed to Git)
WORKOS_API_KEY=pk_test_g7u819wVDZK...

# Good: API key in .env.local (in .gitignore)
WORKOS_API_KEY=pk_test_g7u819wVDZK...

# Best: API key via hosting provider environment variables
# Set through: Heroku Config Vars, AWS Lambda Env, etc.
```

--------------------------------

### Accessing the WorkOS Singleton Instance

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

Demonstrates the various methods to retrieve the shared WorkOS singleton instance within a Laravel application.

```php
// All of these return the same singleton instance
app('workos');
app(\WorkOS\WorkOS::class);
workos();
app()->make(\WorkOS\WorkOS::class);
```

--------------------------------

### Manage Directory Sync

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve directory information, users, and groups.

```php
$directory = workos()->directorySync()->getDirectory('dir_123');

$users = workos()->directorySync()->listDirectoryUsers('dir_123');

$groups = workos()->directorySync()->listDirectoryGroups('dir_123');
```

--------------------------------

### workos()

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

The workos() helper function returns the singleton WorkOS client instance from the Laravel service container.

```APIDOC
## workos()

### Description
Returns the configured WorkOS client instance from the Laravel service container. This function is available globally and provides a singleton instance for consistent access across the application.

### Signature
`function workos(): \WorkOS\WorkOS`

### Parameters
None.

### Return Type
`\WorkOS\WorkOS` — The singleton WorkOS client instance.

### Usage Example
```php
// Access a service directly
$user = workos()->userManagement()->getUser('user_123');

// Method chaining
$org = workos()->organizations()->getOrganization('org_123');
```
```

--------------------------------

### Accessing WorkOS via Dependency Injection

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Inject the WorkOS client directly into class constructors using typehinting.

```php
\WorkOS\WorkOS
```

--------------------------------

### Implement Single Sign-On

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Generate authorization URLs and exchange codes for user profiles using the SSO service.

```php
$url = workos()->sso()->getAuthorizeUrl(['domain' => 'acme.com']);
$profile = workos()->sso()->getProfileAndToken(code: $code, domain: $domain);
```

--------------------------------

### Access WorkOS via Dependency Injection

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Inject the WorkOS client directly into classes to follow dependency inversion principles and maximize testability.

```php
public function __construct(private \WorkOS\WorkOS $workos) {}

public function show($id) {
    $user = $this->workos->userManagement()->getUser($id);
}
```

--------------------------------

### Sync Directory Users

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Implements a console command to fetch and synchronize users from a WorkOS Directory into a local database.

```php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Models\User;
use WorkOS\WorkOS;

class SyncDirectoryUsers extends Command
{
    protected $signature = 'workos:sync-directory {directory_id}';
    protected $description = 'Sync users from a WorkOS Directory';

    public function __construct(private WorkOS $workos) {}

    public function handle()
    {
        $directoryId = $this->argument('directory_id');
        
        $users = $this->workos->directorySync()
            ->listDirectoryUsers(directory: $directoryId);

        foreach ($users as $workosUser) {
            User::updateOrCreate(
                ['workos_id' => $workosUser->id],
                [
                    'email' => $workosUser->emails[0]['value'] ?? null,
                    'first_name' => $workosUser->firstName,
                    'last_name' => $workosUser->lastName,
                    'directory_id' => $directoryId,
                ]
            );
        }

        $this->info("Synced " . count($users) . " users");
    }
}
```

--------------------------------

### View documentation structure

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Visual representation of the project's documentation file organization.

```text
Documentation Structure:
├── 00_START_HERE.md (you are here)
├── REFERENCE_GUIDE.md (comprehensive index)
├── INDEX.md (overview)
├── installation-and-setup.md
├── configuration.md
├── module-reference.md
├── integration-patterns.md
└── api-reference/
    ├── service-provider.md
    ├── facades.md
    ├── helper-functions.md
    ├── supported-services.md
    └── version-info.md
```

--------------------------------

### Publishing WorkOS Configuration

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

Commands to publish the default configuration file to the application's config directory.

```bash
# Publish configuration file
php artisan vendor:publish --provider="WorkOS\Laravel\WorkOSServiceProvider"

# Or use specific tag
php artisan vendor:publish --tag=workos-config
```

--------------------------------

### Manage Organizations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Provides service methods for creating organizations, inviting users, and listing organization memberships.

```php
namespace App\Services;

use WorkOS\WorkOS;

class OrganizationService
{
    public function __construct(private WorkOS $workos) {}

    public function createOrganizationWithDomain($name, $domain)
    {
        $org = $this->workos->organizations()->createOrganization([
            'name' => $name,
            'domain_data' => [
                'domain' => $domain,
            ],
        ]);

        return $org;
    }

    public function inviteUser($organizationId, $email)
    {
        $invitation = $this->workos->organizations()->createInvitation([
            'organization_id' => $organizationId,
            'email' => $email,
        ]);

        return $invitation;
    }

    public function listOrganizationMembers($organizationId)
    {
        $members = $this->workos->organizations()
            ->listOrganizationMemberships(organization_id: $organizationId);

        return $members;
    }
}
```

--------------------------------

### Directory Sync Methods

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Method for listing users within a directory.

```APIDOC
## workos()->directorySync()->listDirectoryUsers(string $directoryId)

### Description
Lists all users associated with a specific directory.

### Parameters
- **directoryId** (string) - Required - The unique identifier of the directory.
```

--------------------------------

### View Test Directory Structure

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

Organization of test files within the package repository.

```text
tests/
├── LaravelTestCase.php               # Base test case
├── WorkOS/
│   ├── WorkOSFacadeTest.php         # Facade tests
│   └── WorkOSServiceProviderTest.php # Provider tests
└── bootstrap.php                     # Test bootstrap
```

--------------------------------

### Function Signature for workos()

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

The signature for the global helper function.

```php
function workos(): \WorkOS\WorkOS
```

--------------------------------

### Configure Autoloading

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

PSR-4 mapping and global file inclusion for the WorkOS Laravel package.

```json
{
  "autoload": {
    "psr-4": {
      "WorkOS\\Laravel\\": "lib/"
    },
    "files": [
      "lib/helpers.php"
    ]
  }
}
```

--------------------------------

### WorkOS Configuration File

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

The published configuration file that maps environment variables to the WorkOS client settings.

```php
// config/workos.php
return [
    'api_key' => env('WORKOS_API_KEY'),
    'client_id' => env('WORKOS_CLIENT_ID'),
    'api_base_url' => null,
];
```

--------------------------------

### Configure API Base URL

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Setting a custom API base URL or reverting to the default.

```php
'api_base_url' => 'https://api-staging.workos.com/'
```

```php
'api_base_url' => null  // Uses https://api.workos.com/
```

```bash
WORKOS_API_BASE_URL=https://api-staging.workos.com/
```

--------------------------------

### Access SDK Constants

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

Individual constants for the SDK identifier and version.

```php
public const SDK_IDENTIFIER = "WorkOS PHP Laravel"
```

```php
public const SDK_VERSION = '8.0.1'
```

--------------------------------

### Access WorkOS Services

Source: https://github.com/workos/workos-php-laravel/blob/main/README.md

Retrieve the WorkOS client via the facade, helper function, or dependency injection.

```php
use WorkOS\Laravel\Facades\WorkOS;

$user = WorkOS::userManagement()->getUser($id);
// or
$user = workos()->userManagement()->getUser($id);
// or
public function __construct(private \WorkOS\WorkOS $workos) {}
```

--------------------------------

### Access WorkOS Configuration via Config Helper

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Use the Laravel config helper to retrieve the full configuration array or specific keys.

```php
// Get entire WorkOS configuration
$config = config('workos');

// Get specific configuration value
$apiKey = config('workos.api_key');
$clientId = config('workos.client_id');
$baseUrl = config('workos.api_base_url');
```

--------------------------------

### Update Dependency Injection

Source: https://github.com/workos/workos-php-laravel/blob/main/docs/V6_MIGRATION_GUIDE.md

Replace the WorkOSService type hint with the WorkOS class directly in constructors.

```php
use WorkOS\Laravel\Services\WorkOSService;

class UserController
{
    public function __construct(private WorkOSService $workos) {}
}
```

```php
use WorkOS\WorkOS;

class UserController
{
    public function __construct(private WorkOS $workos) {}
}
```

--------------------------------

### Configure API Key

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Setting the required WorkOS API key via config or environment variable.

```php
'api_key' => 'pk_test_g7u819wVDZK...'
```

```bash
WORKOS_API_KEY=pk_test_g7u819wVDZK...
```

--------------------------------

### User Management Methods

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Methods for retrieving and creating users via the User Management service.

```APIDOC
## workos()->userManagement()->getUser(string $id)

### Description
Retrieves a specific user by their unique identifier.

### Parameters
- **id** (string) - Required - The unique identifier of the user.

## workos()->userManagement()->createUser(array $attributes)

### Description
Creates a new user in the WorkOS system.

### Parameters
- **attributes** (array) - Required - An array containing user details such as 'email' and 'password'.
```

--------------------------------

### SSO Methods

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Method for generating an SSO authorization URL.

```APIDOC
## workos()->sso()->getAuthorizeUrl(array $options)

### Description
Generates the authorization URL for SSO login.

### Parameters
- **options** (array) - Required - Configuration options including 'domain', 'redirectUri', and 'state'.
```

--------------------------------

### List Feature Flags

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve a list of feature flags.

```php
$flags = workos()->featureFlags()->listFeatureFlags();
```

--------------------------------

### Access WorkOS services via Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/docs/V6_MIGRATION_GUIDE.md

The WorkOS facade remains the primary way to access services, though internal service namespaces have been updated.

```php
use WorkOS\Laravel\Facades\WorkOS;

$user = WorkOS::userManagement()->getUser($id);
```

--------------------------------

### Accessing WorkOS via Static Facade

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Use the WorkOS facade for static access to SDK services within Laravel applications.

```php
WorkOS::userManagement()->getUser($id)
```

--------------------------------

### Define Version Class

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

The Version class contains the SDK_IDENTIFIER and SDK_VERSION constants.

```php
final class Version
{
    public const SDK_IDENTIFIER = "WorkOS PHP Laravel";
    public const SDK_VERSION = '8.0.1';
}
```

--------------------------------

### Access WorkOS Services

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/INDEX.md

Demonstrates different ways to access WorkOS services within a Laravel application.

```php
use WorkOS\Laravel\Facades\WorkOS;

$users = WorkOS::userManagement()->listUsers();
$orgs = WorkOS::organizations()->listOrganizations();
```

```php
$user = workos()->userManagement()->getUser($id);
```

```php
public function store(\WorkOS\WorkOS $workos) {
    $user = $workos->userManagement()->getUser($id);
}
```

--------------------------------

### Register WorkOS Helper Function

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/helper-functions.md

Add the helper file to the autoload files section in composer.json to ensure global availability.

```json
"autoload": {
  "files": [
    "lib/helpers.php"
  ]
}
```

--------------------------------

### Manage Users with WorkOS

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Retrieve individual user details or list all users using the user management service.

```php
$user = workos()->userManagement()->getUser($id);
$users = workos()->userManagement()->listUsers();
```

--------------------------------

### Environment Variable Configuration

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

Define these variables in your .env file to set the WorkOS API credentials and optional base URL.

```bash
WORKOS_API_KEY=pk_test_...
WORKOS_CLIENT_ID=org_...
WORKOS_API_BASE_URL=https://custom.api.com/  # optional
```

--------------------------------

### Create Validation Helper Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Encapsulate resource existence checks within a service class to simplify validation logic across the application.

```php
namespace App\Services;

use WorkOS\WorkOS;

class WorkOSValidator
{
    public function __construct(private WorkOS $workos) {}

    public function validateUser($userId): bool
    {
        try {
            $this->workos->userManagement()->getUser($userId);
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }

    public function validateOrganization($organizationId): bool
    {
        try {
            $this->workos->organizations()->getOrganization($organizationId);
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }
}
```

--------------------------------

### User-Agent String Format

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/version-info.md

The combined format used for the User-Agent header.

```text
'WorkOS PHP Laravel/8.0.1'
```

--------------------------------

### Manage Organizations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Perform CRUD operations on organizations, list memberships, and create invitations.

```php
$org = workos()->organizations()->getOrganization('org_123');

$orgs = workos()->organizations()->listOrganizations();

$newOrg = workos()->organizations()->createOrganization([
    'name' => 'Acme Corp',
]);

$members = workos()->organizations()->listOrganizationMemberships('org_123');

$invitation = workos()->organizations()->createInvitation([
    'organization_id' => 'org_123',
    'email' => 'user@example.com',
]);
```

--------------------------------

### Sync Directory Users

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Retrieve a list of users from a specific directory.

```php
$users = workos()->directorySync()->listDirectoryUsers('dir_123');
```

--------------------------------

### Configure Client ID

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Setting the required WorkOS Client ID via config or environment variable.

```php
'client_id' => 'org_01ARZ3NDEKTSV4RRFFQ69G5FAV'
```

```bash
WORKOS_CLIENT_ID=org_01ARZ3NDEKTSV4RRFFQ69G5FAV
```

--------------------------------

### Manage Organizations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/00_START_HERE.md

Fetch organization details and list memberships for a specific organization ID.

```php
$org = workos()->organizations()->getOrganization('org_123');
$members = workos()->organizations()->listOrganizationMemberships('org_123');
```

--------------------------------

### Access Actions Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve the Actions service instance.

```php
$actions = workos()->actions();
```

--------------------------------

### Retrieve Connection

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Fetch details for a specific connection.

```php
$connection = workos()->connect()->getConnection('conn_123');
```

--------------------------------

### Single Sign-On (SSO)

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Provides Single Sign-On functionality for user authentication.

```APIDOC
## SSO

### Description
Provides Single Sign-On functionality.

### Methods
- `getAuthorizeUrl(array $options)`: Generate an SSO authorization URL.
- `getProfileAndToken(code, domain)`: Exchange authorization code for user profile.
```

--------------------------------

### WorkOS Configuration Error Message

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

The error message thrown when required configuration keys are missing.

```text
WorkOS is not configured: `workos.api_key` is missing. Set the corresponding environment variable (e.g. WORKOS_API_KEY, WORKOS_CLIENT_ID) or publish and edit config/workos.php.
```

--------------------------------

### List Events

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve a list of events.

```php
$events = workos()->events()->listEvents();
```

--------------------------------

### Retrieve API Key

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Fetch details for a specific API key.

```php
$apiKey = workos()->apiKeys()->getApiKey('key_123');
```

--------------------------------

### Validate WorkOS Configuration

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

The service provider checks for the presence of required configuration keys during application registration.

```php
// Ensures both api_key and client_id are present and not empty
foreach (['api_key', 'client_id'] as $required) {
    if (empty($config[$required])) {
        throw new RuntimeException(
            "WorkOS is not configured: `workos.{$required}` is missing. "
            ."Set the corresponding environment variable (e.g. WORKOS_API_KEY, WORKOS_CLIENT_ID) "
            ."or publish and edit config/workos.php."
        );
    }
}
```

--------------------------------

### Access Authorization Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve the Authorization service instance.

```php
$authz = workos()->authorization();
```

--------------------------------

### Manage Organization Domains

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve a specific organization domain or list all domains.

```php
$domain = workos()->organizationDomains()->getOrganizationDomain('org_domain_123');

$domains = workos()->organizationDomains()->listOrganizationDomains();
```

--------------------------------

### Handle Specific WorkOS Exceptions

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Use specific catch blocks to return appropriate HTTP status codes for different WorkOS error types.

```php
use WorkOS\Laravel\Facades\WorkOS;

try {
    $user = WorkOS::userManagement()->getUser($id);
} catch (\WorkOS\Exception\NotFoundException $e) {
    return response()->json(['error' => 'User not found'], 404);
} catch (\WorkOS\Exception\UnauthorizedException $e) {
    return response()->json(['error' => 'Unauthorized'], 401);
} catch (\Exception $e) {
    return response()->json(['error' => 'Server error'], 500);
}
```

--------------------------------

### Handle Webhook Events

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Verifies incoming webhook signatures and dispatches events based on the event type.

```php
namespace App\Http\Controllers\Webhooks;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use WorkOS\Laravel\Facades\WorkOS;
use App\Events\WorkOSUserCreated;

class WorkOSWebhookController extends Controller
{
    public function handle(Request $request)
    {
        try {
            // Verify webhook signature
            $event = WorkOS::webhookVerification()->verifyEvent(
                payload: $request->getContent(),
                sigHeader: $request->header('WorkOS-Signature'),
                secret: config('workos.webhook_secret'),
            );

            // Process event
            match ($event->type) {
                'user.created' => event(new WorkOSUserCreated($event->data)),
                'user.updated' => $this->handleUserUpdated($event->data),
                'user.deleted' => $this->handleUserDeleted($event->data),
                default => null,
            };

            return response()->json(['success' => true]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], Response::HTTP_UNAUTHORIZED);
        }
    }

    private function handleUserUpdated($userData)
    {
        // Update local user record
    }

    private function handleUserDeleted($userData)
    {
        // Delete or deactivate local user
    }
}
```

--------------------------------

### Implement Session Management Middleware

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Middleware to verify WorkOS session validity and redirect to login if expired or invalid.

```php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use WorkOS\Laravel\Facades\WorkOS;

class EnsureWorkOSSession extends Middleware
{
    public function handle(Request $request, Closure $next)
    {
        if (!auth()->check()) {
            return $next($request);
        }

        // Verify session is still valid
        try {
            $session = WorkOS::sessionManager()->getSession(
                sessionId: session('workos_session_id')
            );

            if (!$session || $session->expired_at && now() > $session->expired_at) {
                auth()->logout();
                return redirect('/login');
            }
        } catch (\Exception $e) {
            // Handle verification error
            auth()->logout();
            return redirect('/login');
        }

        return $next($request);
    }
}
```

--------------------------------

### Directory Sync Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Provides functionality for managing users and groups from directory providers.

```APIDOC
## Directory Sync Service

### Description
Provides directory synchronization functionality for managing users and groups from directory providers (LDAP, Active Directory, etc.).

### Methods
- `getDirectory($id)` - Get a directory by ID
- `listDirectories(array $options)` - List all directories
- `listDirectoryUsers($id, array $options)` - List users in a directory
- `listDirectoryGroups($id, array $options)` - List groups in a directory
- `getDirectoryUser($id)` - Get a directory user by ID
- `getDirectoryGroup($id)` - Get a directory group by ID
```

--------------------------------

### Generate Admin Portal Link

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Generate a link to the WorkOS Admin Portal for a specific organization.

```php
// Get Admin Portal link
$intent = WorkOS::adminPortal()->generatePortalLink([
    'organization' => 'org_123',
]);
```

--------------------------------

### Perform Batch Operations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Iterate through collections to perform bulk operations, ensuring errors are caught and logged without halting the process.

```php
public function bulkCreateUsers(array $userEmails)
{
    $created = [];
    
    foreach ($userEmails as $email) {
        try {
            $user = workos()->userManagement()->createUser(['email' => $email]);
            $created[] = $user;
        } catch (\Exception $e) {
            // Log error and continue
            logger()->error("Failed to create user {$email}: {$e->getMessage()}");
        }
    }
    
    return $created;
}
```

--------------------------------

### Manage Users

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Perform CRUD operations on users.

```php
$user = workos()->userManagement()->getUser('user_123');

$users = workos()->userManagement()->listUsers();

$newUser = workos()->userManagement()->createUser([
    'email' => 'user@example.com',
    'password' => 'secure_password',
]);

workos()->userManagement()->updateUser('user_123', [
    'first_name' => 'John',
    'last_name' => 'Doe',
]);

workos()->userManagement()->deleteUser('user_123');
```

--------------------------------

### Generate Admin Portal Link

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Generate a link for the Admin Portal for a specific organization.

```php
$link = workos()->adminPortal()->generatePortalLink([
    'organization' => 'org_123',
]);
```

--------------------------------

### Define WorkOS Environment Variables

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Required and optional environment variables for WorkOS integration.

```bash
# Required environment variables
WORKOS_API_KEY=pk_test_g7u819wVDZK...
WORKOS_CLIENT_ID=org_01ARZ3NDEKTSV4RRFFQ69G5FAV

# Optional environment variables
WORKOS_API_BASE_URL=https://api.workos.com/
```

--------------------------------

### Access WorkOS Client via Service Container

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/configuration.md

Retrieve the configured WorkOS client instance from the Laravel service container.

```php
$workos = app('workos');
$workos = app(\WorkOS\WorkOS::class);
```

--------------------------------

### Admin Portal Service

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Provides methods for managing and generating Admin Portal links.

```APIDOC
## Admin Portal Service

### Description
Provides Admin Portal link generation and management functionality.

### Method
`workos()->adminPortal()->generatePortalLink(array $options)`

### Parameters
- **options** (array) - Required - Configuration options for the portal link, including 'organization'.
```

--------------------------------

### Manual service provider registration

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/installation-and-setup.md

Configuration for auto-discovery or manual registration if auto-discovery is disabled.

```json
"extra": {
  "laravel": {
    "providers": [
      "WorkOS\\Laravel\\WorkOSServiceProvider"
    ]
  }
}
```

```php
'providers' => [
    // ... other providers
    WorkOS\Laravel\WorkOSServiceProvider::class,
],
```

--------------------------------

### Composer Auto-discovery Configuration

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/service-provider.md

Add this entry to your composer.json to enable automatic registration of the WorkOS service provider in Laravel.

```json
"extra": {
  "laravel": {
    "providers": [
      "WorkOS\Laravel\WorkOSServiceProvider"
    ]
  }
}
```

--------------------------------

### Mock the WorkOS Facade in Laravel Tests

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Use the WorkOS facade's built-in mocking capabilities to intercept service calls during testing.

```php
use WorkOS\Laravel\Facades\WorkOS;
use Tests\TestCase;

class UserControllerTest extends TestCase
{
    public function test_shows_user()
    {
        WorkOS::shouldReceive('userManagement')
            ->andReturn($mockUserService);

        $response = $this->get('/users/123');
        $response->assertOk();
    }
}
```

--------------------------------

### Organization Methods

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Method for listing organizations.

```APIDOC
## workos()->organizations()->listOrganizations()

### Description
Retrieves a list of organizations associated with the account.
```

--------------------------------

### Manage Users

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/facades.md

Perform CRUD operations on users via the User Management service.

```php
// Get a user by ID
$user = WorkOS::userManagement()->getUser('user_123');

// List all users
$users = WorkOS::userManagement()->listUsers();

// Create a new user
$newUser = WorkOS::userManagement()->createUser([
    'email' => 'user@acme.com',
    'password' => 'secure_password',
]);
```

--------------------------------

### Authenticate Users via SSO

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/integration-patterns.md

Handles the redirect to the WorkOS authorization URL and processes the callback to retrieve user profiles and tokens.

```php
namespace App\Http\Controllers\Auth;

use Illuminate\Http\Request;
use WorkOS\Laravel\Facades\WorkOS;

class SSOController extends Controller
{
    public function redirect(Request $request)
    {
        $authorizeUrl = WorkOS::sso()->getAuthorizeUrl([
            'domain' => $request->input('domain'),
            'redirectUri' => route('auth.sso.callback'),
            'state' => $this->generateState(),
        ]);

        return redirect($authorizeUrl);
    }

    public function callback(Request $request)
    {
        $profile = WorkOS::sso()->getProfileAndToken(
            code: $request->input('code'),
            domain: $request->input('domain'),
        );

        // Create or update user
        $user = User::updateOrCreate(
            ['workos_id' => $profile->id],
            [
                'email' => $profile->email,
                'first_name' => $profile->firstName,
                'last_name' => $profile->lastName,
            ]
        );

        auth()->login($user);
        return redirect('/dashboard');
    }

    private function generateState()
    {
        $state = bin2hex(random_bytes(16));
        session(['sso_state' => $state]);
        return $state;
    }
}
```

--------------------------------

### List Audit Logs

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve audit logs for a specific organization.

```php
$logs = workos()->auditLogs()->listAuditLogs([
    'organization_id' => 'org_123',
]);
```

--------------------------------

### List Organizations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/REFERENCE_GUIDE.md

Retrieve a list of organizations associated with the WorkOS account.

```php
$orgs = workos()->organizations()->listOrganizations();
```

--------------------------------

### Update Container Resolution

Source: https://github.com/workos/workos-php-laravel/blob/main/docs/V6_MIGRATION_GUIDE.md

Update service resolution to use the WorkOS class instead of the removed WorkOSService wrapper.

```php
$service = app(WorkOSService::class);
// or
$service = app('workos'); // resolved to WorkOSService
```

```php
$client = app(\WorkOS\WorkOS::class);
// or
$client = app('workos'); // resolved to \WorkOS\WorkOS
```

--------------------------------

### Webhooks

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Provides webhook management functionality.

```APIDOC
## Webhooks

### Description
Provides webhook management.

### Methods
- `getWebhook($id)`: Get a webhook by ID.
- `listWebhooks()`: List all webhooks.
- `createWebhook(array $data)`: Create a new webhook.
- `updateWebhook($id, array $data)`: Update a webhook.
- `deleteWebhook($id)`: Delete a webhook.
```

--------------------------------

### Perform SSO Operations

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Generate authorization URLs and exchange codes for user profiles.

```php
$authorizeUrl = workos()->sso()->getAuthorizeUrl([
    'domain' => 'acme.com',
    'redirectUri' => 'https://myapp.com/callback',
    'state' => 'state_string',
]);

$profile = workos()->sso()->getProfileAndToken(
    code: 'code_from_callback',
    domain: 'acme.com',
);
```

--------------------------------

### Verify Webhook Events

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Verify the signature of an incoming webhook event.

```php
$event = workos()->webhookVerification()->verifyEvent([
    'payload' => $requestBody,
    'sigHeader' => $sigHeader,
    'secret' => $secret,
]);
```

--------------------------------

### Define Package Dependencies

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

Required dependencies for the composer.json file to ensure compatibility with Laravel 12/13 and WorkOS PHP SDK.

```json
{
  "require": {
    "php": ">=8.2.0",
    "illuminate/contracts": "^12.0|^13.0",
    "illuminate/support": "^12.0|^13.0",
    "workos/workos-php": "^7.0.1"
  }
}
```

--------------------------------

### Manage Sessions

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/api-reference/supported-services.md

Retrieve a specific session by its ID.

```php
$session = workos()->sessionManager()->getSession('session_123');
```

--------------------------------

### Register WorkOS Service Provider

Source: https://github.com/workos/workos-php-laravel/blob/main/_autodocs/module-reference.md

The service provider is auto-registered by Laravel via package discovery.

```php
use WorkOS\Laravel\WorkOSServiceProvider;

// Auto-registered by Laravel via package discovery
```
Tokens:
Raw