Boleta Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require ascensodigital/boleta-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       AscensoDigital\BoletaBundle\AscensoDigitalBoletaBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference AscensoDigital\BoletaBundle\Resources\config\services.yml
   

   Override in config/packages/ascenso_digital_boleta.yaml:

   ascenso_digital_boleta:
       imap:
           host: 'your.imap.server'
           port: 993
           username: 'your@email.com'
           password: 'your_password'
           ssl: true
       processing:
           directory: '%kernel.project_dir%/var/boletas'
   

3. First Use Case: Fetching Emails Trigger the email processor via CLI:

   php bin/console ascenso-digital:boleta:fetch
   

   This downloads attachments (PDFs) from the IMAP server into var/boletas/.

Implementation Patterns

Workflow: Processing Invoices

1. Fetching Emails Use the command to pull emails from IMAP:

   php bin/console ascenso-digital:boleta:fetch --days=7  # Fetch emails from last 7 days
   

   • Configurable via ascenso_digital_boleta.imap in YAML.

2. Parsing PDFs Process downloaded PDFs with:

   php bin/console ascenso-digital:boleta:parse
   

   • Leverages php-xpdf for text extraction. Outputs structured data to Doctrine entities (e.g., Boleta).

3. Integration with EasyAdmin Display parsed boletas in the admin panel:

   # config/packages/easy_admin.yaml
   easy_admin:
       entities:
           AscensoDigital\BoletaBundle\Entity\Boleta:
               class: AscensoDigital\BoletaBundle\Entity\Boleta
               label: 'Boletas'
               list:
                   fields: ['rut', 'fecha', 'monto', 'estado']
   

4. Exporting Data Export boletas to Excel via LiuggioExcelBundle:

   use AscensoDigital\BoletaBundle\Service\BoletaExporter;
   
   $exporter = $this->get('ascenso_digital_boleta.exporter');
   $exporter->exportToExcel($boletas, 'boletas.xlsx');
   

Key Patterns

• Event-Driven Processing Listen for boleta.fetched and boleta.parsed events to trigger custom logic:

  // src/EventListener/BoletaListener.php
  public function onBoletaFetched(BoletaFetchedEvent $event) {
      $this->notifyAdmin($event->getBoleta());
  }
  

• Doctrine Entities Extend Boleta entity for custom fields:

  // src/Entity/CustomBoleta.php
  #[ORM\Entity]
  class CustomBoleta extends Boleta {
      #[ORM\Column]
      private string $customField;
  }
  

• Scheduled Processing Use Symfony’s CronBundle or a task scheduler to run fetch/parse daily:

  # config/packages/cron.yaml
  cronjobs:
      fetch_boletas:
          command: 'ascenso-digital:boleta:fetch'
          schedule: '0 9 * * *'
  

Gotchas and Tips

Pitfalls

1. IMAP Configuration

   • Error: Connection could not be established. Fix: Verify ext-imap is enabled (php -m | grep imap) and IMAP SSL settings. Tip: Use a dedicated email account for the bot to avoid rate limits.

2. PDF Parsing Failures

   • Error: PDF parsing failed for [filename]. Fix: Ensure php-xpdf is installed (pecl install xpdf) and the PDF structure is standard (non-scanned images may fail). Tip: Debug with php-xpdf's pdf2text directly on the file.

3. Doctrine Migrations

   • Error: Column not found after updating entities. Fix: Run:

     php bin/console doctrine:migrations:diff
     php bin/console doctrine:migrations:migrate
     

4. EasyAdmin Caching

   • Issue: Changes to Boleta entity not reflected in EasyAdmin. Fix: Clear cache:

     php bin/console cache:clear
     php bin/console easyadmin:cache:clear
     

Debugging Tips

• Log IMAP Activity Enable debug mode in ascenso_digital_boleta.yaml:

  imap:
      debug: true
  

  Logs appear in var/log/dev.log.

• Validate Email Parsing Test PDF parsing manually:

  use AscensoDigital\BoletaBundle\Service\PdfParser;
  
  $parser = new PdfParser();
  $data = $parser->parse('/path/to/boleta.pdf');
  var_dump($data);
  

• Override Default Behavior Extend the BoletaFetcher service:

  # config/services.yaml
  services:
      App\Service\CustomBoletaFetcher:
          decorates: ascenso_digital_boleta.boleta_fetcher
          arguments: ['@.inner']
  

Extension Points

1. Custom Parsing Logic Override PdfParser to handle non-standard PDFs:

   // src/Service/CustomPdfParser.php
   class CustomPdfParser extends PdfParser {
       protected function extractRut($text) {
           // Custom regex logic
       }
   }
   

   Register in services.yaml:

   ascenso_digital_boleta.pdf_parser: '@App\Service\CustomPdfParser'
   

2. Webhook Notifications Trigger HTTP requests on boleta.parsed:

   use AscensoDigital\BoletaBundle\Event\BoletaParsedEvent;
   use Symfony\Component\HttpClient\HttpClient;
   
   public function onBoletaParsed(BoletaParsedEvent $event) {
       $client = HttpClient::create();
       $client->request('POST', 'https://api.example.com/webhook', [
           'json' => ['boleta_id' => $event->getBoleta()->getId()]
       ]);
   }
   

3. Bulk Processing Process multiple PDFs in a batch:

   use AscensoDigital\BoletaBundle\Service\BoletaProcessor;
   
   $processor = $this->get('ascenso_digital_boleta.processor');
   $results = $processor->processDirectory('/path/to/boletas');