phpBB3 MODifications Database policy
The MODDB at phpBB.com has some requirements that must be met before a MOD is accepted to the MODDB.
Below are all of the requirements. If you have any questions or suggestions about this policy please create a topic in the [3.0.x] MOD Writers Discussion forum.
This policy has been updated at Wed Sep 14, 2011 5:57 pm, version $Rev: 3866 $.
Required changes to languages and templates
All MODs must include changes for the prosilver style and the English language. These changes should be placed in the install.xml file (See packaging guidelines and XML naming convention).
subsilver2 isn't required to be included within the MOD. Prosilver is required to be included.
What shouldn't be included?
It is not allowed to include pre-modded files in your MOD. This includes files within the contrib directory. Pre-modded files are core phpBB files with changes applied to them.
Privacy
For privacy reasons it is not allowed to send private information (including but not limited to posts, user information, etc.) to any remote website or remote server. Any MOD that does send information to a remote website or remote server will be denied for this reason.
Exceptions to this rule, although rare, will be handled on a case-by-case basis.
Function usage
Only functions that exist before and in PHP 4.3.3 may be used by default. If you want to use functions that were added in a later version of PHP you need to mention this requirement within the author notes.
Database specific functions should not be used (e.g. mysql_* etc.). Use phpBB's DBAL instead.
To retrieve a value from $_POST/$_GET you should always use phpBB3's request_var function. You should not access $_POST/$_GET directly. An exception is checking whether a variable is set, such as isset($_POST['submit']).
The second parameter for request_var must be set to the correct variable type (int, string, double etc.). The second parameter is the default value that is returned if the value doesn't exist. This default value is used to type cast the value that is returned. If you want an integer you can use 0 (without quotes!) as the second parameter in request_var.
Coding guidelines
The phpBB3 coding guidelines should be followed as much as possible. This means that all files should follow these guidelines, including installers, JavaScript, and HTML files. This is to ensure maximum readability by the phpBB Modifications Team. Third party libraries are the only exceptions and do not have to follow the coding guidelines. It is also required to use the English language for all table names, variable names and comments. The primary language for phpBB and MODs is English.
MODX usage
MODX is required for phpBB3 MODs. See our MODX Resource Center for more information about how to use and write MODX.
The latest MODX release should be used. This is currently 1.2.5. When you submit a new MOD or an update you always should check that you are using the latest version of MODX and the XSL.
You may edit the XSL but the preferred method is to use the prosilver XSL that we provide. For exact packaging see the packaging guidelines of this document.
MOD license
The submitted MOD should be submitted under the GPL v2. Submitting MODs GPL v3 isn't allowed because phpBB3 is released under GPL v2 only and the GPL v3 isn't compatible with v2.
You are also allowed to submit it under a license compatible with GPL v2. Be sure to change the license within the MODX install files and include a copy of the license in license.txt.
MOD packaging
The MODX packaging is completely new starting with MODX 1.2.0. These changes make the requirements less strict.
The following files must be included in your MOD:
- install.xml or other variations as long as it has the word install in it. This is the main install file.
- license.txt, the license of the MOD, so in most cases a copy of the GPL v2.
- modx.prosilver.en.xsl, the prosilver xsl for displaying the MOD in the browser of the user. This file must be included in either the directory containing the MODX xml file, or a subdirectory of that directory.
- All included 3rd party libaries should be the latest version of that libary at the moment of submission of the MOD.
Both the install.xml and the license.txt should be in the root of your zip file. modx.prosilver.en.xsl may be placed also in another directory, see below.
All changes to the phpBB core files should be placed in the install.xml file. Changes and file copies for non-English languages and non-prosilver templates should not be placed in this file. These should have a separate XML file, but should be linked to from the main install file using the link tag.
New files should always be placed in the root/ directory, including the non-English languages and non-prosilver templates.
If there are no changes for non-English languages or non-prosilver templates, but there are new files included, the MODX file for this specific language or specific template still needs to be included in the package.
Optional install files or instructions should be placed within the contrib directory. Additional required instructions should be placed in the root directory or in a directory called named xml/.
All filenames for included files should be in English.
If your MOD adds new permission to phpBB it is required to use UMIL. In all other cases it is strongly prefered to use UMIL for database changes.
XSL file
A security change in Firefox 3 has caused MODX xml files to display incorrectly when the xsl file is located outside of the directory containing the xml file. Due to this issue, we need to require that the xsl file is placed in either the same directory as the xml file, or a subdirectory within that directory. For the time being, we will repack all MODs that have not yet complied with this requirement.
Using UMIL
In case you want to use UMIL this need to included in the MOD package you submit to the MODDB. You need to include all required files to run UMIL in the package, without the need to download extra files.
See for more information regarding UMIL the dedicated UMIL pages.
XML naming convention
Required files
There are a few required files that should be named following a specific naming convention:
- install.xml: This is the main install file and should contain at least the text install, but its strongly prefered to have it named install.xml
- modx.prosilver.en.xsl: This is the XSL file for the MODX file. Its strongly prefered to have this named modx.prosilver.en.xsl, but we allow to change it.
In case this naming convention isn't followed we might deny the MOD for this.
Optional files
There are a few optional files that can be included in a MOD. This are mainly template and language files. These files have a strict naming convention that should be followed. In case this naming convention isn't followed the MOD will be denied.
- Additional template files: The filename for this should be TEMPLATE.xml, so in case for subsilver2 the name should be subsilver2.xml. Names as like install-subsilver2.xml, template-subsilver2.xml are not allowed.
- Additional language files: The filename for this file should be ISO_CODE.xml, in the case of the Dutch language it should be named like nl.xml, and in the case of English (United States) it should be en_us.xml. Names such as install-nl.xml, language-nl.xml are not allowed.
Externally hosted scripts
Please be aware that MODs referencing external sources (such as externally hosted Javascript files) will not be accepted into the MOD Database. Any files required by the MOD should be packaged with the MOD.
phpBB3 or MODX updates
MOD authors may re-submit their MODs for validation if the only changes are either:
- Updating the version of MODX used by the modification and the phpBB version which the MOD applies to.
- The phpBB version which the MOD applies to.
MODs re-submitted on this basis will still be reviewed and tested on the latest version of phpBB. Re-submissions reflecting a new MODX version alone will not be accepted.
Insta Deny
All MODs are checked by MPV after being submitted to be sure it follows this policy and some basic security checks. In case that a MOD fails these checks, the MOD will be insta-denied within 72 hours of submission. If you don't get a deny message from the MOD Team within 72 hours after you submitted your MOD, then it has passed this initial check and will be validated fully.
To make sure that your MOD passes Insta Deny you should check your MOD with MPV before you submit it. You can do this at our dedicated page for MPV, which can be found here. In case you dont understand the returned result of MPV you can open a topic in MOD Writters Discussion. Your question will be answered in that topic as soon as possible.
Times of validation
The MOD team can't give an exact time of how long the validation takes.
We always try our best to get your MOD validated within 2 weeks with a maximum time frame of 4 weeks. If you haven't heard anything from us after 4 weeks you should contact us by sending a message in the discussion part of the Customisation Database. This can be found by using the following path: My Contributions -> The MOD -> Discussion/Support -> MOD discussion.
Version numbers for your MOD
If you submit an update of your MOD you should always increase the version number. There should not be two revisions with the same version number.
Version numbers are meant to give a unique number to the code so that a user (or a validator or anyone else) can see what version was used. The version is specific to the code at the time it was released so if you change the code, the version number should be changed as well.