Facturax Contracts Laravel Package

Technical Evaluation

Architecture Fit

• Factura-X Alignment: The package provides versioned DTOs for Factura-X compliance (e.g., CFDI, DIOT), aligning with LATAM tax authority requirements. The Symfony bundle adds structured validation/normalization but introduces Symfony-specific dependencies, which may not be ideal for Laravel projects avoiding Symfony’s footprint.
• Laravel Compatibility: While the package is PHP 8.3+ and Symfony 7.1-compatible, Laravel’s integration with Symfony is limited to specific components (e.g., HttpFoundation, OptionsResolver). The risk is unnecessary coupling if the project doesn’t use Symfony elsewhere.
• Decoupling: The DTOs are designed to be decoupled from Greenter’s models, making them reusable for custom invoice generation logic in Laravel. However, the Symfony bundle’s ContractValidator/ContractNormalizer may tighten integration with Symfony’s DI container.

Integration Feasibility

• Symfony Dependencies:
  • Feasible: Only symfony/options-resolver and symfony/http-foundation are likely needed for validation/normalization.
  • Risk: Potential version conflicts with existing Symfony packages (e.g., symfony/console if used elsewhere).
• PHP 8.3 Requirement:
  • Feasible: Laravel 10+ supports PHP 8.3, but older Laravel versions (e.g., 9.x) would require upgrades.
  • Mitigation: Use platform-check or phpunit/phpunit to test compatibility before full adoption.
• Validation Coverage:
  • Partial: The package covers Factura-X schemas (e.g., ComprobanteRequestDto) but lacks profile-specific validators (e.g., BASIC vs. COMMUNICATION). Custom logic may still be needed.

Technical Risk

• Symfony Overhead:
  • Tradeoff: Gaining structured configuration (via OptionsResolver) at the cost of larger vendor size (~2–5MB) and potential DI complexity.
  • Impact: Minimal for most Laravel apps, but serverless/edge deployments may face size constraints.
• Breaking Changes:
  • Symfony 7.1: Backward-compatible with Symfony 6/7, but Laravel’s Symfony integration (e.g., symfony/mailer) could introduce edge cases.
  • PHP 8.3: New features (e.g., array_unpack in attributes) may break older Laravel helpers if misused.
• Validation Gaps:
  • Risk: Missing profile-specific validation (e.g., mandatory fields for PERSONA_MORAL vs. PERSONA_FISICA in Mexico’s CFDI). Requires custom extensions.

Key Questions

1. Symfony Scope:
   • Which Symfony components are actually used? Can they be mocked or replaced in Laravel (e.g., using illuminate/support)?
2. Dependency Conflicts:
   • Will this force upgrades to symfony/console, symfony/finder, etc.? How are version constraints managed?
3. Performance:
   • Does Symfony’s DI container add overhead for high-volume invoice generation (e.g., 1000+ invoices/hour)?
4. Laravel-Specific Tools:
   • Are there plans to add Laravel facades or queue job integrations (e.g., ShouldQueue for async invoice generation)?
5. Deprecation Policy:
   • How will PHP 8.1/8.2 support be handled in future releases? Will interfaces change to leverage PHP 8.3 features?
6. XML/PDF Generation:
   • Is there documentation or plans for integrating with libraries like dompdf or spatie/pdf-to-html for invoice rendering?

Integration Approach

Stack Fit

• Best For:
  • Laravel apps targeting LATAM markets (Mexico, Colombia, Peru) requiring Factura-X compliance.
  • Projects using PHP 8.3+ and Symfony 7.1 (or willing to upgrade).
• Less Ideal For:
  • Legacy Laravel (pre-10.x) or PHP 8.1/8.2 environments without upgrade paths.
  • Projects avoiding Symfony (e.g., minimalist Laravel apps or those using spatie/laravel-* packages with conflicting Symfony versions).
• Complementary Packages:
  • spatie/laravel-data: For structured invoice data (could integrate with Symfony’s OptionsResolver).
  • laravel-queues: For async invoice generation (mitigate Symfony DI overhead).
  • heynemann/laravel-facturae: For CFDI-specific XML generation (if this package lacks full Factura-X coverage).

Migration Path

1. Dependency Audit:
   • Run composer why symfony/* to identify conflicts. Resolve with explicit versions:

     composer require symfony/options-resolver:^7.1 symfony/http-foundation:^7.1
     

   • Upgrade Laravel to 10.x if on PHP 8.3 (or use platform-check to test compatibility).
2. Proof of Concept (PoC):
   • Implement a Symfony-aware invoice validator using ContractValidator:

     use CarlosChininin\FacturaxContracts\Service\ContractValidator;
     
     class InvoiceValidator {
         public function __construct(private ContractValidator $validator) {}
     
         public function validate(array $payload): bool {
             return $this->validator->validate(new ComprobanteRequestDto(), $payload);
         }
     }
     

   • Test with Factura-X validators (e.g., CFDI 3.3 schema) and benchmark against custom implementations.
3. Phased Rollout:
   • Phase 1: Replace custom XML validation with ContractValidator.
   • Phase 2: Integrate Symfony’s OptionsResolver for configurable invoice templates.
   • Phase 3: Extend to profile-specific validation (e.g., COMMUNICATION vs. BASIC in CFDI).

Compatibility

• PHP 8.3: Requires Laravel 10.x or a custom PHP 8.3 runtime (e.g., Bref, Laravel Vapor).
• Symfony 7.1:
  • Safe: If only using OptionsResolver/HttpFoundation, conflicts are unlikely.
  • Risky: If the package pulls in symfony/console or symfony/process, test for CLI command collisions.
• Database: No changes, but consider Symfony’s Doctrine integration if storing invoice metadata (though not part of this package).

Sequencing

1. Update Dependencies:

   composer require carloschininin/facturax-contracts:^0.0.2
   

2. Laravel Configuration:
   • Bind Symfony services in AppServiceProvider:

     $this->app->singleton(
         ContractValidator::class,
         fn() => new ContractValidator()
     );
     

3. Interface Implementation:
   • Create a Laravel-friendly facade for ContractValidator:

     facade(InvoiceValidator::class, InvoiceValidator::class);
     

4. Testing:
   • Validate against Factura-X schemas (e.g., CFDI 3.3, DIOT 2.1).
   • Test edge cases (e.g., missing mandatory fields, invalid profiles).
5. Deployment:
   • Roll out to non-production first, monitoring for Symfony DI overhead or validation failures.

Operational Impact

Maintenance

• Pros:
  • Reduced custom validation logic: The package handles Factura-X schema validation, reducing maintenance burden for tax-compliant invoices.
  • Versioned DTOs: Future-proofs against tax authority updates (e.g., CFDI 4.0) if the package evolves.
• Cons:
  • Symfony Dependency: Adds maintenance overhead for Symfony components (e.g., OptionsResolver updates).
  • Lack of Documentation: Limited examples for Laravel-specific integrations (e.g., queue jobs, API responses).
• Mitigation:
  • Isolate Symfony components in a dedicated service layer.
  • Document custom extensions (e.g., profile-specific validators).

Support

• Pros:
  • Community: While the package has low stars (1), the maintainer is active (releases in 2026).
  • Symfony Ecosystem: Leverages well-supported Symfony components (e.g., OptionsResolver).
• Cons:
  • Limited Adoption: Few dependents may mean slower issue resolution.