Liberu Billing

Modular Laravel billing platform for subscriptions, invoicing, payments, provisioning, and revenue operations.

Software · Hosting · Services · Liberu Group

Liberu Billing Laravel is the deployable Billing host for the Liberu Composer ecosystem. It combines independently released billing capabilities, presentation adapters, and foundation packages while keeping application bootstrapping, environment configuration, panel composition, and cross-package tests in one place.

Billing features

• Product catalogues, pricing plans, quotes, carts, checkout, agreements, and order workflows
• Subscription lifecycle management, usage metering, recurring billing, and plan changes
• Invoices, payment collection, payment methods, mandates, capture, allocation, refunds, disputes, and reconciliation
• Tax profiles, exemptions, threshold rates, currency conversion, billing terms, and account settings
• Customer portal, communications, domains, hosting, service provisioning, and ISP workflows
• Stripe and Paddle payment adapters plus Sanctum-protected API resources for billing capabilities
• Reporting, exports, notifications, audit trails, feature flags, and operational observability
• Filament and Livewire presentation adapters assembled from independently versioned modules

Requirements

Dependency	Supported version
PHP	8.5
Laravel	13.x
Filament	5.x
Livewire	4.x
Composer	2.x
Node.js	Latest stable release
Database	A Laravel-supported SQL database

Quick start

git clone https://github.com/liberusoftware/billing-laravel.git
cd billing-laravel
composer install
cp .env.example .env
php artisan key:generate
npm install
npm run build
php artisan migrate
php artisan serve

Review .env before migrating. Use php artisan migrate --seed only when example data is wanted. The optional interactive install.sh supports local, Docker, and Kubernetes-oriented setup.

Composable package architecture

Each runtime capability is an independent liberu-module Composer package with its own GitHub repository, release lifecycle, manifest, provider, documentation, and tests. Each visual package is an independent liberu-theme. Shared contract packages and the custom installer are normal Composer dependencies under /vendor.

Application composition
├── modules/       # Composer-installed module releases, tracked in Git
├── themes/        # Composer-installed theme releases, tracked in Git
├── app/           # Host-only composition and integration
├── config/        # Enabled modules and application policy
└── tests/         # Cross-package and application tests

Composer is the source of installation and version truth:

# Update all dependencies, including modules and themes
composer update --with-all-dependencies

# Update one capability from its tagged GitHub repository
composer update liberusoftware/search --with-dependencies

The trusted liberusoftware/composer-installer places packages according to type:

Composer type	Install path	Repository convention
liberu-module	/modules/{installer-name}	liberusoftware/module-{installer-name}
liberu-theme	/themes/{installer-name}	liberusoftware/theme-{installer-name}
Contract/library	/vendor	Package-specific repository

modules/ and themes/ are intentionally kept out of .gitignore. Their reproduced contents are committed so deployments and reviews can see the exact installed code, while composer.lock pins each release and source commit. Do not edit an installed module only in this host: contribute the generic change to its package repository, release it, and update the Composer dependency here.

Installation, runtime enablement, authorisation, and commercial entitlement are separate concerns. config/modules.php selects the enabled capability graph; the module manager validates dependencies and orders providers without scanning application classes manually.

Every module also publishes a validated feature catalog in module.json. Hosts can inspect the complete catalog or search it without loading module internals:

php artisan module:features
php artisan module:features health
php artisan module:status search

Module and theme development

A module owns one cohesive capability and communicates through public contracts, actions, events, registries, or stable identifiers. Domain modules do not depend on Filament or themes; optional *-filament, *-api, and *-livewire packages provide presentation adapters.

Every module contains:

composer.json
module.json
README.md
LICENSE.md
CHANGELOG.md
src/
database/ or resources/ when required
tests/

Themes contain composer.json, theme.json, source assets, compatibility metadata, accessibility/fallback expectations, tests, documentation, and asset licensing information. See the module development guide and theme architecture.

Testing and quality

composer validate --strict
vendor/bin/pest
vendor/bin/pint --test
npm run build

The test suite exercises application behaviour and every installed module provider. Package architecture tests verify metadata, declared dependencies, host isolation, UI boundaries, and Composer ownership.

Coverage

Coverage is measured with Xdebug over the configured release scope and must be green before branch promotion:

XDEBUG_MODE=coverage php -d memory_limit=1G vendor/bin/pest --coverage --min=100 --coverage-clover=coverage.xml

Each independently released package owns its own source scope and coverage gate. The current refactor is still in progress: the latest host unit run passed 844 tests with 3 skipped and measured 46.5% line coverage. The full host scope is not yet a passing 100% result. A failing coverage run blocks release and promotion.

Publishing the component repositories

The publishing helper derives repository names from directory names, using module- for entries in modules/ and theme- for entries in themes/. It also handles this complete meta repository as billing-laravel.

# Inspect all mappings without changing GitHub
scripts/publish-components

# Create any missing public repositories in the organisation
scripts/publish-components --create

# After committing the complete worktree, split and push every component plus the meta repository
scripts/publish-components --push

Publishing requires authenticated gh and git access to the organisation. Push mode deliberately refuses a dirty worktree because subtree splits can only publish committed content. Existing repositories are updated without force, so non-fast-forward histories must be reconciled explicitly rather than overwritten.

After the repositories are public, register every Composer package on Packagist:

# Verify all package-to-repository mappings without submitting
php scripts/submit-packagist.php --dry-run

# Obtain the MAIN API token from packagist.org/profile, then bulk register the packages
export PACKAGIST_USERNAME='your-packagist-username'
export PACKAGIST_API_TOKEN='your-packagist-api-token'
php scripts/submit-packagist.php
unset PACKAGIST_API_TOKEN

The submitter skips packages that are already registered and reports individual API failures without printing the configured token.

Documentation

• Billing architecture
• Module development
• Foundation compliance
• Foundation module matrix
• Theme architecture
• Theme system
• Messaging architecture
• Search architecture
• Localisation
• Notifications

Related Liberu projects

Project	Repository	Scope
Accounting	liberusoftware/accounting-erp-laravel	Ledgers, banking, tax, expenses, close, and reporting
Automation	liberusoftware/automation-laravel	Governed workflows, provider-neutral AI, approvals, and connectors
Billing	liberusoftware/billing-laravel	Billing, subscriptions, payments, invoices, and revenue operations
Boilerplate	liberusoftware/boilerplate-laravel	Modular Laravel foundation and reference implementation
Browser game	liberusoftware/browser-game-laravel	Browser-based game platform and domain capabilities
CMS	liberusoftware/cms-laravel	Content, publishing, pages, media, search, and delivery
Control panel	liberusoftware/control-panel-laravel	Hosting, infrastructure, DNS, mail, backups, and operations
CRM	liberusoftware/crm-laravel	Customers, leads, opportunities, sales, and service
Ecommerce	liberusoftware/ecommerce-laravel	Catalogues, checkout, orders, fulfilment, and returns
Genealogy	liberusoftware/genealogy-laravel	Genealogy records, relationships, sources, and research
Maintenance	liberusoftware/maintenance-laravel	Maintenance planning, assets, work orders, and operations
Real estate	liberusoftware/real-estate-laravel	Property, listing, tenancy, and transaction workflows
Social network	liberusoftware/social-network-laravel	Social profiles, groups, content, messaging, and discovery

Security

Do not report security vulnerabilities through public GitHub issues. Email security@liberusoftware.com with reproduction details and the affected version so the report can be handled privately.

License

This project is open-source software available under the MIT License. The linked licence text is authoritative; this summary is not legal advice.

Feedback and contributing

Feedback and contributions are welcome. Report reproducible bugs, propose focused enhancements, improve documentation or translations, and submit tested changes. Search existing issues first. Pull requests should explain the problem and approach, remain focused, pass the required checks, and document user-visible or breaking changes. Security reports must follow the private route above.

Contributors

Thank you to everyone who helps improve Liberu. View the contributors graph.

Automatic module and theme publishing

.github/workflows/sync-packages.yml publishes packages changed under modules/ or themes/ on pushes to main. A manual run reconciles all tracked packages. Each package needs a composer.json with a liberusoftware/* name. Files are copied from Git into the root of liberusoftware/module-<directory> or liberusoftware/theme-<directory>. Where .liberu-meta.json defines a repositoryPrefix, that design is authoritative (for example, modules/module-manager becomes module-module-manager). Without a configured prefix, an existing module- or theme- directory prefix is kept. Destination history is preserved, deleted files are removed, and unchanged packages do not receive another commit or release. Removing an entire package leaves its public repository intact. This workflow makes tracked package edits publishable; install checks still require the project's Composer dependencies to resolve to those published package contents.

Configure these secrets in the packagist GitHub environment (or as repository or organization secrets available to this repository):

• MODULE_SYNC_TOKEN: organization-authorized GitHub token able to create public repositories and read/write package contents and releases across the target repositories. Because package snapshots include .github/workflows, allow workflow writes too. A classic PAT needs repo and workflow scopes and an organization role permitted to create repositories. The default GITHUB_TOKEN cannot publish across these repositories.
• PACKAGIST_USERNAME: Packagist account that owns or maintains these packages.
• PACKAGIST_API_TOKEN: that account's main API token, required to submit new packages as well as update existing packages.

New packages start at their declared stable Composer version, or v1.0.0. Existing packages use the highest stable repository tag: a higher declared Composer version wins, BREAKING CHANGE: or type!: commits bump major, feat: commits bump minor, and other changes bump patch. Only commits touching the package since the last successful sync affect this decision. The first automated run and manual runs reconcile all packages, so canceled or failed runs cannot silently drop package changes. Tags and commits are pushed atomically, then a GitHub release is created and the package is submitted to or refreshed on Packagist. Rerunning a failed job completes publication without issuing another release for the same contents. Concurrent pushes from other projects are rejected instead of force-pushed; rerun the failed job.

The source project and its lockfile are not rewritten by publication. Different projects publishing the same directory name share a destination repository; coordinate their package contents. Run the publisher's local tests with python3 -m unittest discover -s .github/scripts -p 'test_sync_packages.py'.