FOSSBilling File Structure
The file structure of FOSSBilling may be unfamiliar to new developers because it is not based on a modern framework. This guide aims to help developers understand the file structure of FOSSBilling in order to make contributions.
The main source code for FOSSBilling is located in the "src" (opens in a new tab) directory within the project repository. This directory contains most of the code for the project, with the exception of tests and a few other files. This guide will primarily focus on the source code found in the "src" directory.
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.
The "install" directory contains the files necessary for installing FOSSBilling, such as the installation wizard and default SQL content.
The "library" folder serves as a general library for the FOSSBilling application. It contains several subfolders, which hold various resources and code used by the application. In the following section, we will describe the contents of these subfolders.
src/library/API.js and is the most commonly used file in this directory. Documentation for the wrapper can be found here (opens in a new tab)
The "Box" directory is named after BoxBilling and holds classes that originate from BoxBilling code. Many of these classes are older and are in the prosses of being cleaned up and refactored into new FOSSBilling classes. Some examples of the types of classes found in this directory include classes for tools, translations, exception handling, custom Twig extensions, and more.
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 and don't provide functionality that many module developers will need to interact with.
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.
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, which extend the classes defined in the parent directory.
The "Registrar" directory holds the classes and files for domain registrar adapters used by FOSSBilling.
The actual adapters are located in the subfolder
src/library/Registrar/Adapter and extend classes from the parent directory.
The "Registrar" directory holds the classes and files for server managers used by FOSSBilling.
The actual server managers are located in the subfolder
src/library/Server/Manager and extend classes from the parent directory.
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" (opens in a new tab) repository, including any new or updated translations compiled in the ".mo" format.
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.
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, then this folder will have a
settings.htmlfile 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.
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.