Laravel Float Sdk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/laravel-float-sdk
   

   Publish the config file (if needed):

   php artisan vendor:publish --provider="Spatie\FloatSdk\FloatSdkServiceProvider"
   

2. Configuration: Update .env with Float API credentials:

   FLOAT_API_KEY=your_api_key_here
   FLOAT_API_SECRET=your_api_secret_here
   FLOAT_BASE_URL=https://api.float.com/v3
   

3. First Use Case: Fetch a client's data:

   use Spatie\FloatSdk\Float;
   
   $client = Float::client()->find(123);
   

Where to Look First

• Documentation: The Float API docs (v3) are the primary reference.
• SDK Methods: Check src/Spatie/FloatSdk/Float.php for available endpoints.
• Config: .env and config/float-sdk.php for API settings.

Implementation Patterns

Core Workflows

1. Client Management:

   // Create
   $client = Float::client()->create([
       'name' => 'John Doe',
       'email' => 'john@example.com',
   ]);
   
   // Update
   $client->update(['email' => 'new@example.com']);
   
   // Delete
   $client->delete();
   

2. Invoices & Payments:

   // Fetch invoices
   $invoices = Float::invoice()->all(['limit' => 10]);
   
   // Create payment
   $payment = Float::payment()->create([
       'invoice_id' => 456,
       'amount' => 100.00,
       'method' => 'bank_transfer',
   ]);
   

3. Webhooks: Configure webhook endpoints in config/float-sdk.php:

   'webhooks' => [
       'endpoint' => '/float-webhook',
       'events' => ['invoice.paid', 'client.created'],
   ],
   

   Handle incoming webhooks in a Laravel route:

   Route::post('/float-webhook', [FloatWebhookHandler::class, 'handle']);
   

Integration Tips

• Service Layer: Wrap SDK calls in a service class for business logic:

  class FloatClientService {
      public function createClient(array $data) {
          return Float::client()->create($data);
      }
  }
  

• Error Handling: Use Laravel’s exception handling:

  try {
      $client = Float::client()->find(123);
  } catch (\Spatie\FloatSdk\Exceptions\FloatException $e) {
      Log::error("Float API Error: " . $e->getMessage());
      abort(500);
  }
  

• Testing: Mock the SDK in tests:

  $this->mock(Float::class)->shouldReceive('client')->andReturnSelf();
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • Float’s API has rate limits (e.g., 60 requests/minute). Cache responses aggressively:

     $client = Cache::remember("float_client_{$id}", now()->addMinutes(5), fn() => Float::client()->find($id));
     

   • Monitor HTTP_429 responses and implement retries with exponential backoff.

2. Webhook Verification:

   • Always verify webhook signatures using Float’s X-Float-Signature header:

     use Spatie\FloatSdk\Webhook;
     
     $payload = request()->getContent();
     $signature = request()->header('X-Float-Signature');
     
     if (!Webhook::verify($payload, $signature)) {
         abort(403, 'Invalid signature');
     }
     

3. Idempotency:

   • Use idempotency_key for critical operations (e.g., payments) to avoid duplicates:

     $payment = Float::payment()->create([
         'invoice_id' => 456,
         'idempotency_key' => 'unique-key-123',
     ]);
     

Debugging

• Enable Debug Mode: Set FLOAT_DEBUG=true in .env to log raw API responses.
• Log API Calls: Extend the SDK to log requests/responses:

  Float::extend(function ($client) {
      $client->onRequest(function ($request) {
          Log::debug('Float Request:', $request->toArray());
      });
  });
  

Extension Points

1. Custom Endpoints: Add unsupported endpoints by extending the SDK:

   Float::extend(function ($client) {
       $client->customEndpoint = function ($method, $path, $data = []) {
           return $client->request($method, $path, $data);
       };
   });
   

2. Middleware: Attach middleware to modify requests/responses:

   Float::extend(function ($client) {
       $client->withMiddleware(function ($request) {
           $request->headers->set('X-Custom-Header', 'value');
       });
   });
   

3. Event Dispatching: Trigger Laravel events for Float webhooks:

   event(new FloatWebhookReceived($payload, $signature));
   

Config Quirks

• Base URL: Ensure FLOAT_BASE_URL matches Float’s environment (e.g., https://api.float.com/v3 for production).
• Timeouts: Adjust Guzzle’s timeout in config/float-sdk.php:

  'timeout' => 30, // seconds
  

• SSL Verification: Disable only for testing (not production):

  'verify_ssl' => env('FLOAT_VERIFY_SSL', true),