Laravel Mollie Billing Laravel Package

Technical Evaluation

Architecture Fit

• Monolithic vs. Modular: The package is highly opinionated but modular enough to integrate into Laravel’s ecosystem without forcing architectural changes. It leverages Laravel’s service container, contracts, and middleware, making it a good fit for SaaS platforms with subscription-based billing.
• Domain Alignment: Aligns well with multi-tenant SaaS architectures where billing is tied to an Organization (or similar) rather than a User. The Billable contract enforces a clean separation of concerns.
• Feature Parity: Covers 90%+ of SaaS billing needs (subscriptions, VAT/OSS, metered billing, coupons, trials, admin panels). Gaps may exist for highly customized billing logic (e.g., complex revenue recognition).

Integration Feasibility

• Laravel Compatibility: Designed for Laravel 12/13 with PHP 8.3+. Uses Laravel’s conventions (service providers, facades, middleware) but requires Livewire 4 and Flux Pro (commercial license).
• Dependency Risks:
  • Mollie SDK v4: Tight coupling with Mollie’s API; future SDK changes may require updates.
  • Livewire/Flux Pro: Adds frontend complexity. Flux Pro’s commercial license may be a blocker for open-source projects.
  • Wallet System (bavix/laravel-wallet): Requires schema migrations for uuid/ulid keys if not already in use.
• Database Schema: Publishes migrations for billing tables (subscriptions, wallets, coupons, etc.). Critical: billable_key_type and user_key_type must be set before migrations to avoid manual schema changes later.

Technical Risk

• High Initial Setup Complexity:
  • Configuration Overhead: Requires publishing config, migrations, views, and translations. Misconfiguration (e.g., wrong billable_key_type) can break migrations.
  • Flux Pro Dependency: Commercial license adds cost and vendor lock-in.
  • Livewire 4: If the app doesn’t use Livewire, the admin/customer portal becomes a blocker.
• Customization Challenges:
  • Blade/Livewire Views: Overriding views requires Tailwind CSS source scanning to avoid styling issues.
  • Business Logic Hooks: While the package provides callbacks (e.g., beforeCheckoutUsing), deep customization (e.g., modifying VAT logic) may require forking or extending core classes.
• Multi-Tenancy Risks:
  • Route Prefixing: Incorrect tenant route mounting can break portal URLs (e.g., missing organization:slug in URL::defaults).
  • Billable Resolution: If resolveBillableUsing fails, checkout or portal access may break silently.

Key Questions

1. License Compliance:
   • Is the Flux Pro commercial license acceptable for the project?
   • Does the team have experience with Livewire 4 and Flux Pro?
2. Schema Compatibility:
   • Are the app’s models already using uuid/ulid for primary keys? If not, can the team migrate existing data without downtime?
3. Customization Needs:
   • Does the package’s VAT/OSS logic align with the business’s compliance requirements?
   • Are there unsupported billing scenarios (e.g., deferred revenue, complex add-ons)?
4. Performance:
   • How will wallet-based metered billing scale with high transaction volumes?
   • Are there optimizations needed for the Livewire admin portal (e.g., pagination, lazy loading)?
5. Maintenance:
   • Who will monitor Mollie webhooks and handle failures (e.g., past_due states)?
   • Is there a rollback plan if Mollie’s API or the package breaks?

Integration Approach

Stack Fit

• Backend:
  • Laravel 12/13: Native fit with service providers, facades, and middleware.
  • PHP 8.3+: Required for typed properties and attributes used in the package.
  • Mollie SDK v4: Direct integration with Mollie’s API (subscriptions, mandates, webhooks).
• Frontend:
  • Livewire 4: Required for the customer portal and admin panel. If the app doesn’t use Livewire, this becomes a major integration hurdle.
  • Flux Pro: Powers the checkout flow and portal. Commercial license required.
  • Tailwind CSS: Views rely on Tailwind utilities; source scanning is mandatory to avoid purging.
• Database:
  • MySQL/PostgreSQL: Supports uuid/ulid keys (required for polymorphic relations).
  • Wallet System: Uses bavix/laravel-wallet for metered billing; schema migrations must align with billable_key_type.

Migration Path

1. Pre-Integration:
   • Audit Current Billing: Document existing subscriptions, coupons, VAT logic, and edge cases.
   • Schema Review: Ensure the app’s billable model (e.g., Organization) can accommodate uuid/ulid keys if needed.
   • Livewire/Flux Pro Setup: Install and configure Livewire 4 + Flux Pro (commercial license).
2. Configuration:
   • Publish and configure:

     php artisan vendor:publish --tag=mollie-billing-config
     php artisan vendor:publish --tag=mollie-billing-migrations
     php artisan vendor:publish --tag=mollie-billing-views
     php artisan vendor:publish --tag=billing-lang
     

   • Set billable_key_type and user_key_type before migrations.
3. Database:
   • Run migrations:

     php artisan migrate
     

   • Critical: If billable_key_type is changed later, manual schema alterations are required.
4. Backend Integration:
   • Implement the Billable contract on the target model (e.g., Organization).
   • Register callbacks in AppServiceProvider:

     MollieBilling::resolveBillableUsing(...);
     MollieBilling::createBillableUsing(...);
     MollieBilling::beforeCheckoutUsing(...);
     

   • Mount routes in routes/web.php with correct middleware.
5. Frontend Integration:
   • Ensure Vite entry points (app.css, app.js) are exposed.
   • Add Tailwind source scanning for vendor views:

     // vite.config.js
     content: [
       './resources/views/**/*.blade.php',
       './vendor/graystackit/laravel-mollie-billing/resources/views/**/*.blade.php',
     ],
     

   • Customize views if needed (publish and override).
6. Testing:
   • Validate config with:

     php artisan billing:check-config
     

   • Test checkout flow, portal access, and admin panel.
   • Simulate webhook failures and country mismatches.

Compatibility

• Laravel Ecosystem:
  • Works seamlessly with Laravel’s auth, middleware, and queues.
  • Event-driven: Emits events (e.g., CheckoutAbandoned, SubscriptionCreated) for custom logic.
• Third-Party Risks:
  • Mollie API Changes: The package wraps Mollie’s SDK, but breaking changes may require updates.
  • Livewire/Flux Pro: If the app uses an older Livewire version or a different UI framework, migration effort increases.
• Multi-Tenancy:
  • Tenant-Aware: Designed for tenant-based routing (e.g., /{tenant}/billing).
  • Fallback Logic: Handles cases where no tenant is resolved (e.g., during checkout).

Sequencing

1. Phase 1: Core Setup (2–3 weeks)
   • Configure package, run migrations, implement Billable contract.
   • Set up Mollie webhooks and test basic subscriptions.
2. Phase 2: Frontend Integration (1–2 weeks)
   • Customize Livewire views, integrate Tailwind, test checkout flow.
3. Phase 3: Advanced Features (2–4 weeks)
   • Implement VAT/OSS logic, wallets, coupons, and admin panel.
   • Test edge cases (country mismatches, refunds, scheduled changes).
4. Phase 4: Go-Live & Monitoring (Ongoing)
   • Monitor webhooks, handle failures, and iterate on customizations.

Operational Impact

Maintenance

• Vendor Updates:
  • Mollie SDK: Monitor for breaking changes; may require package updates.
  • Livewire/Flux Pro: Updates may break the portal if not tested.
• Configuration Drift:
  • Plans/Coupons: Changes to mollie-billing-plans.php require **config validation