Fastbill Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require dvelopment/fastbill-bundle dev-master in your project root. Ensure AppKernel.php includes:

   new DVelopment\FastBillBundle\DVelopmentFastBillBundle(),
   

2. Configuration Add credentials to config.yml:

   d_velopment_fast_bill:
       username: %fast_bill_username%  # Your FastBill email
       apiKey:   %fast_bill_api_key%    # From my.fastbill.com
   

   Define parameters in .env or parameters.yml:

   parameters:
       fast_bill_username: your@email.com
       fast_bill_api_key: your_api_key_here
   

3. First Use Case Inject the API service into a controller/service:

   use Symfony\Component\DependencyInjection\ContainerInterface;
   
   class InvoiceController extends Controller
   {
       public function listInvoices(ContainerInterface $container)
       {
           $api = $container->get('d_velopment_fast_bill.api');
           $invoices = $api->getInvoices(); // Fetch all invoices
           return $this->render('invoice/index.html.twig', ['invoices' => $invoices]);
       }
   }
   

Implementation Patterns

Core Workflows

1. CRUD Operations Use the API wrapper for standard operations:

   // Create
   $customer = $api->createCustomer(['name' => 'John Doe', 'email' => 'john@example.com']);
   
   // Read
   $customer = $api->getCustomer($customerId);
   
   // Update
   $api->updateCustomer($customerId, ['email' => 'new@example.com']);
   
   // Delete
   $api->deleteCustomer($customerId);
   

2. Pagination & Filtering Leverage FastBill’s API endpoints for pagination:

   $invoices = $api->getInvoices(['page' => 2, 'per_page' => 10]);
   

3. Webhook Integration Use the bundle to verify webhook signatures (if supported) or process incoming data:

   // Example: Validate a webhook payload (if bundle supports it)
   $isValid = $api->validateWebhook($payload, $signature);
   

4. Event-Driven Actions Trigger actions post-invoice creation (e.g., send email):

   $invoice = $api->createInvoice($data);
   $this->mailer->sendInvoiceEmail($invoice);
   

Integration Tips

• Dependency Injection Prefer constructor injection over container access:

  class InvoiceService {
      public function __construct(private FastBillApi $api) {}
  }
  

  Register the service in services.yml:

  services:
      App\Service\InvoiceService:
          arguments:
              $api: '@d_velopment_fast_bill.api'
  

• Error Handling Wrap API calls in try-catch blocks:

  try {
      $api->createInvoice($data);
  } catch (\DVelopment\FastBill\Exception\ApiException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Testing Mock the API service in tests:

  $mockApi = $this->createMock(FastBillApi::class);
  $mockApi->method('getCustomers')->willReturn([...]);
  $service = new InvoiceService($mockApi);
  

Gotchas and Tips

Pitfalls

1. API Rate Limits FastBill may throttle requests. Implement exponential backoff:

   use Symfony\Component\Stopwatch\Stopwatch;
   
   $stopwatch = new Stopwatch();
   $event = $stopwatch->start('fastbill_request');
   
   try {
       $api->getCustomers();
   } catch (\DVelopment\FastBill\Exception\RateLimitException $e) {
       sleep($e->getRetryAfter());
       $api->getCustomers();
   }
   

2. Deprecated Methods The dev-master branch may use unstable methods. Check the underlying dVelopment/fastbill library for breaking changes.

3. Configuration Overrides Avoid hardcoding credentials. Use %fast_bill_* parameters and .env for security.

4. Service Naming Collisions The service name (d_velopment_fast_bill.api) is verbose. Alias it in services.yml:

   services:
       fastbill.api: '@d_velopment_fast_bill.api'
   

Debugging

• Enable API Debugging Set debug: true in config.yml (if supported):

  d_velopment_fast_bill:
      debug: true
  

  Logs will appear in var/log/dev.log.

• Inspect Raw Responses Extend the API service to log requests/responses:

  $api->setLogger($logger); // If supported
  

Extension Points

1. Custom API Endpoints Extend the bundle by creating a decorator service:

   services:
       app.fastbill.api.decorated:
           decorates: d_velopment_fast_bill.api
           arguments: ['@app.fastbill.api.decorated.inner']
   

   class CustomFastBillApiDecorator extends FastBillApi
   {
       public function customMethod() {
           return $this->inner->get('/custom-endpoint');
       }
   }
   

2. Event Listeners Listen for API events (if the library dispatches them):

   services:
       app.fastbill.listener:
           class: App\EventListener\FastBillListener
           tags:
               - { name: kernel.event_listener, event: fastbill.api.response, method: onResponse }
   

3. Batch Processing Use Laravel’s queue system to handle large datasets:

   foreach ($api->getCustomers(['per_page' => 100]) as $customer) {
       ProcessCustomerJob::dispatch($customer);
   }