Sdk Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bella-baxter/sdk
   

   Ensure your project meets the requirements (PHP 8.1+, ext-curl, ext-json, ext-openssl).

2. Environment Setup:

   • Register an API key in Bella Baxter via bella apikeys create.
   • Note your clientId, clientSecret, and environmentSlug (e.g., production).

3. First Use Case: Initialize the client and fetch secrets in a Laravel service or config loader:

   use BellaBaxter\BaxterClient;
   use BellaBaxter\BaxterClientOptions;
   
   $client = new BaxterClient(new BaxterClientOptions(
       baxterUrl:       env('BELLA_BAXTER_URL', 'https://baxter.example.com'),
       clientId:        env('BELLA_BAXTER_CLIENT_ID'),
       clientSecret:    env('BELLA_BAXTER_CLIENT_SECRET'),
       environmentSlug: env('BELLA_BAXTER_ENVIRONMENT', 'production'),
       enableE2ee:      env('BELLA_BAXTER_E2EE', false),
   ));
   
   $secrets = $client->getAllSecrets();
   

4. Integrate with Laravel: Bind the client to the service container in config/app.php or a service provider:

   $app->singleton(BaxterClient::class, function ($app) {
       return new BaxterClient(new BaxterClientOptions(
           // ... options from config
       ));
   });
   

Implementation Patterns

Workflows

1. Bootstrap Secrets Early: Load secrets during Laravel’s bootstrapping (e.g., AppServiceProvider::boot()) to avoid runtime delays:

   public function boot()
   {
       $client = app(BaxterClient::class);
       $secrets = $client->getAllSecrets();
   
       config(['database.connections.mysql.url' => $secrets['DATABASE_URL']]);
   }
   

2. Cache Secrets: Cache secrets for a short TTL (e.g., 5 minutes) to reduce API calls:

   $secrets = Cache::remember('bella_baxter_secrets', now()->addMinutes(5), function () {
       return app(BaxterClient::class)->getAllSecrets();
   });
   

3. Environment-Specific Config: Use the environmentSlug to dynamically switch between dev/staging/prod secrets:

   $client = new BaxterClient(new BaxterClientOptions(
       environmentSlug: app()->environment() === 'production' ? 'prod' : 'staging',
       // ...
   ));
   

4. E2EE for Sensitive Data: Enable enableE2ee: true for secrets containing PII or highly sensitive data (e.g., API keys for payment gateways).

5. Error Handling: Wrap SDK calls in try-catch blocks to handle rate limits or auth failures gracefully:

   try {
       $secrets = $client->getAllSecrets();
   } catch (BaxterException $e) {
       Log::error("Failed to fetch secrets: " . $e->getMessage());
       throw new RuntimeException("Secret management unavailable");
   }
   

Integration Tips

• Laravel Config: Merge fetched secrets into Laravel’s config:

  $config = array_merge(
      config('services.bella_baxter.defaults'),
      $secrets
  );
  config($config);
  

• Environment Variables: Use the SDK to override .env variables dynamically (e.g., for CI/CD):

  putenv("DB_CONNECTION=mysql");
  putenv("DB_URL=" . $secrets['DATABASE_URL']);
  

• Testing: Mock the BaxterClient in tests using Laravel’s mocking tools:

  $this->mock(BaxterClient::class, function ($mock) {
      $mock->shouldReceive('getAllSecrets')
           ->andReturn(['TEST_KEY' => 'test-value']);
  });
  

Gotchas and Tips

Pitfalls

1. E2EE Overhead:

   • E2EE adds ~100ms latency per request due to key exchange and encryption.
   • Avoid enabling it for non-sensitive secrets (e.g., APP_DEBUG).

2. Key Rotation:

   • If clientSecret changes, regenerate the client instance to avoid stale sessions.
   • Monitor Bella Baxter’s API rate limits (default: 60 requests/minute).

3. Network Dependencies:

   • The SDK blocks during API calls. For high-availability apps, consider:
     • Running the SDK in a separate process (e.g., queue job).
     • Implementing a local cache with a short TTL.

4. Secret Naming:

   • Use consistent naming conventions (e.g., SERVICE_NAME__KEY) to avoid collisions.
   • Avoid spaces or special characters in secret keys.

5. PHP Extensions:

   • Missing ext-openssl will break E2EE. Verify with:

     php -m | grep openssl
     

Debugging

• Enable Verbose Logging: Set the BELLA_BAXTER_DEBUG env var to log raw API responses:

  $client = new BaxterClient(new BaxterClientOptions(
      // ...
      debug: true,
  ));
  

• Check Headers: Use curl -v or browser dev tools to verify the X-E2E-Public-Key header is sent with E2EE enabled.

• Common Errors:

  • 401 Unauthorized: Invalid clientId/clientSecret or expired credentials.
  • 403 Forbidden: Missing permissions for the environmentSlug.
  • 500 Server Error: Contact Bella Baxter support if E2EE fails silently.

Tips

1. Local Development: Use a .env.local file to override secrets for local testing:

   $client = new BaxterClient(new BaxterClientOptions(
       environmentSlug: env('APP_ENV') === 'local' ? 'dev' : 'production',
       // ...
   ));
   

2. Secret Validation: Validate secrets on fetch to catch misconfigurations early:

   $secrets = $client->getAllSecrets();
   if (empty($secrets['DATABASE_URL'])) {
       throw new RuntimeException("Missing DATABASE_URL secret");
   }
   

3. Extending the SDK:

   • Override the BaxterClient class to add custom methods (e.g., getSecret(string $key)):

     class CustomBaxterClient extends BaxterClient {
         public function getSecret(string $key): string {
             return $this->getAllSecrets()[$key];
         }
     }
     

4. Performance:

   • For monolithic apps, lazy-load secrets only when needed (e.g., in a SecretsManager facade).

5. Security:

   • Restrict Bella Baxter API keys to specific IPs or environments in the Bella Baxter dashboard.
   • Rotate clientSecret regularly (e.g., monthly).