Fakturownia Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codevenom/fakturownia-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Codevenom\FakturowniaBundle\FakturowniaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console fakturownia:install
   

   Update config/packages/fakturownia.yaml with your API credentials and endpoints.

3. First Use Case Inject the InvoiceClient service into a controller or command:

   use Codevenom\FakturowniaBundle\Client\InvoiceClient;
   
   public function __construct(private InvoiceClient $invoiceClient) {}
   
   public function createInvoice(Request $request) {
       $invoice = $this->invoiceClient->add([
           'number' => 'INV-2023-001',
           'customer_id' => 123,
           'items' => [...],
       ]);
       return new JsonResponse($invoice);
   }
   

Implementation Patterns

Domain-Driven Workflows

1. Context Separation Use dedicated clients for each domain (InvoiceClient, CustomerClient, PricingClient) to enforce clean boundaries:

   // Invoice workflow
   $invoice = $invoiceClient->add($data);
   $customer = $customerClient->findById($invoice['customer_id']);
   
   // Pricing workflow
   $pricing = $pricingClient->getStrategy('dynamic')->calculate($invoice);
   

2. MCP Integration Expose tools to AI agents via symfony/mcp-bundle:

   # config/packages/mcp.yaml
   mcp:
       tools:
           - codevenom.fakturownia.invoice.add
           - codevenom.fakturownia.customer.find_by_id
   

   Trigger tools programmatically:

   $this->mcpToolRunner->run('codevenom.fakturownia.invoice.add', ['data' => $payload]);
   

3. Reporting Strategies Extend the reporting engine with custom strategies:

   // src/Reporting/Strategy/CustomStrategy.php
   class CustomStrategy implements ReportingStrategyInterface {
       public function generate(ReportData $data): array {
           // Custom logic
       }
   }
   

   Register in config/packages/fakturownia.yaml:

   reporting:
       strategies:
           custom: App\Reporting\Strategy\CustomStrategy
   

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The bundle does not handle retries by default. Implement middleware for exponential backoff:

     // src/Client/Middleware/RateLimitMiddleware.php
     public function handle(ClientRequestInterface $request, callable $next) {
         if ($this->isRateLimited()) {
             sleep($this->calculateRetryDelay());
         }
         return $next($request);
     }
     

2. Data Validation

   • Fakturownia’s API may reject malformed requests silently. Validate inputs before sending:

     use Codevenom\FakturowniaBundle\Validator\InvoiceValidator;
     
     $validator = new InvoiceValidator();
     if (!$validator->isValid($data)) {
         throw new \InvalidArgumentException($validator->getErrors());
     }
     

3. MCP Tool Naming

   • Tools are case-sensitive and must match the bundle’s naming convention exactly (e.g., codevenom.fakturownia.invoice.add). Typos will result in ToolNotFoundException.

Debugging

1. Enable API Logging Add to config/packages/fakturownia.yaml:

   api:
       logging: true
   

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

2. Mocking for Tests Use the bundle’s MockClient for unit tests:

   $mockClient = new MockInvoiceClient();
   $mockClient->shouldReceive('add')->once()->andReturn($mockInvoice);
   $this->container->set(InvoiceClient::class, $mockClient);
   

Extension Points

1. Custom Clients Extend base clients to add domain-specific logic:

   class CustomInvoiceClient extends InvoiceClient {
       public function bulkCreate(array $invoices): array {
           return $this->client->post('/invoices/bulk', $invoices);
       }
   }
   

   Register as a service:

   services:
       App\Client\CustomInvoiceClient:
           arguments: ['@fakturownia.client']
           tags: ['fakturownia.client']
   

2. Webhook Handlers The bundle lacks built-in webhook support. Implement a listener for fakturownia.webhook events:

   // src/EventListener/FakturowniaWebhookListener.php
   public function onWebhook(WebhookEvent $event) {
       $payload = $event->getPayload();
       // Process webhook (e.g., update local DB)
   }
   

   Register in config/services.yaml:

   services:
       App\EventListener\FakturowniaWebhookListener:
           tags:
               - { name: kernel.event_listener, event: fakturownia.webhook }