¶ Architecture Concepts
Before diving into contributing to NamelessMC or creating your own modules, we recommend you have a good idea of how everything fits together to make NamelessMC work.
Please note, this may not always be 100% up to date - but we will certainly do our best to maintain it.
¶ Code Organization
99% of the files you will need to work with live inside 3 folders, core, custom and modules;
-
core- This folder contains "low level" code for NamelessMC.
- 3rd party JS + CSS libraries live in the
assetsfolder. - The built-in avatar service + cache reside in the
avatarfolder. - All the globally available classes go in
classes, and then specific folders within this folder.- We will review these in more detail later.
- The
includesfolder contains rarely edited files, such as the upgrade scripts, password encryption, etc. You will not need to worry about this folder unless you are making changes to NamelessMC itself. installationhas files for the installation process of NamelessMC.- Minecraft integration helpers go in
integration, but these will likely be moved to their own module soon. templatescontains template initialization files.backend_init.phpis run when StaffCP is being accessed. It defines Smarty variables which are used on most StaffCP pages such as$PANEL_LOGO_IMAGE,$PAGE_TITLEand$FAVICON.cc_navbar.phpdefines the$CC_NAV_LINKSSmarty variable which contains the side nav bar on the user's account page ("Overview", "Alerts", "OAuth", etc)footer.phpis executed on any frontend pages to assign social media Smarty variables, privacy & terms links, etc.frontend_init.phpdoes similar tasks as thebackend_init.phpfile, but for the frontend (shocking, I know!). This file checks if the user has outstanding infractions, or needs to validate their account, as well as define Smarty variables like$PAGE_DESCRIPTION(SEO) and$ANALYTICS_ID.navbar.phpgenerates the top navigation links (like: Alerts, StaffCP, and the users' dropdown) on the frontend, as well as setting the$NAV_LINKSSmarty variable to generate the main navigation bar.panel_navbar.phpsets Smarty variables for StaffCP side navbar such as$NAV_LINKS.
init.phpdoes a lot of heavy lifting during the initialization/booting phase of each request.- We will look at this more later.
-
custom- This contains template and language files - no PHP code is in here.
languagescontains a folder for each installed language, each with different files to help split our language terms into slightly more managable forms.- Please note, we are in the process of migrating away from this language system to a new JSON format which will be compatible with Weblate.
panel_templatescontains each of the installed StaffCP templates Smarty.tplfiles.templatescontains each of the installed frontend templates Smarty.tplfiles.
-
modules- This contains a subfolder for each of the installed modules.
- Most logic for NamelessMC (after the initialization/booting phase) happens here.
- There are 4 built-in modules with NamelessMC (Core, Discord Integration, Forums, and Cookie Consent). These all share a similar file structure, which we will generically highlight here. Please note that not all modules share the same structure!
- Check out our Module Documentation to learn more about the process of creating modules.
init.phpis ran during the initialization phase of NamelessMC on each of the installed & enabled plugins. This creates an instance of the module's main class.module.phpthis contains the module's main class (often named<module name>_Module) which extends the built-inModuleclass.classesthis folder contains PHP classes specifically used by this module. It is generally not safe to use these classes in other modules.hooksthis folder contains listeners for NamelessMC events, such asuserValidatedorreportCreated.includesfolder houses a couple important things:- API endpoint classes (
endpointssubfolder, typically) - Widget configuration pages (
admin_widgetssubfolder mainly)
- API endpoint classes (
pagesis where 90% of the code for most modules lives.- A good rule of thumb to make NamelessMC development as easy as possible is to organize your
pagesPHP code folder the same as your Smarty.tplfolder.- For example,
modules/Core/pages/login.phprelated Smarty file iscustom/templates/DefaultRevamp/login.tpl, andmodules/Core/pages/user/oauth.phpSmarty file iscustom/templates/DefaultRevamp/user/oauth.tpl. - This makes it a lot easier to remember where to look for files and where to place new files. All built-in NamelessMC modules follow this rule!
- For example,
- A good rule of thumb to make NamelessMC development as easy as possible is to organize your
queriesthis contains PHP files which are often called in the background using AJAX, these often return raw JSON. Think of them as internal API endpoints.- Note that NamelessMC will have fully booted by the time these files are executed, so you can do anything in them that you could do in a "normal" file.
- Example:
admin_users.phpin the Core module returns a list of all registered users to render in the StaffCP -> User Management page.
widgets, self explainitory hopefully - this contains all of this module's widget classes.
¶ Builtin Classes
Our classes are split into a few subfolders to help organize them a bit. We will explain the use of each folder, and then explain the use of each of the classes in the "Core" folder - since these are the most commonly used classes by external modules.
¶ Organization
Note that although they are split into subfolders, we do not use PHP namespaces! This is unlikely to change in the future.
Avatars- This folder contains the base classes for our extendable avatar system.
Collections- This folder contains classes to help manage and create Collections.
- Collections are used for StaffCP statistics and StaffCP info items such as "Recent Users", "Recent Reports", etc. Think of them as fancy arrays.
Core- This folder contains the most widely used classes that cover a large portion of functionality throughout NamelessMC.
- We will give more information about each of these classes later.
Database- This folder contains classes used to interact with the database, as well as the
QueryRecorderclass which records all queries made during a request to display on the stack trace page if an exception occurs.
- This folder contains classes used to interact with the database, as well as the
Endpoints- This is where all of the classes to manage and create API endpoints go.
Events- This folder has the
EventHandlerclass which lets modules listen for events and executes said events.
- This folder has the
Group_Sync- This folder contains the
GroupSyncManagerclass which handles group sync logic, as well as theGroupSyncInjectorinterface which modules can implement to create custom injectors for the group syncronization function of NamelessMC.
- This folder contains the
Minecraft- This folder houses classes which are used to interact with Minecraft servers.
Misc- Finally, this folder contains classes which don't fit in another folder. Usually these classes are only used by NamelessMC itself.
¶ Class Usage
To learn how to use our classes, check out our PHPDoc site, or out the source code of NamelessMC to see how we use them. Feel free to ask for support on how to use them in our Discord too!
¶ Request Lifecycle
Perhaps the most common question from new NamelessMC contributors: "how the heck does all of this fit together?".
-
The entry point for most requests is the
index.phpfile in the root of any NamelessMC installation.- This file handles low level initialization such as checking if debug mode is enabled, checking the PHP version, and setting
php.inivariables.
- This file handles low level initialization such as checking if debug mode is enabled, checking the PHP version, and setting
-
Control is then passed to the
core/init.phpfile to continue booting the application before the request is given back to theindex.phpfile.core/init.phpdoes a lot of stuff to help get things up and running:- Execute the Composer autoloader
- Register exception handlers
- Start the session
- Makes sure config & cache locations are writable
- Configure Cache instance
- Define global constants such as
FORCE_SSL,FRIENDLY_URLS,NAMELESS_VERSIONetc - Does redirects if force HTTPS is enabled
- Enables showing PHP errors if debugging is enabled
- Enables PHPDebugBar if debugging is enabled
- Creates global user instance (logs them in if they have an existing session)
- Sets timezones, language and templates based on user preferences or defaults to fallback settings
- Checks for maintenance mode and redirects if needed
- Initializes navigation menus + pages
- Runs each module's
init.phpfile (usually the constructors!)- The module constructors is where they should add pages, add navigation buttons,register events/listeners and do other generic tasks.
- Checks if user is banned + redirects them if so
- Updates user last_online stat + IP
- Redirects if user has a group with TFA forced
- Assigns some Smarty variables based on the user's state (StaffCP links, etc)
-
After all of these tasks have been completed, control is given back to
index.phpto handle routing.- If Nameless has not been installed yet, redirect to
install.php. - If the route in the URL is not valid, redirect to
404.php. - Check for a page registered with the current route and redirect to it if it is valid.
- This also handles checking if it is a custom page or not.
- If Nameless has not been installed yet, redirect to
-
Assuming all went well, control has been given to the module's PHP file for the page the user is visiting. For this example we will use the
modules/Core/pages/home.phpfile since it is basic but contains all the generic pieces.- This page is the homepage of a NamelessMC site, so it will display news, have widgets, and occasionally show errors/success messages.
- Remember that NamelessMC is prodecural, so all variables defined during the initialization of Nameless are still available.
- This file does the following tasks:
- Defines the
PAGEconstant - Executes
core/templates/frontend_init.php(we discussed this file earlier!) - Adds page-specific CSS and JS files
- Flashes session variables to display (success/error messages)
- Runs
Module::loadPage(...)- This calls the
onPageLoad(...)method on all enabled modules!
- This calls the
- Ends the page load timer
- Calls
$template->onPageLoad()- This is where templates will add more CSS and/or JS files or links
- Assigns widget Smarty variables
- Runs the
core/templates/navbar.phpandcore/templates/footer.phpfiles (we discussed these earlier!) - Finally, it displays its Smarty
.tplfile that is shown to the user
- Defines the
The request is complete! 
A (bad) visual representation of this process:
