Download the PHP package digitaldev-lx/laravel-moloni without Composer

Laravel Moloni

A Laravel package for integrating with the Moloni invoicing API. Provides a clean, fluent interface to manage companies, customers, products, invoices, and all other Moloni resources with full type safety through DTOs and enums.

Official page: digitaldev.pt/packages/laravel-moloni

Requirements

• PHP 8.4+
• Laravel 12 or 13

Installation

Install the package via Composer:

Publish the configuration file:

Run the migrations (required for OAuth token storage):

Configuration

Add the following environment variables to your .env file:

You can obtain your API credentials from the Moloni Developer Portal.

Sandbox

Moloni provides a sandbox environment for testing API integrations without affecting production data. The sandbox is available at https://api.moloni.pt/sandbox/ and exposes the same endpoints as production.

Getting sandbox credentials

1. You need an active Moloni account. If your login does not yet have access to the demonstration company, request it from [email protected] indicating the email associated with your login.
2. The OAuth2 client_id / client_secret are the same as in production. Only the base_url changes.
3. Optionally, explore the API interactively at the Moloni API Explorer.

Switching environments

Set MOLONI_BASE_URL in your .env:

Important: token persistence between environments

OAuth2 tokens are stored in the moloni_tokens table and are not scoped per environment. When you switch MOLONI_BASE_URL, the existing token is no longer valid for the new host and the package will silently re-authenticate on the next call. To force a clean state, truncate the table:

A common pattern is to use a separate database for local/testing (already the default with SQLite) so production tokens are never reused against the sandbox host.

Usage

Using the Facade

All API interactions are available through the Moloni facade:

Companies

Customers

Products

Invoices

Other Document Types

The package supports all Moloni document types through dedicated resources:

• Moloni::receipts() - Receipts
• Moloni::creditNotes() - Credit Notes
• Moloni::debitNotes() - Debit Notes
• Moloni::simplifiedInvoices() - Simplified Invoices
• Moloni::invoiceReceipts() - Invoice Receipts
• Moloni::deliveryNotes() - Delivery Notes
• Moloni::billsOfLading() - Bills of Lading
• Moloni::waybills() - Waybills
• Moloni::estimates() - Estimates
• Moloni::purchaseOrders() - Purchase Orders
• Moloni::internalDocuments() - Internal Documents
• Moloni::paymentReturns() - Payment Returns
• Moloni::ownAssetsMovementGuides() - Own Asset Movement Guides
• Moloni::customerReturnNotes() - Customer Return Notes
• Moloni::globalGuides() - Global Guides
• Moloni::supplierInvoices() - Supplier Invoices
• Moloni::supplierPurchaseOrders() - Supplier Purchase Orders
• Moloni::supplierSimplifiedInvoices() - Supplier Simplified Invoices
• Moloni::supplierCreditNotes() - Supplier Credit Notes
• Moloni::supplierDebitNotes() - Supplier Debit Notes
• Moloni::supplierReturnNotes() - Supplier Return Notes
• Moloni::supplierReceipts() - Supplier Receipts
• Moloni::supplierWarrantyRequests() - Supplier Warranty Requests
• Moloni::documents() - Generic Documents

Settings Resources

Access configuration resources for taxes, payment methods, document sets, and more:

Using DTOs

The package provides readonly Data Transfer Objects for type-safe data handling:

• Customer - Customer data
• Supplier - Supplier data
• Salesman - Salesman data
• Product - Product data
• ProductStock - Stock movement data
• Document - Document header data
• DocumentProduct - Document line item data
• Payment - Payment data
• Address - Address data
• Tax - Tax data
• Vehicle - Vehicle data
• Deduction - Withholding tax data
• PriceClass - Price class data

All DTOs are located in the DigitaldevLx\LaravelMoloni\DataTransferObjects namespace.

Using Events

The package dispatches events for all mutation operations:

DocumentCreated, DocumentUpdated and DocumentDeleted carry both the API response and a documentType string (e.g. 'invoices', 'creditNotes') so a single listener can route by document type.

All events are located in the DigitaldevLx\LaravelMoloni\Events namespace.

Auto-discovery (recommended)

Create a listener class in your app/Listeners directory. Laravel automatically discovers and registers listeners based on the type-hint in the handle method:

Manual registration

Register listeners manually in your AppServiceProvider:

Closure listeners

Error Handling

The package provides granular exception handling that maps directly to Moloni's error system.

Exception Types

All exceptions extend MoloniException, so you can catch them all with a single catch block or handle each type individually.

Authentication Errors

Available AuthError enum values: InvalidClient, InvalidUri, RedirectUriMismatch, InvalidRequest, UnsupportedGrantType, UnauthorizedClient, InvalidGrant, InvalidScope.

Validation Errors

Validation error codes (mapped via ValidationErrorCode enum):

Catching All Errors

HasMoloniDocuments Trait

Add the HasMoloniDocuments trait to any Eloquent model to associate it with Moloni documents:

Available Resources

Account & Profile

Company

Entities

Products

Documents

Settings

Global Data

Testing

Run the package test suite with Pest:

When testing your own application against the Moloni API, prefer Http::fake() so no real requests leave your machine. The host you fake should match MOLONI_BASE_URL exactly:

For an end-to-end example see tests/Unit/MoloniClientTest.php.

Troubleshooting

Static Analysis

Code Style

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

License

The MIT License (MIT). Please see License File for more information.

Credits

• DigitalDev LX