Laravel Greenter Laravel Package

Technical Evaluation

Architecture Fit

• Domain Alignment: The package remains tailored for Peruvian electronic invoicing (Facturación Electrónica) under SUNAT regulations — a highly specialized fit for businesses operating in Peru or requiring SUNAT compliance. It abstracts XML schema generation, digital signing (via SunatOCSP or SunatPKCS12), and SUNAT API interactions, reducing custom development effort.
• Laravel Synergy: Leverages Laravel's service providers, facades, and event system. Follows Laravel conventions (config files, service container bindings), minimizing architectural friction.
• Framework Currency (New in v2.0.1): Declared Laravel 13 compatibility materially improves architectural fit for teams on — or planning to move to — the current Laravel release train. This removes a previous blocker where the package would have pinned the host application to an older framework major.
• Modularity: Still designed as a standalone module, allowing incremental adoption (e.g., start with XML generation before enabling API calls).

Integration Feasibility

• Core Features (unchanged in this release):
  • XML Schema Compliance: Generates SUNAT-compliant XML for invoices, credit notes, and other documents (CFDI).
  • Digital Signing: Supports PKCS12 and OCSP signing methods (critical for SUNAT validation).
  • SUNAT API Integration: Handles consultas, envío de comprobantes, and recepción de respuestas via SUNAT's SOAP/WSDL endpoints.
  • Web Services: Endpoints for real-time validation (accepted/rejected status checks).
• Dependencies:
  • PHP 8.0+ historically; Laravel 13 compatibility implies a higher floor (likely PHP 8.3+) — confirm in composer.json before committing to an upgrade.
  • OpenSSL (PKCS12 signing), Guzzle HTTP, SimpleXMLElement.
  • No heavy database schema changes; configuration lives in config/greenter.php.
• Version Signal: The 2.x line plus a Laravel 13 compatibility note suggests a possible support-matrix reset (older Laravel majors may have been dropped). This is the single most important thing to verify before adopting.

Technical Risk

Key Questions

1. Upgrade Scope:
   • Does the business need Laravel 13 now, or is this an opportunistic upgrade? What is the current Laravel version in production?
   • Did v2.x drop support for the Laravel major currently in production? If so, is a framework upgrade a prerequisite?
2. Compliance Scope:
   • Does the business require only invoices (Factura Electrónica) or also credit notes (Nota de Crédito), perception vouchers, etc.?
   • Are there custom document types (e.g., light invoices for S/ 1500 or less)?
3. Signing Method:
   • PKCS12 (recommended by SUNAT) or OCSP? Are the necessary digital certificates in place?
4. Testing Strategy:
   • Is SUNAT's sandbox environment available for pre-go-live testing?
   • Do we have automated tests (PHPUnit) validating XML generation and API responses, and do they pass on Laravel 13?
5. Error Handling & Audit:
   • How are SUNAT rejections surfaced to end users? Automated retries or manual review?
   • Do we need to log all SUNAT interactions, and do 10+ year retention policies apply?

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Service Providers: Registers as a Laravel service provider; supports dependency injection (e.g., Greenter\GreenterFacade::invoice()).
  • Config Files: Centralized (config/greenter.php) for SUNAT credentials, endpoints, and signing methods.
  • Events: Emits events (e.g., InvoiceGenerated, SunatResponseReceived) for custom logic (notifications, analytics).
• PHP Extensions: OpenSSL (php-openssl) for PKCS12 signing; DOM/SimpleXML (php-xml) for XML parsing.
• Database: No mandatory tables. Recommended optional tables:
  • Document metadata (sunat_document_id, status).
  • Certificate rotations (expiry dates).
  • Implement via Laravel Migrations.
• Runtime Baseline: Confirm the PHP floor implied by Laravel 13 support before sizing infrastructure work.

Migration Path

Compatibility

• Laravel Versions: Laravel 13 is now declared compatible (v2.0.1). For projects on Laravel 8–12, confirm the supported range in composer.json — a major-version line change may mean older majors are no longer maintained. Maintain an explicit version pin and upgrade deliberately.
• PHP Versions: Verify the composer platform requirement; Laravel 13 compatibility likely raises the floor. Avoid legacy PHP 7.x.
• SUNAT Schema Versions: The package may lag SUNAT's latest schema. Plan periodic reviews (e.g., quarterly).
• Third-Party Tools:
  • Digital Certificates: Ensure SUNAT-compatible PKCS12.
  • PDF Generation: Not provided; integrate Laravel Snappy or DomPDF if needed.

Sequencing

1. Framework Decision First (New):
   • Decide explicitly: (a) upgrade the application to Laravel 13 and adopt the 2.x line, or (b) stay on the current Laravel major and pin to a compatible package version. Do not let the package dictate the framework timeline.
2. Core Integration:
   • Start with invoice generation and local XML validation; then enable SUNAT API calls in sandbox.
3. Extended Features:
   • Add webhooks for SUNAT responses; implement automated retries for failed submissions.
4. Customization:
   • Extend XML templates for non-standard document types; add custom fields via accessors/mutators.

Operational Impact

Maintenance

• Package Updates:
  • Monitor GitHub releases and SUNAT announcements for schema/API changes. The v2.0.1 release confirms the maintainer is actively tracking modern Laravel, which is a positive maintenance signal.
  • Fork the package if upstream updates lag SUNAT changes.
• Framework Upgrade Cadence:
  • Laravel 13 compatibility means the package can ride the standard annual Laravel cadence. Budget a recurring (annual) integration checkpoint rather than ad-hoc upgrades.
• Certificate Management:
  • SUNAT certificates expire (~1 year). Automate renewal alerts (Laravel scheduler). Store certificates securely (encrypted config or a secrets manager).
• Configuration Drift:
  • Use Laravel Envoy or Ansible to sync config/greenter.php across environments.

Support

• Troubleshooting:
  • XML Validation Errors: Use SUNAT's validation tool to debug.
  • Signing Failures: Verify PKCS12 password and OpenSSL compatibility.
  • API Timeouts: SUNAT's SOAP endpoint may throttle; implement rate limiting.
• Logging: Log raw SUNAT responses (XML/JSON) for audits. Use a dedicated channel with retention aligned to the 10+ year document retention requirement; redact certificate material and secrets.
• Escalation: Because the package is community-maintained, define an internal owner and a fork/patch path for SUNAT-breaking changes.

Scaling

• Throughput: Decouple document generation from SUNAT submission via queues (Horizon/Redis). SUNAT latency, not application CPU, is the practical ceiling.
• Concurrency: Apply rate limiting and backoff per SUNAT endpoint; shard queues by document type if volume grows.
• Data Growth: Document metadata and audit logs grow monotonically — plan archival/partitioning early given multi-year retention.

Failure Modes

Ramp-Up

• Engineering: Low-to-moderate. Laravel conventions mean a mid-level Laravel engineer can integrate XML generation quickly; signing and SUNAT protocol semantics require dedicated study (est. 1–2 sprints to first sandbox-accepted document).
• Compliance/Finance: Requires familiarization with SUNAT rejection codes and document retention obligations — involve them during sandbox testing, not after go-live.
• Training: Build a short internal runbook covering certificate rotation, rejection triage, and the fork/patch escalation path.
• Timeline Impact of v2.0.1: Neutral-to-positive. The Laravel 13 declaration removes a future upgrade blocker but introduces a verification task (confirm the supported Laravel/PHP matrix and any breaking changes in the 2.x line) before it can be booked as a win.