Workos Php Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require workos/workos-php
   

   Ensure your project meets PHP 8.1+ requirements.

2. First Use Case: Authentication Initialize the client with your API key:

   use WorkOS\WorkOS;
   
   $client = new WorkOS('your_api_key_here');
   

   Verify connectivity with a simple API call:

   $response = $client->get('/directory');
   $response->json(); // Returns directory data
   

3. Where to Look First

   • WorkOS PHP SDK Docs (if available)
   • WorkOS API Reference for endpoint details
   • src/WorkOS.php for core client logic and request handling

Implementation Patterns

Common Workflows

1. Directory Management Fetch and update user directories:

   // Fetch all users
   $users = $client->get('/directory/users')->json();
   
   // Create a new user
   $newUser = $client->post('/directory/users', [
       'email' => 'user@example.com',
       'first_name' => 'John',
       'last_name' => 'Doe',
   ])->json();
   

2. SSO Integration Generate SSO links for users:

   $ssoLink = $client->post('/sso/link', [
       'user_id' => 'user_123',
       'redirect_to' => 'https://app.example.com/dashboard',
   ])->json();
   

3. Event Webhooks Listen for events (e.g., user creation):

   $webhook = $client->post('/webhooks', [
       'target_url' => 'https://your-app.com/webhook',
       'events' => ['user.created'],
   ])->json();
   

Integration Tips

• Laravel Service Provider Bind the client to the container for dependency injection:

  // config/services.php
  'workos' => [
      'api_key' => env('WORKOS_API_KEY'),
  ];
  
  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(WorkOS::class, function ($app) {
          return new WorkOS(config('services.workos.api_key'));
      });
  }
  

• API Rate Limiting Handle rate limits gracefully:

  try {
      $response = $client->get('/directory');
  } catch (WorkOS\Exception\RateLimitException $e) {
      // Retry logic or notify admin
  }
  

• Pagination Use the next_page URL from responses for paginated endpoints:

  $response = $client->get('/directory/users');
  $users = $response->json();
  $nextPage = $response->headers->get('link') ?? null;
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Never hardcode API keys in version control. Use Laravel's .env:

     WORKOS_API_KEY=your_api_key_here
     

   • Restrict the key to specific IP addresses or use WorkOS's API key restrictions.

2. Idempotency

   • Some endpoints (e.g., user creation) support idempotency keys to avoid duplicate operations:

     $client->post('/directory/users', [
         'email' => 'user@example.com',
         'idempotency_key' => 'unique_key_here',
     ]);
     

3. Webhook Verification

   • Always verify incoming webhook signatures using WorkOS's workos-signature header:

     use WorkOS\WorkOS;
     
     $payload = file_get_contents('php://input');
     $signature = $_SERVER['HTTP_WORKOS_SIGNATURE'] ?? '';
     $isValid = WorkOS::verifyWebhook($payload, $signature, 'your_api_key');
     

Debugging

• Enable Debug Mode Toggle debug mode for verbose error messages:

  $client = new WorkOS('api_key', [
      'debug' => true,
  ]);
  

• Logging Requests Use Laravel's logging to track API calls:

  $client->get('/directory')->then(function ($response) {
      \Log::debug('WorkOS API Response', ['response' => $response->json()]);
  });
  

Extension Points

1. Custom Requests Extend the client for unsupported endpoints:

   $client->customRequest('GET', '/custom/endpoint', [], [
       'custom_header' => 'value',
   ]);
   

2. Middleware Add request/response middleware:

   $client->addMiddleware(function ($request) {
       $request->headers->set('X-Custom-Header', 'value');
   });
   

3. Mocking for Tests Use Laravel's HTTP mocking or create a test double:

   $mockClient = Mockery::mock(WorkOS::class);
   $mockClient->shouldReceive('get')->andReturn(new WorkOS\Response(200, [], json_encode(['test' => true])));