Getting Started

Minimal Setup

Installation:
```
composer require codersfree/report
```
Ensure your project uses PHP 8.0+ and Laravel 8+ (or compatible).

First Use Case: Generate a basic HTML invoice representation for SUNAT-compliant electronic billing in Peru.

use CodersFree\Report\Report;

$report = new Report();
$report->setType('01') // Factura Electrónica (01)
       ->setSerie('F001')
       ->setNumber('001-2023')
       ->addItem('Product A', 10, 100.00)
       ->addItem('Product B', 5, 50.00)
       ->setTotal(1000.00)
       ->setClient('Client Name', '12345678901', 'client@example.com');

$html = $report->render();

Where to Look First:
- Official Documentation for SUNAT-specific rules (e.g., QR code generation, tax structure).
- src/Report.php for core methods and available modifiers.
- config/report.php (if auto-generated) for default settings like logos, colors, or tax configurations.

Implementation Patterns

Core Workflows

Dynamic Report Generation:

// Generate reports from a Laravel controller
public function generateInvoice(Request $request) {
    $report = new Report();
    $report->setData($request->all()); // Hydrate from API/form
    return response($report->render(), 200, ['Content-Type' => 'text/html']);
}

Reusable Report Templates:
- Extend the base Report class to create domain-specific templates (e.g., InvoiceReport, CreditNoteReport).
- Override render() to customize HTML structure while reusing core logic:
```
class InvoiceReport extends Report {
    protected function render(): string {
        $html = parent::render();
        return $this->addFooter($html); // Custom footer logic
    }
}
```

Integration with SUNAT API:

Use the package to generate HTML representations after validating/communicating with SUNAT’s API (e.g., sunat.pe).

Example:

$sunatResponse = $this->sunatService->sendInvoice($invoiceData);
if ($sunatResponse->isValid()) {
    $report = new Report($sunatResponse->getData());
    return $report->render();
}

PDF Conversion:

Pipe the HTML output to a PDF library (e.g., barryvdh/laravel-dompdf):

use Barryvdh\DomPDF\Facade\Pdf;

$pdf = Pdf::load($report->render());
return $pdf->download('invoice.pdf');

Localization:

Override text labels (e.g., "Total", "Subtotal") via:

$report->setLanguage('es'); // Spanish for Peru
$report->setLabels([
    'total' => 'Total a Pagar',
    'tax' => 'IGV (18%)'
]);

Gotchas and Tips

Pitfalls

SUNAT Compliance:
- QR Code Validation: The package generates QR codes, but SUNAT requires strict validation. Always cross-check with SUNAT’s QR generator.
- Tax Structure: Peru uses IGV (18%) by default. Override with:
```
$report->setTaxRate(18.0); // Explicitly set for clarity.
```
Data Sanitization:
- XSS Risks: User-provided data (e.g., client names) must be escaped. Use Laravel’s e() helper or HTML entities:
```
$report->setClient(htmlspecialchars($request->client_name));
```

Configuration Overrides:

The package may not auto-generate config/report.php. Manually create it to override defaults:

return [
    'logo_path' => public_path('images/logo.png'),
    'default_tax_rate' => 18.0,
    'qr_size' => 100,
];

Performance:
- Large Reports: For invoices with >1000 items, cache the HTML output or use chunked rendering:
```
$report->setItems(array_chunk($items, 100)); // Process in batches
```

Debugging Tips

Validate HTML Output:
- Use browser dev tools to inspect the generated HTML for missing elements (e.g., QR code, tax breakdown).
- Check for SUNAT-required fields like:
```
<div class="sunat-required">• Número de Comprobante</div>
```

Logging:

Enable debug mode to log SUNAT-specific warnings:

$report->debug(true);
// Logs to storage/logs/report.log

Testing:

Mock SUNAT responses in tests:

$report = new Report();
$report->setSunatData(['cdr' => 'mock_cdr']); // Simulate SUNAT response

Extension Points

Custom Fields:

Add SUNAT-specific fields (e.g., setOperationType(), setGuiaRemision()) by extending the class:

class PeruInvoiceReport extends Report {
    public function setOperationType(string $type): self {
        $this->data['operation_type'] = $type;
        return $this;
    }
}

Hooks:

Override beforeRender() to modify data before HTML generation:

protected function beforeRender(): void {
    $this->data['footer_text'] = 'Pago contra entrega';
}

Theming:

Replace the default CSS by overriding the getStyles() method:

protected function getStyles(): string {
    return file_get_contents(public_path('css/custom-report.css'));
}

Multi-Currency:

Extend to support USD/PEN conversion (Peru’s dual-currency system):

$report->setCurrency('PEN'); // Default
$report->setCurrency('USD', 3.8); // USD with exchange rate


```markdown
### Laravel-Specific Tips
1. **Service Provider Binding**:
   Bind the report class for dependency injection:
   ```php
   // app/Providers/AppServiceProvider.php
   public function register() {
       $this->app->bind(Report::class, function ($app) {
           return new Report(config('report.defaults'));
       });
   }

Artisan Commands: Create a command to generate reports from CLI:

// app/Console/Commands/GenerateReport.php
public function handle() {
    $report = app(Report::class);
    $report->setData($this->getInvoiceData());
    file_put_contents('invoice.html', $report->render());
}

Storage Integration: Save reports to Laravel’s storage:

use Illuminate\Support\Facades\Storage;

Storage::disk('public')->put('reports/invoice-' . $id . '.html', $report->render());

Queue Jobs: Offload report generation to queues for long-running tasks:

// app/Jobs/GenerateReportJob.php
public function handle() {
    $report = new Report($this->data);
    $this->saveReport($report->render());
}

API Responses: Return reports as API responses with proper headers:

return response($report->render())
    ->header('Content-Type', 'text/html')
    ->header('X-Report-Type', 'sunat-invoice');

Report Laravel Package