The Problem
Hosting providers and SaaS operators need a low‑cost way to generate invoices, track client activity, and integrate with payment gateways. Commercial billing platforms are expensive, lock‑in, and often include features that are never used. The gap is an open‑source stack that can be self‑hosted, extended, and run on a standard LAMP/LEMP environment.
What This Does
FOSSBilling delivers a PHP‑based billing engine with a web UI, client portal, and a plug‑in architecture for payment gateways. Core code lives under src/ – e.g., src/library/Box/App.php implements the main application class and src/library/Model/Invoice.php defines the invoice entity. The UI assets are stored in src/data/assets/ and rendered through Twig templates in src/install/assets/. Docker support is provided via Dockerfile and the ddev folder, allowing a reproducible development stack.
How To Use It
Setup
Clone the repo git clone https://github.com/FOSSBilling/FOSSBilling.git cd FOSSBilling
Install PHP dependencies
composer install
Install front‑end tooling (optional, for custom UI builds)
cd frontend-build-utils && npm ci && cd ..
Copy sample config and adjust DB credentials
cp src/config-sample.php src/config.php edit src/config.php to match your environment
Database
Run the installation script which creates tables from src/install/sql/structure.sql and seeds data from src/install/sql/content.sql: php src/install/install.php
(You may need to point a web browser at http://localhost/src/install/ if the CLI installer is not used.)
Running
The web entry point is src/index.php. In a typical LAMP stack you point the document root to the src/ directory. When using Docker/DDEV: ddev start Application will be reachable at https://fossbilling.ddev.site
Configuration
All runtime settings live in src/config.php (generated from config-sample.php). Payment gateways are added by placing images in src/data/assets/gateways/ and configuring them through the admin UI; the code that reads these definitions is in src/library/Api/Handler.php.
Real‑World Use
A small hosting company can deploy this on a single VPS, connect it to an existing MySQL database, and enable PayPal and Stripe gateways. After installing, the staff creates product templates (src/library/Model/Product.php), assigns them to clients, and the system automatically sends invoices via the src/library/FOSSBilling/Mail.php class. Billing cycles are driven by the cron script src/cron.php, which can be scheduled with a standard system cron entry.
Code Health & Issues
Low – Limited test coverage – Only one test file is present despite phpunit.xml and CI configuration. Medium – Beta status – README warns of “rough edges” and limited support; production use may encounter undocumented bugs. Low – Mixed language stack – Front‑end tooling (frontend-build-utils/package.json) is separate from the PHP core; building custom UI requires extra steps not documented in the main README. Low – Hard‑coded paths – Several scripts (e.g., src/install/install.php) assume the document root is src/; moving the code may require manual path adjustments. Low – No secret management – Database credentials are stored in plain PHP config; no example of .env usage, increasing risk if the file is inadvertently committed.
Positive signals: Composer lockfile present, GitHub Actions for CI (codeQL, rector, release builds), and a LICENSE (Apache‑2.0). The repository follows PSR‑4 style autoloading and separates concerns via the library/ namespace.
The Bottom Line
FOSSBilling provides a functional, extensible billing platform that can be deployed quickly on a standard PHP stack, making it suitable for small‑to‑mid‑size hosting operations that need cost‑effective automation. The codebase is reasonably organized but suffers from minimal automated testing and a beta‑level maturity, so teams should budget time for validation and possible custom patches before relying on it for critical revenue processes.