The Problem

Hosting providers and SaaS operators need a low‑cost way to generate invoices, collect payments, and keep client data organized. Existing commercial platforms are expensive, lock‑in customers, and often hide the underlying logic, making custom billing rules hard to implement.

What This Does

FOSSBilling is a PHP‑based billing suite that runs on a standard LAMP/LEMP stack. The core lives under src/, with most business logic in src/library/FOSSBilling/ (e.g., Module.php, UpdatePatcher.php, Payment/Adapter/Stripe.php). UI assets for the admin theme are in src/themes/admin_default/. The package manager files (composer.json, package.json) pull in Laravel‑style helpers, React for the front‑end, and Docker for reproducible builds.

Key files:

  • src/index.php – HTTP entry point, boots the DI container (src/di.php) and dispatches to Box\AppAdmin or Box\AppClient.
  • src/console.php – CLI bootstrap used by src/cron.php and developer tools.
  • src/library/FOSSBilling/ExtensionManager.php – loads extensions from src/extensions/ (not listed but part of the architecture).

How It Is Wired

Execution starts in src/index.php. It:

  1. Loads Composer autoloader.
  2. Includes src/di.php, which creates a service container (Box\App) wiring database (Box\Database), Twig (Box\TwigLoader), and logger (Box\Log).
  3. Calls Box\App::run(). The run method resolves the request URI, selects the appropriate controller from src/library/Box/, and renders a Twig template (e.g., src/install/assets/install.html.twig for the installer).

For background jobs, src/cron.php boots the same container and invokes scheduled services defined in src/library/Box/.

Payment processing follows a thin adapter pattern: a request hits src/library/Payment/Adapter/Stripe.php (one of the high‑cognitive‑load files) which calls Stripe’s SDK and returns a result to the calling service in src/modules/Invoice/Service.php.

The internal import graph shows 21 modules with 8 import edges and no cycles. The most connected assets are the admin theme JS bundles (src/themes/admin_default/assets/js/*), each imported by a single parent and importing few helpers, giving them low instability.

The widest blast‑radius modules are src/library/FOSSBilling/Module.php and src/library/FOSSBilling/UpdatePatcher.php; both are deep‑nested (max indentation 8) and referenced by many services, so changes there ripple widely.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/FOSSBilling.git
cd FOSSBilling

# Build the Docker dev environment (uses .ddev)
docker compose -f .ddev/docker-compose.phpmyadmin.yaml up -d

# Install PHP dependencies
composer install

# Install front‑end tooling
npm ci   # reads package-lock.json

# Create a database and copy sample config
cp src/config-sample.php src/config.php
# Edit src/config.php with your DB credentials

# Run the installer via web server (http://localhost)
# or via CLI for a quick test
php src/install.php

The web server entry point is src/index.php; the CLI entry point is src/console.php. Environment variables are not required beyond the DB credentials in src/config.php. Extensions are dropped into src/extensions/ and auto‑loaded by ExtensionManager.php.

Real‑World Use

A hosting reseller can point their Nginx virtual host at src/index.php, configure the MySQL DB, and enable the Stripe gateway. When a client signs up, the request flows through Box\AppClient, creates a Client model (src/library/Model/Client.php), generates an Invoice (src/library/Model/Invoice.php), and finally calls Payment/Adapter/Stripe.php to capture payment. All actions are logged via Box\Log.

Code Health & Issues

  • HIGH – Pin third‑party GitHub Actions to commit SHA (.github/workflows/*).
  • MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/live-tests.yml).
  • MEDIUM – Add a dependency‑vulnerability scan in CI.
  • MEDIUM – Move large GeoIP binaries to Git LFS (src/library/FOSSBilling/GeoIP/Databases/*.mmdb).
  • MEDIUM – Set persist-credentials: false on checkout (.github/workflows/live-tests.yml).
  • MEDIUM – Run container as non‑root (Dockerfile).
  • LOW – Define timeout-minutes for workflow jobs (.github/workflows/ci.yml).

Static analysis also reported:

  • HIGH – Deep nesting in Module.php, UpdatePatcher.php, Adapter/Stripe.php.
  • HIGH – Repeated 6‑line code blocks across dozens of files (e.g., console.php, Autoloader.php).
  • HIGH – Oversized service files (Invoice/Service.php, Support/Service.php).
  • MEDIUM – Empty catch {} blocks in theme build scripts.

The repo includes a full test suite (tests/, tests-legacy/), CI via GitHub Actions, a Dockerfile, and an Apache‑compatible license (Apache 2.0). No secrets were found in history.

The Bottom Line

FOSSBilling provides a functional, extensible billing engine with a clear PHP entry point and Docker‑ready dev setup. Code quality suffers from deep nesting, duplicated snippets, and oversized modules, which raise maintenance risk. It is suitable for teams comfortable with PHP/Laravel‑style codebases that can allocate effort to refactor the high‑complexity areas.