Invoice Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require 2le/invoice-bundle
   

2. Configure Doctrine Target Entities in config/packages/doctrine.yaml:

   orm:
       resolve_target_entities:
           Lle\InvoiceBundle\Model\CustomerInterface: App\Entity\User
           Lle\InvoiceBundle\Model\InvoiceInterface: App\Entity\Invoice
           Lle\InvoiceBundle\Model\InvoiceLineInterface: App\Entity\InvoiceLine
           Lle\InvoiceBundle\Model\PaymentInterface: App\Entity\Payment
   

3. Implement Traits in your entities (e.g., Invoice):

   use Lle\InvoiceBundle\Model\InvoiceTrait;
   
   class Invoice implements InvoiceInterface
   {
       use InvoiceTrait;
       // ...
   }
   

First Use Case

Generate a draft invoice for a user:

use Lle\InvoiceBundle\Manager\InvoiceManager;

public function createDraft(InvoiceManager $invoiceManager, User $user): Response
{
    $invoice = $invoiceManager->generate($user);
    // Persist $invoice if needed
    return $this->render('invoice/create.html.twig', ['invoice' => $invoice]);
}

Implementation Patterns

Core Workflows

1. Invoice Creation:

   • Use InvoiceManager to generate drafts or validate invoices.
   • Pre-fill data with a CustomerInterface (e.g., User):

     $invoice = $invoiceManager->generate($customer);
     $invoiceManager->validate($invoice);
     

2. PDF Generation:

   • Configure lle_invoice.yaml:

     lle_invoice:
         logo: 'public/assets/logo.png'
         header: 'Company Name\nAddress'
         footer: 'Thank you for your business'
     

   • Generate PDF via InvoicePDF service (if available in newer versions).

3. Exporting:

   • Export single/multiple invoices to CSV:

     $invoiceExporter->export([$invoice1, $invoice2], 'invoices.csv');
     

Integration Tips

• EasyAdmin: Use the bundle’s entities with EasyAdmin for CRUD:

  # config/packages/easy_admin.yaml
  easy_admin:
      entities:
          Invoice: App\Entity\Invoice
          InvoiceLine: App\Entity\InvoiceLine
  

• Custom Logic: Extend traits (e.g., InvoiceTrait) to add fields/methods:

  class Invoice implements InvoiceInterface
  {
      use InvoiceTrait;
  
      public function getCustomField(): string
      {
          return $this->customField;
      }
  }
  

Gotchas and Tips

Pitfalls

1. Doctrine Target Entities:

   • Forgetting to map interfaces (e.g., CustomerInterface) to concrete entities causes runtime errors.
   • Fix: Verify resolve_target_entities in doctrine.yaml matches your bundle’s expectations.

2. Trait Conflicts:

   • Overriding methods in traits (e.g., InvoiceTrait) may break bundle functionality.
   • Fix: Use use InvoiceTrait { method as private; } to avoid conflicts.

3. PDF Generation:

   • The InvoicePDF service is undocumented in the README but referenced in usage examples.
   • Workaround: Check the InvoiceExporter or use a third-party library (e.g., dompdf) if PDF generation is critical.

Debugging

• Validation Errors:
  • If validate() fails silently, enable Doctrine debug mode:

    # config/packages/dev/doctrine.yaml
    doctrine:
        dbal:
            logging: true
    

• Missing Fields:
  • Ensure all required fields (e.g., number, date) are set before validation. Use InvoiceTrait methods like setNumber() if needed.

Extension Points

1. Custom Exporters:
   • Extend InvoiceExporter to support additional formats (e.g., Excel):

     class CustomExporter extends InvoiceExporter
     {
         public function exportToExcel(array $invoices, string $filename): void
         {
             // Logic here
         }
     }
     

2. Payment Logic:
   • Implement PaymentInterface and integrate with payment gateways (e.g., Stripe) via PaymentManager.
3. Localization:
   • Override bundle translations in config/packages/lle_invoice.yaml:

     lle_invoice:
         translations:
             invoice: 'Facture' # French for "Invoice"