- Joined
- Mar 22, 2026
- Messages
- 189
- Reaction score
- 0
Windows 10
Microsoft Edge 146
Developing custom add-ons for XenForo 2 allows you to extend its functionality, integrate with external services, or tailor the platform precisely to your needs. This guide will walk you through the fundamental steps to create a basic XenForo 2 add-on.
Prerequisites
Before you begin, ensure you have:
1. XenForo 2 Installation: A working XenForo 2 instance.
2. Development Mode Enabled: Add
3. Basic PHP Knowledge: Understanding of object-oriented PHP is crucial.
4. Text Editor/IDE: Such as VS Code, PHPStorm, etc.
Understanding the Add-on Structure
XenForo 2 add-ons follow a strict directory and naming convention. Each add-on resides within the
The basic structure looks like this:
For this guide, let's use
Step 1: Create the Add-on Directory Structure
First, create the necessary directories:
Step 2: Define Your Add-on with
The
Step 3: Install Your Add-on
Now that the basic structure and
1. Navigate to ACP -> Add-ons.
2. You should see "My First XenForo 2 Add-on" listed with an "Install" button. Click it.
3. XenForo will process the
At this point, your add-on is installed but doesn't do anything yet.
Step 4: Add Simple Functionality with an Event Listener
Let's make a simple listener that adds a message to the footer of every page.
1. Create a file
*
*
2. Register the Listener in ACP:
* Go to ACP -> Development -> Code Events.
* Click "Add code event listener".
* Event Hint:
* Callback Class:
* Callback Method:
* Add-on: Select
* Execute order: 10 (Default is fine).
* Save the listener.
3. Rebuild the Add-on Cache:
* Go to ACP -> Development -> Rebuild Caches.
* Click "Rebuild Master Data". This ensures your listener registration is picked up.
Now, refresh your forum's front-end. You should see "Hello from My First Add-on!" added to the footer.
Step 5: Exporting Your Add-on Data
When you create new templates, phrases, options, or other data through the ACP while your add-on is active, XenForo stores this information in the database. To make this data part of your add-on's files (so it can be installed on other forums), you need to "export" it.
1. Go to ACP -> Development -> Add-ons.
2. Find "My First XenForo 2 Add-on" and click the "Export" button next to it.
3. This will populate your
These files are crucial for distribution and version control.
Next Steps
This covers the absolute basics. From here, you can explore:
Developing XenForo add-ons is a powerful way to customize your forum. Always refer to the official XenForo developer documentation for detailed information on various concepts and best practices.
Prerequisites
Before you begin, ensure you have:
1. XenForo 2 Installation: A working XenForo 2 instance.
2. Development Mode Enabled: Add
$config['development']['enabled'] = true; to your src/config.php file. This enables helpful development tools and allows add-on creation via the ACP.3. Basic PHP Knowledge: Understanding of object-oriented PHP is crucial.
4. Text Editor/IDE: Such as VS Code, PHPStorm, etc.
Understanding the Add-on Structure
XenForo 2 add-ons follow a strict directory and naming convention. Each add-on resides within the
src/addons/ directory.The basic structure looks like this:
Code:
src/addons/
└── [VendorId]/
└── [AddOnId]/
├── _output/ (Generated files like templates, phrases, etc.)
├── addon.json (Core add-on definition file)
└── src/ (Your actual PHP code, listeners, controllers, entities)
└── Listener.php (Example: A simple event listener)
[VendorId]: This is your unique identifier (e.g., "XF", "MyCompany", "YourName"). It should be a short, uppercase, alphanumeric string.[AddOnId]: This is the unique identifier for your specific add-on (e.g., "HelloWorld", "ThreadPrefixes"). It should be a short, alphanumeric string, typically CamelCase.
For this guide, let's use
MyVendor as the VendorId and FirstAddon as the AddOnId.Step 1: Create the Add-on Directory Structure
First, create the necessary directories:
Code:
src/addons/MyVendor/FirstAddon/
src/addons/MyVendor/FirstAddon/_output/
src/addons/MyVendor/FirstAddon/src/
Step 2: Define Your Add-on with
addon.jsonThe
addon.json file is the heart of your add-on. It defines its metadata, version, and dependencies. Create src/addons/MyVendor/FirstAddon/addon.json with the following content:
JSON:
{
"legacy_addon_id": "",
"title": "My First XenForo 2 Add-on",
"description": "A simple add-on to demonstrate basic XenForo 2 development.",
"version_id": 1000010,
"version_string": "1.0.0 Alpha",
"developer": "MyVendor",
"developer_url": "https://example.com",
"faq_url": "",
"support_url": "",
"extra_urls": [],
"require": {
"XF": [2020000, "XenForo 2.2.0+"]
},
"icon": ""
}
version_id: An integer representing the version. XenForo uses this for updates. Conventionally,MAJOR.MINOR.PATCHbecomesMMPPCC(e.g.,1.0.0is1000000,1.0.1is1000010,1.2.3is1020300).require: Specifies dependencies, such as the minimum XenForo version.2020000corresponds to XenForo 2.2.0.
Step 3: Install Your Add-on
Now that the basic structure and
addon.json are in place, you can install the add-on through the XenForo Admin Control Panel (ACP).1. Navigate to ACP -> Add-ons.
2. You should see "My First XenForo 2 Add-on" listed with an "Install" button. Click it.
3. XenForo will process the
addon.json and install your add-on. It will also create the _output directory if it doesn't exist and populate it with a hashes.json file.At this point, your add-on is installed but doesn't do anything yet.
Step 4: Add Simple Functionality with an Event Listener
Let's make a simple listener that adds a message to the footer of every page.
1. Create a file
src/addons/MyVendor/FirstAddon/src/Listener.php:
Code:
php
<?php
namespace MyVendor\FirstAddon;
class Listener
{
public static function templaterMacroPreRender(\XF\Template\Templater $templater, &$type, &$template, &$name, array &$arguments)
{
// Only target the 'PAGE_CONTAINER' template's 'footer' macro
if ($template == 'PAGE_CONTAINER' && $name == 'footer')
{
$arguments['extraFooterHtml'] .= '<div>Hello from My First Add-on!</div>';
}
}
}
*
namespace MyVendor\FirstAddon;: This namespace must match your VendorId\AddOnId.*
templaterMacroPreRender: This is a common event listener that fires before a template macro is rendered. We're specifically targeting the PAGE_CONTAINER template's footer macro.2. Register the Listener in ACP:
* Go to ACP -> Development -> Code Events.
* Click "Add code event listener".
* Event Hint:
templater_macro_pre_render (This is the name of the event XenForo dispatches).* Callback Class:
MyVendor\FirstAddon\Listener (Your Listener class).* Callback Method:
templaterMacroPreRender (The static method within your Listener class).* Add-on: Select
My First XenForo 2 Add-on.* Execute order: 10 (Default is fine).
* Save the listener.
3. Rebuild the Add-on Cache:
* Go to ACP -> Development -> Rebuild Caches.
* Click "Rebuild Master Data". This ensures your listener registration is picked up.
Now, refresh your forum's front-end. You should see "Hello from My First Add-on!" added to the footer.
Step 5: Exporting Your Add-on Data
When you create new templates, phrases, options, or other data through the ACP while your add-on is active, XenForo stores this information in the database. To make this data part of your add-on's files (so it can be installed on other forums), you need to "export" it.
1. Go to ACP -> Development -> Add-ons.
2. Find "My First XenForo 2 Add-on" and click the "Export" button next to it.
3. This will populate your
src/addons/MyVendor/FirstAddon/_output/ directory with .xml files containing your add-on's data (e.g., code_events.xml for the listener we just created).These files are crucial for distribution and version control.
Next Steps
This covers the absolute basics. From here, you can explore:
- Phrases: Create custom text strings that can be translated.
- Options: Add configurable settings to your add-on.
- Templates: Create new templates or extend existing ones.
- Controllers: Handle user requests and display pages.
- Entities: Define custom database tables and interact with them using XenForo's ORM.
- Routes: Define custom URLs for your add-on's pages.
- Setup Class: Run database schema changes or initial data population during install/upgrade.
Developing XenForo add-ons is a powerful way to customize your forum. Always refer to the official XenForo developer documentation for detailed information on various concepts and best practices.
