Fastbill Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require development/fastbill
   

   Ensure your composer.json includes "minimum-stability": "dev" if the package is in a dev state.

2. Configuration Add your FastBill API credentials to .env:

   FASTBILL_API_KEY=your_api_key_here
   FASTBILL_API_SECRET=your_api_secret_here
   

3. First Use Case: Fetching a Client

   use Development\FastBill\FastBill;
   
   $fastbill = new FastBill(config('fastbill'));
   $client = $fastbill->clients->get(1); // Fetch client with ID 1
   

4. Key Files to Review

   • src/FastBill.php: Main class for API initialization.
   • src/Resources/Clients.php: Client-related methods (e.g., get(), create()).
   • src/Exceptions/FastBillException.php: Error handling.

Implementation Patterns

Common Workflows

1. CRUD Operations Use the resource-specific classes (e.g., Clients, Invoices, Payments) for standard operations:

   // Create an invoice
   $invoice = $fastbill->invoices->create([
       'client_id' => 1,
       'amount' => 100.00,
       'due_date' => now()->addDays(30)->format('Y-m-d'),
   ]);
   
   // Update an invoice
   $fastbill->invoices->update(123, ['amount' => 150.00]);
   
   // Delete an invoice
   $fastbill->invoices->delete(123);
   

2. Pagination and Filtering Leverage built-in pagination for lists:

   $clients = $fastbill->clients->all(['per_page' => 20, 'page' => 1]);
   

3. Webhooks Configure webhooks via the API and handle callbacks in Laravel:

   // In routes/web.php
   Route::post('/fastbill-webhook', [WebhookController::class, 'handle']);
   

   Validate payloads using FastBill’s signature header:

   $signature = request()->header('X-FastBill-Signature');
   $payload = request()->getContent();
   if (!FastBill::verifyWebhook($signature, $payload)) {
       abort(401);
   }
   

4. Integration with Laravel Jobs Offload API calls to background jobs for performance:

   use Development\FastBill\Jobs\SyncInvoices;
   
   SyncInvoices::dispatch()->onQueue('fastbill');
   

Integration Tips

• Service Provider Binding Bind the FastBill client in AppServiceProvider for dependency injection:

  public function register()
  {
      $this->app->singleton(FastBill::class, function ($app) {
          return new FastBill(config('fastbill'));
      });
  }
  

• API Rate Limiting Implement middleware to handle FastBill’s rate limits:

  public function handle($request, Closure $next)
  {
      if (FastBill::isRateLimited()) {
          return response()->json(['error' => 'Rate limit exceeded'], 429);
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Authentication Errors

   • Issue: 401 Unauthorized responses may occur if FASTBILL_API_KEY or FASTBILL_API_SECRET are misconfigured.
   • Fix: Double-check .env and ensure the API key has the correct permissions in the FastBill dashboard.

2. Deprecated Endpoints

   • The package may not cover all FastBill API versions. Check the FastBill API docs for breaking changes.
   • Workaround: Extend the package or use raw HTTP calls for unsupported endpoints:

     $response = $fastbill->http->get('/v2/clients', ['param' => 'value']);
     

3. Webhook Delays

   • FastBill may retry failed webhook deliveries. Implement idempotency in your handlers:

     if (Webhook::where('payload_hash', $payloadHash)->exists()) {
         return response()->json(['status' => 'already_processed'], 200);
     }
     

4. Currency Formatting

   • Ensure amounts are passed as floats (not strings) to avoid precision issues:

     // Bad
     $fastbill->invoices->create(['amount' => '100.00']);
     
     // Good
     $fastbill->invoices->create(['amount' => 100.00]);
     

Debugging

• Enable Debug Mode Set FASTBILL_DEBUG=true in .env to log raw API responses:

  FASTBILL_DEBUG=true
  

• Logging Exceptions Catch Development\FastBill\Exceptions\FastBillException and log details:

  try {
      $fastbill->invoices->get(123);
  } catch (FastBillException $e) {
      \Log::error('FastBill Error: ' . $e->getMessage(), ['response' => $e->getResponse()]);
  }
  

Extension Points

1. Custom Endpoints Extend the FastBill class to add unsupported endpoints:

   class CustomFastBill extends FastBill
   {
       public function customEndpoint($method, $path, $data = [])
       {
           return $this->http->request($method, $path, $data);
       }
   }
   

2. Model Bindings Use Laravel’s model binding to simplify client/invoice retrieval:

   // In AppServiceProvider
   Route::bind('client', function ($id) {
       return $fastbill->clients->get($id);
   });
   

   Then use in routes:

   Route::get('/client/{client}', [ClientController::class, 'show']);
   

3. Testing Mock the FastBill client in tests using Laravel’s HTTP testing:

   $response = $this->actingAs($user)
       ->post('/invoices', ['client_id' => 1, 'amount' => 100.00])
       ->assertCreated();