FOSSBilling

FOSSBilling is a self‑hosted, PHP‑based billing and client management system that targets web hosting businesses but is flexible enough for any online service. At its core, the application orchestrates invoice generation, payment processing, client communication, and service provisioning through a modular architecture that can be extended via plugins or custom code. The platform is released under the Apache 2.0 license, ensuring that developers can freely modify, distribute, or embed it into larger ecosystems without licensing constraints.

Technical Stack & Architecture

• Language & Framework: Pure PHP (≥ 7.4) with a lightweight MVC pattern; the codebase is organized into controllers, models, and views without a heavy framework dependency. This keeps the footprint small and makes it easy to drop into existing PHP stacks.
• Database: MySQL/MariaDB is the only required persistence layer. The schema is fully relational and exposed through an ORM‑like Db::query() interface, enabling developers to write custom SQL or extend the data model with minimal friction.
• Dependency Management: Composer is used for third‑party libraries (e.g., payment gateway SDKs, email clients). The composer.json file lists all runtime dependencies, allowing developers to update or replace libraries without touching the core code.
• Template Engine: Twig is employed for rendering admin and client pages, giving developers a clear separation between business logic and presentation. Twig’s extensibility (filters, functions) is leveraged for custom UI components.

The application follows a plugin‑centric architecture: core functionality resides in the modules folder, while optional features are packaged as installable plugins. Each plugin declares a manifest (module.xml) that specifies routes, database migrations, and hooks into the core event system. This design enables developers to add new payment gateways, integrate with external APIs (e.g., cPanel, Plesk), or expose custom REST endpoints without modifying the core.

Core Capabilities & APIs

• RESTful API: A built‑in JSON API exposes CRUD operations for clients, invoices, services, and payments. Authentication is token‑based (API key + secret), allowing secure integration with external billing or provisioning systems.
• Webhooks: The system can emit events (e.g., invoice.created, payment.received) to external URLs. Developers can consume these hooks to trigger downstream processes such as provisioning or analytics.
• Event System: A publish/subscribe mechanism (Events::trigger()) lets plugins listen to lifecycle events (e.g., client.registered, service.suspended). This is ideal for extending business logic or integrating with third‑party services.
• Payment Gateways: The core supports multiple gateways (Stripe, PayPal, Mollie, etc.) via a unified interface (GatewayInterface). Adding a new gateway is as simple as implementing the interface and registering it in the plugin manifest.
• Client Portal: A self‑service portal exposes API endpoints for clients to view invoices, make payments, and manage services. The portal is built with the same Twig templates, ensuring a consistent look‑and‑feel.

Deployment & Infrastructure

• Self‑Hosting Requirements: Apache/Nginx with PHP ≥ 7.4, MySQL/MariaDB, and optional Redis for caching (improves API response times). No proprietary dependencies mean it runs on any LAMP/LEMP stack.
• Containerization: Official Docker images are available, simplifying CI/CD pipelines. The docker-compose.yml ships with a ready‑to‑run stack (web server, PHP-FPM, MySQL) and can be extended with custom services.
• Scalability: While designed for small to medium businesses, the architecture supports horizontal scaling by separating the web tier from the database. Load balancers can route API traffic to multiple PHP instances, with a shared MySQL cluster or read replicas for high availability.
• Backups & Migrations: Database migrations are managed through the core’s CLI (php bin/console db:migrate). Developers can script backups or integrate with cloud storage services via plugins.

Integration & Extensibility

• Plugin System: Plugins are discovered automatically; developers can ship them as Composer packages or zip archives. The manifest declares routes, database migrations, and event listeners.
• Custom Routes & Controllers: By adding a controller file under modules/<name>/controllers/, developers can expose new URLs that integrate with the core authentication and permission system.
• Theme Customization: The admin panel’s Twig templates can be overridden by copying them into a themes/<name>/ directory. This allows branding without touching core files.
• Webhook Handlers: Implementing a webhook listener is straightforward—create an endpoint that validates the signature and processes the payload. The core’s Webhook class can be extended to support new providers.

Developer Experience

• Documentation: The project hosts a comprehensive docs site (docs.fossbilling.org) covering installation, API reference, plugin development guides, and migration procedures. The API docs include example payloads and error codes.
• Community & Support: An active Discord channel, issue tracker, and contributor guidelines provide quick help. The codebase follows a clear commit message style, making it easier to review pull requests.
• Testing: CI pipelines run PHPUnit tests across all modules, ensuring that new code does not break core functionality. Developers can add their own tests following the same structure.
• Licensing: Apache 2.0 allows commercial use, modification, and redistribution without copyleft obligations—ideal for proprietary SaaS platforms that want to embed billing.

Use Cases

|