FOSSBilling File Structure

FOSSBilling’s file structure may feel unfamiliar to new developers since it is not based on a modern framework. This guide is here to help you quickly get comfortable with how everything is organized so you can jump right into it.

The Main Source Code

The source code for FOSSBilling lives in the “src” directory within the project repository.

You’ll find almost all of the project’s code here, except for tests and a few other files. This guide will primarily focus on the source code found in the “src” directory.

Data

File path: /src/data

The “data” folder within the source code is mostly empty, but it is an important directory for a live installation of FOSSBilling. This is where cache, logs, and uploads will be stored.

Install

File path: /src/install

The “install” directory contains the files necessary for installing FOSSBilling, such as the installation wizard and default SQL content.

The install folder is automatically removed once the installation is complete. If you plan to contribute changes to the installer, set APP_ENV to dev to keep the folder from being deleted.

Library

File path: /src/library

The “library” directory serves as a general-purpose library for FOSSBilling. It contains several subfolders, each holding different resources and core code. In the following section, we will describe the contents of these subfolders.

API

File path: /src/library/Api

The “API” folder contains some of the core files for the FOSSBilling API, including the abstract class, handler, and the JavaScript API wrapper.

The most commonly used file here is the JavaScript wrapper at src/library/API.js. This wrapper makes it easy to interact with the backend from within themes. You can find detailed documentation for using the wrapper here.

Box

File path: /src/library/Box

Named after BoxBilling (FOSSBilling’s predecessor), this folder contains some legacy classes that are being gradually improved and replaced.

Some examples of the types of classes found in this directory include classes for tools, translations, exception handling, custom Twig extensions, and more.

FOSSBilling

File path: /src/library/FOSSBilling

The “FOSSBilling” directory holds classes that are brand-new or rewritten classes since we’ve forked from BoxBilling. For the moment, these are mostly specific to the FOSSBilling core. Most module developers won’t need to interact with the classes here often, but it’s useful to know this is where new core features live.

Model

File path: /src/library/Model

The “Model” directory contains all of the models used in FOSSBilling. It is unlikely that you will need to make any changes to these files, but they can serve as a useful reference for the models implemented in the application.

Payment

File path: /src/library/Payment

The “Payment” directory is important and contains the library files for payment adapters and invoice handling.

For most developers, the subfolder src/library/Payment/Adapter will be of particular interest, as it contains the payment adapters for FOSSBilling. Here’s a guide to creating a payment gateway to help you along.

Registrar

File path: /src/library/Registrar

The “Registrar” directory holds the classes and files for domain registrar adapters used by FOSSBilling.

Actual adapters are inside src/library/Registrar/Adapter. If you want to create your own, here’s a guide to help you build a domain registrar integration.

Server

These are intended for shared hosting control panels like cPanel, Plesk, or HestiaCP. For more complex product types like VPS or game servers, consider creating a dedicated product module instead.

File path: /src/library/Server

This folder contains the classes and files for server managers. You’ll find the managers themselves under src/library/Server/Manager.

Documentation for creating a server manager can be found here.

Locale

File path: /src/locale

The “locale” folder contains all of the translations for FOSSBilling. These translations are stored in a separate repository and are included in the main repository as a submodule. When preview and release archives are generated, the submodule is updated to the latest version from the “locale” repository, including any new or updated translations compiled in the “.mo” format.

Modules

File path: /src/modules

The “modules” directory contains all of the modules for FOSSBilling. Modules provide flexibility and expandability in terms of functionality for the application. No two modules will be exactly the same, however there is a standard set of folders that each module may have.

Api - The “Api” folder defines the API functions for each FOSSBilling module. There may be separate files for different types of users, such as “Admin.php”, “Client.php”, and “Guest.php”. These files define the API calls that can be made based on the permission level of the user.
Controller - The “Controller” folder defines the controllers for the module. These controllers are similar to what some frameworks may refer to as “routes”. There may be separate files for different types of users, such as “Admin.php”, “Client.php”, and “Guest.php”. Each of these files corresponds to a specific type of user.
html_admin - The “html_admin” folder contains Twig templates for the module that are used within the admin panel.
html_client - The “html_client” folder contains Twig templates for the module that are used within the client dashboard
html_email - The “html_email” folder holds twig-enabled email templates related to the module.
manifest.json - The “manifest.json” file is the module’s manifest file, which defines various details about the module, such as its version, name, and description.
Service.php - The “Service.php” file defines the main functions and class for the module. These functions are not exposed through the API and are generally used to define the underlying functions that the API calls utilize to execute API functions.

Themes

File path: /src/themes

The “Themes” folder holds a directory for each theme that is installed inside of FOSSBilling. Themes should have the following file structure:

assets - This directory should hold theme assets such as JS, CSS, and images.
config - If the theme has configuration options, this folder will have a settings.html.twig file to define the configurable options for that theme.
html - This directory hold the twig templates used as the HTML for the theme. If needed, a theme can define custom pages for modules by naming a twig template to be the same name as the one the module uses which will then be loaded instead of the module’s template.
html_custom - An optional directory that end-users can use to provide templates which will take priority over all other templates. Themes should not place their templates here, as the purpose of this directory is to make customizing a theme easier.
manifest.json - The “manifest.json” file is the theme’s manifest file, which defines various details about the theme, such as its version, name, and description.

Every contribution, big or small, helps make the project better for everyone! If you need help with anything, don’t hesitate to reach out. Join our Discord community or create a new thread in our forums.

JavaScript API wrapper Twig Filters & Extensions